Set up and configure an Ingenico ePayments GlobalCollect gateway instance
Set up and configure an Ingenico ePayments GlobalCollect gateway instance by using the information in this article, including prerequisites, configuration procedure, descriptions of the configuration fields, and reference for testing the payment gateway.
New instances of this gateway are not supported. Please use Ingenico ePayments instead.
IP address whitelist configuration
This gateway requires adding Zuora EU or US Cloud Data Center IP addresses to the whitelist for each of your gateway merchant accounts, depending on which data center that your tenant is located at. Therefore, before start using this gateway on Zuora EU or US Cloud Data Center, you must contact with the gateway to add Zuora EU or US Clould Data Center IP addresses to the gateway's whitelist for both the Sandbox and Production environments so that both environments can work properly.
For more information about the Zuora EU or US Cloud Data Center IP addresses, see Outbound IP Addresses Whitelisting.
Ingenico ePayments GlobalCollect Merchant Account Configuration
Work with your Ingenico ePayments GlobalCollect implementation manager to ensure your Ingenico ePayments GlobalCollect merchant account is configured to support a two-step payment process for Sale transactions. To do this, Ingenico ePayments GlobalCollect will configure the delayed settlement per card type setting in your account by setting the indicator to the value to 7. This ensures the payment transactions are pending until triggered via the
set_payment for settlement.
Clarification on API calls for Sale transactions:
For Sale transactions, the integration uses a two-step process with the following Ingenico ePayments API calls:
Insert Order With Payment()+
Insert Order with Payment()- This call inserts an order and a payment in a single API call combining the
Insert Order()and a
Do Payment()action in a single call.
SetPayment- This call is used to settle authorized credit card payments or to register mandates for direct debit.
Error if Account is Not Configured for Two-Step Sale Process
It is very important for your account to be configured properly to accept the two-step Sale call. If it is not configured correctly, your transactions may error with Ingenico ePayments GlobalCollect code "410110."
By default, the integration and your Ingenico ePayments GlobalCollect account support a one-step process for Refund transactions, so no action is required from you to ensure that this configuration is correct on your merchant account. With the one-step process, Zuora will make a
DoRefund call, and Ingenico ePayments GlobalCollect will process the refund automatically.
Set Up a Secure File Transfer (SFT) Account with Ingenico ePayments GlobalCollect
This SFT account allows you to upload and/or download data from Ingenico ePayments GlobalCollect.
Enable the GlobalCollect Gateway for Your Tenant
Contact Zuora Global Support with your Ingenico ePayments GlobalCollect Merchant ID number(s) so that our support team can enable the gateway in your tenant.
Take the following steps to set up and configure an Ingenico ePayments GlobalCollect gateway instance:
- Click your username at the top right and navigate to Settings > Payments > Setup Payment Gateway.
- Select GlobalCollect (WebCollect Merchant Link) from the Gateway Type drop-down list.
- Click Create Gateway.
- Complete the information for the gateway instance. See below for more information on the fields.
- Click save gateway information after entering the necessary information.
Common configuration fields
There are some common fields you must complete for every gateway configuration. We recommend reviewing our Setup Payment Gateway documentation for information on these common fields:
- Use Gateway Test Environment
- Test Environment Type
- Merchant ID
- Soft Descriptor (Direct Debit Text)
- Cards Accepted
- Default Authorization Amount
Note that 0 is not permitted. If 0 is entered in this field, Zuora will automatically change it to 1 in order to avoid transaction failure.
- Verify new payment method (optional)
- Verify updated payment method (optional)
- Support Recurring
- Collection offset (days)
- Enable AVS Filtering
If enabled, Zuora will decline Credit Card transactions for certain AVS response codes returned by the gateway, even if the gateway has approved the transaction. Default is disabled.
- Enable CVV Filtering
If enabled, Zuora will decline Credit Card transactions for certain CVV response codes returned by the gateway, even if the gateway has approved the transaction. Default is disabled.
AVS and CVV Response Codes
The following table lists the AVS and CVV response codes:
|AVS Response Codes||Description|
|CVV Reponse Code||Description|
|N||CVV checked and no match|
In addition to the common fields, every gateway has unique requirements and information (such as credentials) that you must provide to configure the gateway in Zuora. For Ingenico ePayments GlobalCollect, you must select a Merchant ID and provide a Soft Descriptor.
Your merchant ID is a unique ID (a numeric value of up to 10 digits) that is provided to you by Ingenico ePayments GlobalCollect. The merchant ID number should be the same one you provided to Zuora Global Support to enable in your tenant, and the IDs will appear as a list in the gateway configuration page. If you have more than one Merchant ID number, you configure multiple gateways for each Merchant ID number.
Soft Descriptor (Direct Debit Text)
Soft Descriptor is a dynamic descriptor (text) that helps the customer identify the merchant's business on their statement. This is important, because charge backs can occur if a customer does not recognize the merchant debiting their account and believes that it is an unauthorized charge.
If you accept credit card payment methods, you may consider enabling the Support Recurring option. If Support Recurring is selected, Zuora will mark such payments as recurring when submitting the sale payment transactions to Ingenico ePayments GlobalCollect. For recurring payments, this option may result in reduced fees for the subsequent payments. and greater acceptance with your merchant bank.
Collection Offset (Days)
Collection Offset informs Ingenico ePayments GlobalCollect to delay collection of a UK Direct Debit payment by the specified number of days. The default is five days.
For example, if you submit a request to process the payment on 8/5/14, with an offset date of five days, then they would submit the payment to be collected on 8/10/15.
Zuora recommends setting the field to five days. This accounts for the delay of setting up a mandate and the initial payment that is immediately processed by Zuora. If the acquisition flow considers this delay already, then the offset should be reduced to accelerate collections of recurring payments.
Implement Direct Debit
Although direct debit is treated as any other electronic payment method in Zuora, there are some additional steps required to implement this payment method. See Implementing Direct Debit with Ingenico ePayments for information about using direct debit with Zuora.
Testing the configuration
Zuora recommends testing your selected payment gateway using both your payment gateway's test (staging) and production (live) environments. Once you have completed testing in the gateway's test environment, it is recommended that you perform a test in your live production environment with a real credit card. If there are any differences in the configuration of your testing and production accounts, testing in production ensures your production merchant account is set up properly and can successfully connect to the production environment.
Accessing Your Gateway's Test Environment
If Use Gateway Test Environment is selected in your payment gateway configuration, Zuora will direct payment transactions to the Ingenico ePayments GlobalCollect staging environment.
You will be accessing a staging environment linked to Zuora's integration. This environment is a testing simulator and is shared amongst all merchants using the Zuora Ingenico ePayments integration.
If Use Gateway Test Environment is not selected (disabled), Zuora will direct payment transactions to the Ingenico ePayments GlobalCollect production environment.
Test Credit Cards and Testing Scenarios
Please contact your Ingenico ePayments GlobalCollect implementation manager or Ingenico ePayments Support for specific test credit card numbers and testing scenarios. General support information can be viewed on the Ingenico ePayments 24/7 Shopper Support web page, including phone numbers by region and email contact information.
General Testing Information
Zuora has been certified with Ingenico ePayments as an integration partner and maintains the integration on an ongoing basis, thoroughly testing the integration with every new release. The Ingenico ePayments GlobalCollect integration documentation is helpful if you are integrating Ingenico ePayments GlobalCollect directly with your website, however, you do not need to perform any integration or certification testing to submit transactions to Ingenico ePayments GlobalCollect via the Zuora application. The intended audience for the integration guides are technical integrators, however, these documents can be helpful to non-technical integrators who can refer to it for information on testing and troubleshooting gateway errors. Integration guides and all necessary documentation are provided to you by your Ingenico ePayments GlobalCollect implementation team (as described below).
Performance and Volume Testing
In general, gateway testing environments are intended to give merchants the opportunity to test their gateway and integrations to their gateway, in order to work out any bugs before going to the production environment. Some gateway test environments are shared amongst multiple merchants, and other gateways provide unique testing environments for each merchant. Additionally, gateway test environments (also referred to as certification or sandbox environments) do not have the same high availability or performance capability as production environments. As such, they are not intended for load testing. Merchants performing high volumes of load testing that puts a stress on a shared test environment may receive a warning from the gateway or have their access to the testing environment suspended.
The following information explains how to test Ingenico ePayments GlobalCollect transactions:
Credit Card Transactions:
- PM Creation: This can be tested by making an auth call.
- Sale: The Sale can be tested by making a sale call.
- Void: The void can be done before the transaction goes for settlement. If you want to do a void on sale, you can call it immediately after the sale call is made.
- Refund: In case of credit cards, it takes one business day for a sale transaction to be settled. If you do a sale call today, then you can test the refund of the transaction on the next business day or once the transaction is settled. You can use the inquiry call to identify whether the transaction is settled or is still in the process of settling.
- Inquiry: This can be tested by making an inquiry call.
Direct Debit Transactions:
- PM creation: This can be tested by making a auth call. In case of direct debit, the auth call is used for validation of the bank account information. This is done by Ingenico ePayments against their database.
- Sale: This can be tested by making a sale call.
- Void: Similar to credit card transaction, the void can be done only before the transaction goes for settlement.
- Refund: In case of direct debit, the settlement happens from one to five business days, depending on which country direct debit you are testing for. For the UK and France, it takes four to five business days to settle on their test environment. For all other countries, it can take up to two business days to settle. Similar to credit card, you can make an inquiry call to see whether the transaction is settled. If it has settled, then you can make a refund call.
- Inquiry: This can be tested by making an inquiry call.
Troubleshooting Gateway Errors
There are several ways to obtain information about gateway errors:
- Look up the transaction by the transaction ID number (in the Zuora payment detail page, this is the Reference ID and Secondary Reference ID numbers) in your Ingenico ePayments payment console to see if more information is provided; often you will see more than just the response (reasons) code and response message in Zuora.
- If you need further assistance with a specific error, please contact Ingenico ePayments support. General support information can be viewed on the Ingenico ePayments 24/7 Shopper Support web page, including phone numbers by region and email contact information.
Make sure you are not re-trying an invalid card too many times
We recommend that you check the payment in Zuora to see how many times the same payment method has been retried for payment and failed. If there have been several retries, check the error messages from the beginning with the first failure and the more recent failures to determine if the error message is the same. If a merchant tries to process a payment against the same credit card too many times despite receiving errors, this could trigger warnings to the card issuing bank. The card issuing bank may place an alert on the account and not allow any further transactions from the merchant using that payment method. When a merchant has been flagged, the error received on the payment may be not state the reason why, instead it might be a generic error decline error. In this case, the merchant (Zuora customer) should work with Ingenico ePayments to see if they can identify the problem with the payment method. If the processor does not know, then the merchant and/or the card holder can try calling their card issuing bank to look into the issue.
Transaction Error 410110
As discussed above under Prerequisites, it is very important for your account to be configured properly to accept the two-step Sale call. If it is not configured correctly, your transactions may error with Ingenico ePayments code "410110." This error code may contain a message that can vary, but here is an example of the message: "410110 -- REQUEST 35649 UNKNOWN ORDER OR NOT PENDING."
Working with your Ingenico ePayments GlobalCollect implementation team
Ingenico ePayments GlobalCollect provides merchants with an implementation manager during the first 90 days of the implementation to help with the complex process of implementing and working with direct debits. Processing direct debit transactions may require management of mandates (some countries require mandates and some do not) and thus we recommend working very closely with your implementation manager to understand how direct debits work and how mandates are obtained, processed, and maintained. Your implementation manager should also review how reporting and payment reconciliation is handled, as well as provide you all the necessary documentation to get you started with using Ingenico ePayments GlobalCollect such as:
- Business Guide for Direct Debit
- WebCollect Reporting Guide
- Documentation Containing Test Credit Card Numbers and Test Scenarios
Overview of Ingenico ePayments GlobalCollect gateway integration