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.
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
. The following screen will appear:When establishing the general settings for your credit card configuration, you are presented with the following options:
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.
Select if your site is testing the credit card configuration and functionality. If selected, the system will verify that the server specified under the
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.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.
Specify the credit card verification service you will be using:
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.
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.
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”.
Specify when you want to application users to confirm transactions before they are processed:
Select if you want confirmation before pre-authorizing charges on a credit card.
Select if you want confirmation before directly charging a credit card.
Select if you want confirmation before posting pre-authorized charges.
Select if you want confirmation before crediting back charges on a credit card.
Select which of the following options should be enabled under the
tab of the sales order header. This setting does not affect the Receivables workbench or any other window in the application.If selected, only the
button will be enabled.If selected, only the
button will be enabled.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.
Specify the default bank accounts to be used when receiving cash from customers using the following types of credit cards:
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.
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.
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.
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.
Select if you want to specify a different default bank account than those listed.
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
tab. The following screen will appear:If the CyberSource service is being used, the options on the
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:
Select if you want to require users to enter a credit card verification value (CVV) code when processing credit cards.
Specify how you want to handle credit card verification processing:
Select if the xTuple application should ignore the CVV result sent by the payment gateway.
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.
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.
Specify how you want to handle CVV check failures:
Select if the transaction should be treated as fraudulent if the CVV does not match the credit card number.
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.
Select if the transaction should be treated as fraudulent if the credit card does not have a CVV but is expected to have one.
Select if the transaction should be treated as fraudulent if the financial institution that issued the credit card is not certified.
Specify how you want to handle address verification:
Select if the xTuple application should ignore the AVS result sent by the payment gateway.
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.
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.
Specify how you want to handle address verification check failures:
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.
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.
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.
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 tab. The following screen will appear:
When establishing the server settings for your credit card configuration, you are presented with the following options:
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.
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.
For Authorize.Net, use your API login here, not your merchant interface login, which may differ.
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.
Select if your site uses a proxy server.
Specify the IP address for your proxy server.
Specify the port used by your proxy server.
Specify the login name for your proxy server.
Specify the password for your proxy server.
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
button if you do this.To establish the service option settings for your credit card configuration, select the
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:When establishing the service option settings for your Authorie.Net configuration, you are presented with the following options:
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.
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.
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.
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 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.
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.
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.
Enter the signature key code supplied to you by Authorize.net.
Select if you want the application to verify the signature key. If not selected, the verification will not be performed.
Select to fail a transaction if the key check fails.
Select to raise a warning if the key check fails.
Specify how you want to handle foreign currency transactions:
Select to always use the currency specified here for all credit card transactions.
You have the option to specify the following additional options:
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.
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 tab. The following screen will appear:
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.
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:
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.
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.
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.
If you name the key file "xTuple.key" and place it in the installation directory, then you do not need to enter the path.
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.
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.
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:
When entering details related to an external credit card transaction, you are presented with the following options:
Displays the name of the customer you are entering a credit card transaction for.
Displays the selected credit card for the specified customer.
Displays the transaction type (i.e., charge).
Displays the amount of the transaction.
Displays the number of the order (e.g., sales order, cash receipt, etc.) which the selected credit card is being charged for.
Specify the status of the external credit card transaction. The following options are available: approved, declined, error, and held for review.
Enter the approval code you received from the external credit card processor.
Enter the transaction identifier you received from the external credit card processor. By default, this value will be the same as the order number.
Select if the external transaction passed the address verification.
Select if the external transaction passed the card verification.