Collapse AllExpand All

13.1.2. Credit Card

The system supports several credit card verification services, including Authorize.Net and CyberSource. The recording of credit card transactions is also supported, even if an approved verification service is not being used.

Tip

Once you've confirmed with your bank which payment gateway you want to use, contact the gateway to set up a merchant account. The merchant account details are needed before you can configure xTuple to use payment gateways.

To configure your system to process credit cards, go to System > Setup > Configure > Credit Card. The following screen will appear:

Configure general Credit Card options

When establishing the general settings for your credit card configuration, you are presented with the following options:

Accept Credit Cards

Select to indicate the system is configured to accept credit card payments. If selected, the credit card processing functionality will be enabled throughout the system. For example, users will be able to store customer credit card information on the Customer master—and receive credit card payments when processing sales orders. If this option is not selected, credit card functionality will be disabled.

Work in Test Mode

Select if your site is testing the credit card configuration and functionality. If selected, the system will verify that the server specified under the Server tab is in fact the correct test server. If this option is not selected, the system will verify that the correct production server is specified.

Warning

Make sure that you uncheck this option as soon as you are ready to put the application into production. Most credit card transactions will appear to succeed whether running in test mode or live mode but there will be no actual charges made if in test mode.

If you are using Authorize.Net then you should also make sure that the Merchant Interface is configured to run in live mode instead of test mode. Both xTuple ERP and the Authorize.Net gateway allow sending test transactions to the live server but both applications must be set to run in live mode for real transactions to occur.

Verification Service

Specify the credit card verification service you will be using:

Authorize.Net

Select if you will be using the Authorize.Net payment gateway for handling credit card transactions. If selected, specific Authorize.Net options will be enabled on the screen. Please be aware that xTuple only supports the card not present (CNP) account type through Authorize.Net. The card present (CP) account type is not currently supported. Authorize.Net has also deprecated its support for multiple currencies per account.

CyberSource

Select if you will be using the CyberSource payment gateway for handling credit card transactions. Specific CyberSource options will be enabled on the screen if you select this service.

External

Select if you will be using tools outside of xTuple ERP to communicate with your credit card company. If selected, you may still process credit card transactions in xTuple ERP—and this information will be stored in your xTuple database. However, no information will be sent to outside credit card processors. You can learn more about the interface used to collect external credit card transactions in Section 13.1.2.1, “External Credit Card Transaction”.

Confirm Transaction

Specify when you want to application users to confirm transactions before they are processed:

Pre-Authorization

Select if you want confirmation before pre-authorizing charges on a credit card.

Direct Charge

Select if you want confirmation before directly charging a credit card.

Charge Pre-Authorization

Select if you want confirmation before posting pre-authorized charges.

Credit

Select if you want confirmation before crediting back charges on a credit card.

Enable Transaction on sales Order

Select which of the following options should be enabled under the Payments tab of the sales order header. This setting does not affect the Receivables workbench or any other window in the application.

Pre-Authorization

If selected, only the AUTHORIZE button will be enabled.

Direct Charge

If selected, only the CHARGE button will be enabled.

Number of days Pre-Authorizations are valid for

Select a value between one and 30 using the arrows located to the right of the field. Value entered specifies the number of days pre-authorizations will remain valid from the date they were entered. Once a pre-authorization expires, it will no longer be visible in the system and will be unavailable for post-authorization.

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. This selection allows you to track American Express transactions and reconcile them against statements provided by your credit card processing company.

Discover

Select a bank account to use for Discover transactions. This selection allows you to track Discover transactions and reconcile them against statements provided by your credit card processing company.

Master Card

Select a bank account to use for Master Card transactions. This selection allows you to track Master Card transactions and reconcile them against statements provided by your credit card processing company.

Visa

Select a bank account to use for Visa transactions. This selection allows you to track Visa transactions and reconcile them against statements provided by your credit card processing company.

Other

Select if you want to specify a different default bank account than those listed.

General Options
Print Receipts

Select if you want the ability to print credit card receipts.

Fraud detection methods vary depending on the payment gateway used. Authorize.Net requires fraud settings to be configured on the gateway server. Other services send fraud detection results back to the client software and require the client to decide whether to accept the transaction or void it. To configure client-side fraud detections settings, if required, select the Fraud Detection tab. The following screen will appear:

Configure Credit Card Fraud Detection

Tip

If the CyberSource service is being used, the options on the Fraud Detection tab will be enabled and selections should be made. These options will be disabled if the Authorize.Net gateway is being used. Fraud detection settings for Authorize.Net must be configured through the Merchant Interface.

When configuring client-side fraud detection settings, if required, you are presented with the following options:

Require Card Verification Value/Code (CVV)

Select if you want to require users to enter a credit card verification value (CVV) code when processing credit cards.

