+1-757-461-3022 x124

Payment Gateways Extension for xTupleCommerce


The xTuple Payment Gateways package is an xTuple extension that is needed to support the processing of credit card transactions on xTupleCommerce web portals. If you are running xTupleCommerce and you want to allow your customers to make purchases with credit cards, then you must have the xTuple Payment Gateways package installed and configured in the ERP.

It is important to note that the Payment Gateways package is designed to replace the credit card processing features that come standard with xTuple ERP. When the Payment Gateways package is installed and enabled, the standard credit card system will be disabled. The two methods cannot be operating at the same time. That said, the Payment Gateways package provides a utility to migrate existing credit card related data to the new method. See below for more information about the Payment Gateways migration utility.

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 impacts credit card processing in the ERP.

How it Works

Both xTupleCommerce and xTuple ERP integrate with payment gateways (e.g., Authorize.net, Stripe) to handle credit card transactions. The following graphic illustrates how the credit card process works, starting from the point when an order is placed on xTupleCommerce:

  1. xTupleCommerce submits the shopping cart, along with the credit card information, to the ERP via a REST API.

  2. The REST API submits a request to the payment gateway for a pre-authorization of the order amount. 

  3. If the pre-authorization fails, the new order is rejected by the ERP and the shopping cart remains active for the consumer to fix their credit card details.

  4. If the pre-authorization succeeds, the order is submitted to the ERP along with a pre-authorization token.

  5. When it is time to ship the order and charge the credit card, the ERP submits a "capture" request to the payment gateway for the order total along with the pre-authorization token.

  6. If the pre-authorization is no longer valid and the capture fails, an error is shown to the user.

  7. If the capture is successful, the credit card is charged and a cash receipt is created in the ERP.

The same processing steps are followed when a sales order with a credit card charge is created using the xTuple ERP desktop client.

In the steps described above, you may have noticed the use of the term "token." The reason for this is that the actual credit card information is stored on the payment gateway. With the Payment Gateway package, xTuple does not store any credit card information in the database. Rather, it encrypts the data and sends it to the payment gateway, who then returns a token for the information. xTuple stores the token, which represents the credit card information, and uses it to manage credit card transactions, including pre-authorizations, payment captures, and refunds.

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: Authorize.net 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

With xTuple version 4.11 the payment gateway was introduced. 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:

    • 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.

36 users have voted.