Payment Gateways package


The xTuple Payment Gateways package is an optional extension designed to support the processing of credit card transactions in a robust and flexible manner. When installed and enabled, the package replaces the credit card processing features that come standard with xTuple ERP.

Note: One of the key reasons to use the Payment Gateway package is that it only stores credit card "tokens" in the xTuple database. The actual card numbers themselves are stored on the servers of the gateway provider (e.g.,, etc.) 

In this article we will explain how to install and configure the xTuple Payment Gateway package, as well as provide some examples of how the package features operate in the ERP.

Installing the Package

To install the xTuple Payment Gateways package, you will need the following:

  • Updater- The Updater application is used to install packages into xTuple ERP. Please see the Updater documentation for more information on where to get and how to use this application.
  • Payment Gateways package (paymentgateways.gz) - This is the Payment Gateways package file, which gets loaded into xTuple ERP with the Updater. Like all xTuple database install/upgrade scripts, the file ends with a .gz extension.

Once the two required packages are installed, be sure to grant payment gateway privileges to any users who will be configuring and/or using the package.

Configuring the Package

To configure the Payment Gateways package, go to System > Setup > Configure > Payment Gateways. The following screen will appear:


Payment Gateways Configuration

When configuring payment gateways, you are presented with the following options:

  • Payment Gateway Services - Shows a list of the payment gateway services that are currently set up in the database. Two payment gateways are currently supported: and Stripe. Only one gateway can be active at a time.
  • Default Bank Accounts - Specify the default bank accounts to be used when receiving cash from customers using the following types of credit cards:
    • American Express - Select a bank account to use for American Express transactions.
    • Discover - Select a bank account to use for Discover card transactions.
    • Master Card - Select a bank account to use for Master Card transactions.
    • Visa - Select a bank account to use for Visa transactions.
    • Other - Select if you want to specify a different card/bank combination.
  • Print Receipts - Select if you want the ability to print credit card receipts.
  • Send Receipt - This option can only be checked if Print Receipts is enabled. Check this option if you would like the payment gateway to send an email of the receipt to the customer.

Before you can create a new payment gateway service, you must have an encryption key defined and configured. Please see the Reference Guide section on setting up encryption keys for more information. To define a new payment gateway service, select the NEW button, the following screen will appear:


Payment Gateway Service

When defining a new payment gateway service, you are presented with the following options:

  • Name - Enter a name to identify the payment gateway service.
  • Gateway - Select a payment gateway service from the available options. The required information will vary, depending on which gateway service you chooce. Currently, the supported gateways include Authorize.Net and Stripe. However, the software allows for additional gateways to be added.
  • Bank Account - Specify the bank account you want to connect with the payment gateway service.
  • Active - Indicate whether the service is active or not. You can have only one active gateway service at a time.

Migrating Credit Card Information

The payment gateway functionality was introduced with xTuple version 4.11.  When switching from xTuple's old credit card system to the new payment gateway system,, credit cards must be migrated from the database to the payment gateway. A credit card migration utility is available to move existing information to the payment gateway. After all cards have been migrated or deleted, click QUERY to ensure no results are returned. Then (IMPORTANT!) make sure to click the TRUNCATE CCARDAUD button to remove all remaining old credit card data from the database to ensure credit card numbers are no longer stored anywhere in the xTuple database. Moving this information to the payment gateway is mandatory to continue to process credit card payments. This section describes the Credit Card Migration utility.

Note: We strongly recommend that you test the migration process thoroughly, before attempting to migrate all your credit card information at once. For example, try migrating one card at a time. Then navigate to the credit card gateway's website to verify the data was migrated successfully.

Migrate credit cards by going to System > Utilities > Payment Gateway > Migrate Credit Cards. Click QUERY to populate the screen with the information to be migrated. The following screen will appear:


Migrate Credit Cards

When migrating credit cards from the legacy system, you are presented with the following options:

  • QUERY - Select this button to generate a list of encrypted credit cards you have on file in your database. Credit card information is displayed by customer. Specific credit card information can be selected and migrated or everything listed can be migrated in one step. Expand the customer summary line to select specific credit cards to migrate or delete.
  • Migrate Card(s) - Migrates the selected credit card(s) into the payment gateway. You can select multiple cards, using a combination of the SHIFT and CTRL keys. Alternatively, if no cards are selected, this option will migrate all cards by default. Once migrated the credit card information is automatically removed from the database.
  • Delete Card(s) - Prior to migrating your credit cards, you should get rid of any records you don't need to keep. This button removes the selected credit card(s) from the ERP database. You can also choose to delete only expired and/or inactive cards. If no cards are selected, and if the Delete All Expired and Delete All Inactive options are not selected, this button will delete all cards by default.
    • Delete All Expired - Select to delete all expired credit cards when the DELETE CARDS button is pushed. May be used in conjunction with the Delete All Inactive option. When used, only expired and/or inactive cards will be removed.
    • Delete All Inactive - Select to delete all inactive credit card records when the DELETE CARDS button is pushed. May be used in conjunction with the Delete All Expired option. When used, only expired and/or inactive cards will be removed.
  • Truncate CCardaud - After all cards have been migrated or deleted, truncate credit card tracking information from the database by clicking on the TRUNCATE CCARDAUD button. This will remove any remaining traces of the card information.
  • Output Log - Displays log information related to actions performed, to assist with troubleshooting.

Capturing Cards During Sales Order Entry

The user experience for capturing customer credit cards using the Payment Gateway package is similar to, but different from, the legacy method. The following screenshot illustrates the Payment tab on a sales order. This example is taken from an xTuple database where the Payment Gateway package is installed:


Sales Order - Payment Tab

In the screenshot you can see that an existing credit card is "on file" for the customer, and so this card can be used for the sales order transaction. Of course, the card is on file with the payment gateway, not stored in the xTuple database. If you need to add a new payment method, select the NEW button. The following screen will appear:


Sales Order - Adding New Payment Method

When adding a new payment method, you are presented with the following options:

  • Default Payment Method - Select if this payment should be treated as the customer's default payment method.
  • Save for later - Select to save the card information for retrieval and use at a later date. The card information will be saved on the payment gateway.
  • Credit Card - Select if the payment method is a credit card. Enter the credit card details in the fields provided.
  • Bank Account - Select if the payment method is a bank account. Enter the bank account details in the fields provided.

Entering Cash Receipts

Credit card payments can also be taken using the Cash Receipts screen, as shown below:


The method for capturing credit card information on the Cash Receipt screen is the same as it is on the Sales Order screen.