Card Verification

Specify how you want to handle credit card verification processing:

Do not check

Select if the xTuple application should ignore the CVV result sent by the payment gateway.

Warn if failure

Select if the xTuple application should tell the user if the CVV result sent by the payment gateway fails based on the criteria checked in the Fail CVV Check If section.

Reject if failure

Select if the xTuple application should void the transaction and tell the user if the CVV result sent by the payment gateway fails based on the criteria checked in the Fail CVV Check If section.

Fail CVV Check If:

Specify how you want to handle CVV check failures:

Code Does Not Match

Select if the transaction should be treated as fraudulent if the CVV does not match the credit card number.

CVV Was Not Processed

Select if the transaction should be treated as fraudulent if the credit card company, such as Visa or American Express, could not process the CVV for the payment gateway.

Card Had No Code

Select if the transaction should be treated as fraudulent if the credit card does not have a CVV but is expected to have one.

Card Issuer Is Not Certified

Select if the transaction should be treated as fraudulent if the financial institution that issued the credit card is not certified.

Address Verification Service

Specify how you want to handle address verification:

Do not check

Select if the xTuple application should ignore the AVS result sent by the payment gateway.

Warn on Failed AVS Check

Select if the xTuple application should tell the user if the AVS result sent by the payment gateway fails based on the criteria checked in the Fail AVS Check If section.

Reject on Failed AVS Check

Select if the xTuple application should void the transaction and tell the user if the AVS result sent by the payment gateway fails based on the criteria checked in the Fail AVS Check If section.

Fail AVS check if:

Specify how you want to handle address verification check failures:

Address Does Not Match

Select if the transaction should be treated as fraudulent if the address stored by the xTuple application does not match the credit card company's recorded billing address for the credit card.

Address Comparison Not Available

Select if the transaction should be treated as fraudulent if the credit card company could not process the street address information for the payment gateway.

ZIP Does Not Match

Select if the transaction should be treated as fraudulent if the postal code stored by the xTuple application does not match the credit card company's recorded billing address for the credit card.

ZIP Comparison Not Available

Select if the transaction should be treated as fraudulent if the credit card company could not process the postal code information for the payment gateway.

To establish the server settings for your credit card configuration, select the Server tab. The following screen will appear:

Configure Credit Card Server

When establishing the server settings for your credit card configuration, you are presented with the following options:

Server Name

Enter the URL for the specified verification service's server—or, leave this field blank to automatically use the correct default URL. If you manually enter a URL, keep in mind that the address needed may vary depending on whether you are working in test mode or production mode. By leaving this field blank, you can be assured the correct default path will always be used.

Port

Enter the port number for the specified verification service's server. If this is left empty then the application will use the default port for this verification service.

Login

For Authorize.Net, use your API login here, not your merchant interface login, which may differ.

Password/Transaction Key

Enter either the password or transaction key for the selected verification service. The label for this field will change depending on the verification service being used.

Use Proxy Server

Select if your site uses a proxy server.

Server Name

Specify the IP address for your proxy server.

Port

Specify the port used by your proxy server.

Login

Specify the login name for your proxy server.

Password

Specify the password for your proxy server.

Tip

You can leave the Server Name and Port fields blank if you desire. This is the easiest way to switch between test mode and production mode, as you won't have to change these values every time you switch modes.

Some payment gateways, such as Authorize.Net, allow testing against the live, production server. If you want to run test transactions against the live payment gateway then you must set the server name explicitly to the live payment gateway's URL. You will get a warning from the application when you click the SAVE button if you do this.

To establish the service option settings for your credit card configuration, select the Service Options tab. The options will vary depending on the payment gateway being used. For example, the CyberSource and external methods do not require service options to be entered. However, if Authorize.Net is being used, the screen will appear as follows:

Authorize.Net Service Options

When establishing the service option settings for your Authorie.Net configuration, you are presented with the following options:

Transaction Version

Authorize.Net supports three different versions of the communications protocol at this time, with the potential for more to be added in the future. The xTuple application builds transaction requests which conform to version 3.1 of the Authorize.Net protocol. This field is a placeholder to allow for future expansion by both xTuple and Authorize.Net.

Delimiting Character

This field allows overriding the default character used by Authorize.Net to separate parts of the messages sent by the gateway to the client application. If this field is blank then Authorize.Net will use the comma (,) to separate message fields. If you expect your data to contain commas as part of their content, such as street addresses, then you should change the delimiting character.

Encapsulating Character

This field allows setting the character used by Authorize.Net to enclose individual parts of the messages sent by the gateway to the client application. If this field is blank then Authorize.Net will not use any character for this purpose.

Warning

You should set the encapsulating character to a value. Otherwise some transactions may fail with an error reporting that the response from the payment gateway has the wrong number of fields.

Several of these configuration options may be set through the Authorize.Net merchant interface. If you set any of these options there, you must use exactly the same values here in the Service Options tab. If you do not then most or all of your credit card transactions will fail, often with mysterious errors.

If you want to use the MD5 Hash feature, you must set it to exactly the same value here and on the merchant interface, including spaces and capitalization.

You may set the delimiting character, encapsulating character, duplicate window, and currency of transactions in the xTuple application without setting them through the Authorize.Net merchant interface.

Duplicate Window

Use this field to indicate a time window to Authorize.Net for checking for duplicate transactions. If similar transactions are sent to Authorize.Net within this window then it may reject them as duplicates. This is a value in seconds.

Important

As of March 2019, Authorize.net phased out the MD5 based hash previously used for transaction response verification in favor of the SHA-512 based hash utilizing a signature key. If you are running an xTuple ERP version prior to 4.12, you must disable the Authorize.net MD5 hash features on the xTuple credit card configuration screen.

Signature Key

Enter the signature key code supplied to you by Authorize.net.

Check Signature Key

Select if you want the application to verify the signature key. If not selected, the verification will not be performed.

Fail if key check fails

Select to fail a transaction if the key check fails.

Warn if key check fails

Select to raise a warning if the key check fails.

Currency of Transactions

Specify how you want to handle foreign currency transactions:

Always Use

Select to always use the currency specified here for all credit card transactions.

Additional Options

You have the option to specify the following additional options:

Using Wells Fargo SecureSource

Check this box if you are using Authorize.Net with Wells Fargo SecureSource. Wells Fargo SecureSource requires that transaction requests be built slightly differently than pure Authorize.Net transactions and this configuration option tells the xTuple application to construct the transactions to work with this service.

Ignore SSL Errors

Select if you want xTuple ERP to ignore Secure Sockets Layer (SSL) errors when connecting to the Authorize.Net gateway.

To establish the key file settings for your credit card configuration, select the Key File tab. The following screen will appear:

Configure Credit Card Key File

Tip

All users on your system who need access to credit card information must use the same key file. The key file can be a simple text file with any contents whatsoever. It should be stored at the same level as the xTuple executable file. For Mac users, this would be within the MacOS directory inside the package contents for your xTuple executable. The key file is not stored in the database.

Caution

It is very important that you keep a backup copy of your encryption key in a safe location. If you lose your encryption key and do not have a backup copy, you risk losing access to your encrypted data.

When establishing the key file settings for your credit card configuration, you are presented with the following options:

Key File Name

Enter the name of your key file. The encryption key information may be entered on this screen, or on the Encryption screen—and vice versa. The key file is an encryption seed file, which enables you to read encrypted credit card information. The key file is required regardless of the verification service used at your site. The contents of the key file should be at least 16 characters long and use a combination of upper and lower case letters and numbers. Special characters should not be used.

Note

If you change the contents of your key file after it has already been in production, steps must be taken to convert any data encrypted up to that point. The function "alterencrypt" must be used to handle the conversion. Please contact your systems administrator for more information.

Windows Location

Specify the directory path any Windows machine on your system would use to access the key file. All users and machines on the system must use the same key file. To ensure consistency and security, the file should be stored in a central location.

Tip

If you name the key file "xTuple.key" and place it in the installation directory, then you do not need to enter the path.

Linux Location

Specify the directory path any Linux machine on your system would use to access the key file. All users and machines on the system must use the same key file. To ensure consistency and security, the file should be stored in a central location.

Mac Location

Specify the directory path any Mac machine on your system would use to access the key file. All users and machines on the system must use the same key file. To ensure consistency and security, the file should be stored in a central location.

13.1.2.1. External Credit Card Transaction

If you are using an external credit card processing mechanism to record information about xTuple ERP credit card transactions, the following screen will be used when these transactions are recorded:

External Credit Card Transaction

When entering details related to an external credit card transaction, you are presented with the following options:

Customer

Displays the name of the customer you are entering a credit card transaction for.

Credit Card Number

Displays the selected credit card for the specified customer.

Transaction Type

Displays the transaction type (i.e., charge).

Amount

Displays the amount of the transaction.

Order

Displays the number of the order (e.g., sales order, cash receipt, etc.) which the selected credit card is being charged for.

Approval Status

Specify the status of the external credit card transaction. The following options are available: approved, declined, error, and held for review.

Approval Code

Enter the approval code you received from the external credit card processor.

Transaction ID

Enter the transaction identifier you received from the external credit card processor. By default, this value will be the same as the order number.

Passed Address Verification

Select if the external transaction passed the address verification.

Passed Card Verification

Select if the external transaction passed the card verification.