Skip to main content

Ingenico ePayments Gateway

Zuora

Ingenico ePayments Gateway

Ingenico ePayments is the online and mobile commerce division of Ingenico Group. Zuora now partners with the Ingenico ePayments payment gateway to provide a gateway integration for credit card payment processing. The integration also provides the ability to pass IP addresses for fraud checking by using Gateway Options parameters.

Supported Payment Methods

The Ingenico ePayments integration supports the following payment methods  :

  • Credit cards (Visa, MasterCard, American Express, Discover, JCB, Diners Club, Maestro, Electron, Union Pay, and MIR)
  • ACH
  • SEPA
  • Direct Debit UK (BACS)

Currently, the Ingenico ePayments integration supports the Three Domain Secure (3D Secure) transactions only for the Visa, Mastercard, and American Express credit cards. For more 3D Secure information, see 3D Secure for Payment Pages 2.0.

Stored Credential Transactions 

The Ingenico ePayments integration includes support for the Stored Credential Transaction framework of Visa, Mastercard, and Discover.

Support for 3D Secure 2.0

The Ingenico ePayments integration supports 3D Secure 2.0. See Enable 3DS2 for Ingenico ePayments gateway integration for more information about how to enable 3D Secure 2.0.

A positive amount for the authorizationAmount field is required to enable 3D Secure 2.0. If you use the value 0, Ingenico ePayments will skip the 3D Secure 2.0 process. Zuora uses the following authorization amounts for different card brands:

  • 1 for American Express cards,
  • 0 for other credit card brands.

Ingenico ePayments requires that the authentication amount must be equal to or higher than the authorization amount to enable 3D Secure 2.0. For 3DS2 transactions, the specified value for authorizationAmount will be used as the authentication amount. Therefore, if you want to use 3D Secure 2.0 with American Express credit cards, the authorization amount must be equal to or greater than 1.

Zuora recommends that you use the first transaction amount to be sent as the authorization amount. If you do not populate the authorizationAmount field in the request to Zuora, Zuora will fetch the default authorization amount from the gateway settings to be populated as the authentication amount.

To skip the 3DS2 authentication for specific card brands, you can use the skipAuthenticationCardType gateway option field in API requests or your implementation. You should list all the credit card brands that need to be skipped by the 3DS2 authentication, separated with commas (,). For example, "Visa, AmericanExpress, MaterCard". For more information about how to use gateway options in Payment Pages 2.0, see Gateway Options.

Supported Payment Operations

The Ingenico ePayments integration supports the following operations:

  • Credit card validation 
  • Payment creation
  • Payment cancel
  • Refund creation (partial refunds are supported)

Prerequisites

If you are interested in using the Ingenico ePayments functionality, you must go through a series of procedures to ensure that the feature can be used. 

  • You must obtain the following information from the Ingenico ePayments configuration center.
    • Merchant ID: This is needed to configure gateway instances. If you use the custom merchant ID hierarchy option, you must set up a valid merchant ID custom field on the Payment or Account object, or use the merchantId gateway option field in API requests.
    • API Key ID: A unique identifier used to determine API access right for the Ingenico ePayments merchant account.
    • Secret API Key: An encryption and decryption key unique to the merchant account and is used to receive or retrieve data.
  • You must work with the Ingenico merchant account manager or merchant support to turn on the Delayed Capture setting for your Ingenico merchant account. 

  • You must work with the Ingenico merchant account manager or merchant support to turn on Ingenico’s autonomous decline setting for payments challenged by fraud tools.

Set Up the Ingenico ePayments Gateway

After the Ingenico ePayments payment gateway is enabled in your tenant, set up the payment gateway.

  1. Click your username at the top right, and navigate to Settings > Payments > Set Up Payment Gateway.
  2. From the Gateway Type list, select Ingenico ePayments.
  3. Click create gateway.

Configure the Ingenico ePayments Gateway

After setting up the Ingenico ePayments payment gateway, configure information on the New Gateway configuration page.

  1. In the Basic Information area, configure the following information:
    • In the Name field, specify a name for the gateway instance.
    • If you want to use the Ingenico ePayments test environment, select the Use Gateway Test Environment check box.
  2. In the Credentials area, configure the following information:

    Ingenico ePayments's support for multiple Merchant IDs is an Early Adopter feature. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available.

    • Merchant ID: You can obtain the merchant ID by logging into the Ingenico ePayments configuration center. If you use the custom merchant ID hierarchy option, you can enter either a real Merchant ID or a dummy value. Zuora will default to the value configured in this field if the merchantId gateway option field is not specified and the Merchant ID custom fields on the Payment and Account objects are blank.
    • (Optional) Enable Custom Merchant ID Hierarchy: Select this check box if you want to use a hierarchy for the Merchant ID. With the custom Merchant ID hierarchy enabled, Zuora will look for and use the merchant ID in the following order:
      1. The merchantId gateway option field in API requests.
      2. The Merchant ID custom field on the Payment object.
      3. The Merchant ID custom field on the Account object.
      4. The value specified in the Merchant ID gateway setting.
    • (Optional) Payment Custom Field - Merchant ID: Enter the API name (without __c) of the Merchant ID custom field configured on the Payment object.
    • (Optional) Account Custom Field - Merchant ID: Enter the API name (without __c) of the Merchant ID custom field configured on the Account object.
    • In the API Key ID field, enter the unique API Key ID obtained from the Ingenico ePayments gateway.
    • In the Secret API Key field, enter the secret API key obtained from the Ingenico ePayments gateway.
    • (Optional) In the SFTP Username field, enter the username of the SFTP server used for reconciliation. This field is required if you want to enable Gateway Reconciliation.
    • (Optional) In the SFTP Password field, enter the password of the SFTP server used for reconciliation. This field is required if you want to enable Gateway Reconciliation.
  3. In the Rules area, configure the following information:
    • Cards Accepted: Select the credit cards that you accept.
    • Default Authorization Amount: Specify the minimum default amount used to process a payment.
      The default value of this field is 1. For American Express payments, a minimum of $1.00 is required. 
    • Verify new payment method: If you want to verify new payment methods, select this check box.
      By default, this check box is selected.
    • Verify updated payment method: If you want to verify updated payment methods, select this check box.
      By default, this check box is selected.
    • Ingenico Platform: Select GlobalCollect.
    • (Optional) Complete the Level 2 and Level 3 card fields. See Level 2 and Level 3 card data for more information. Note: The first 17 characters of the Account Number is mapped to the customerReference field on the Ingenico side for Level 2 and Level 3 data processing.
      • Enable Level 2 Processing
      • Enable Level 3 Processing
      • ProductCode Custom Field API Name 
    • (Optional) Enable AVS Filtering: If selected, Zuora will decline Credit Card transactions for certain AVS response codes returned by the gateway even though the gateway has approved the transaction.
    • (Optional) Enable CVV Filtering: If selected, Zuora will decline Credit Card transactions for certain CVV response codes returned by the gateway even though the gateway has approved the transaction.
    • (Optional) Enable Gateway Reconciliation: Select this check box if you want to enable the Gateway Reconciliation feature.
  4. Click save gateway information to save the configurations.

Gateway Reconciliation

Before enabling Gateway Reconciliation for the Ingenico ePayments gateway in Zuora, you must ensure that you receive the WX file in the XML format on the SFTP directory. This might have to be configured separately by Ingenico ePayments.

To enable the Gateway Reconciliation feature for Ingenico ePayments, in addition to the required fields, you must complete the following optional gateway settings:

  • SFTP Username: The username of the SFTP server used for reconciliation
  • SFTP Password: The password of the SFTP server used for reconciliation
  • Enable Gateway Reconciliation

The Ingenico ePayments gateway integration supports the following Gateway Reconciliation event types:

  • Settlement
  • Chargeback
  • Rejection

The Ingenico ePayments integration supports only the following Gateway Reconciliation status:

Gateway Reconciliation event type Supported Gateway Reconciliation status Corresponding response from the gateway 
Transaction Settled Credit Card payment settled recordCategory = "+" and recordType = "ON"
Direct Debit settled recordCategory = "+" and recordType = "AP"
Credit Card refund settled recordCategory = "-" and recordType = "CR"
Transaction Rejected Credit Card payment settlement refused recordCategory = "-" and recordType = "ON"
An online settlement for an authorized Credit Card payment was refused recordCategory = "X" and recordType = "RS"
Credit Card payment rejected after successful authorization recordCategory = "X" and recordType = "RN"
A Direct Debit payment has been rejected by the bank of the consumer recordCategory = "X" and recordType = "AB"
A Direct Debit payment has been rejected by GlobalCollect recordCategory = "X" and recordType = "AG"
A Direct Debit payment previously reported as settled (recordCategory = "+" and recordType = "AP") has been reversed for some reason recordCategory = "-" and recordType = "AR"
Transaction Reversed Chargeback on collected Credit Card payment recordCategory = "-" and recordType = "CB"

To understand how Zuora will subsequently process these Gateway Reconciliation events, see Gateway Reconciliation for more information.

Gateway Reconciliation job status can be viewed beginning at 3:00 pm (PST).

Testing Your Configuration  

We recommend that you test your payment gateway using both your payment gateway's test 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 real information. 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.

You can use the testing payment methods provided by Ingenico ePayments to test your integration. See Ingenico ePayments' testing payment methods for details.

Supported Gateway Option Fields

You can submit additional information to the Ingenico ePayments gateway using gateway options. Currently, Ingenico ePayments supports the following gateway option fields:

  • isRecurring
  • endDate
  • merchantId
  • minFrequency
  • recurringPaymentSequenceIndicator
  • transactionChannel
  • merchantInitiatedReasonIndicator
  • unscheduledCardOnFileRequestor
  • unscheduledCardOnFileSequenceIndicator
  • merchantCustomerId
  • skipAuthenticationCardType

You can use these fields in Payment Pages 2.0SOAP API, or the following REST API:

Limitations

  • The custom Merchant ID hierarchy is used only when you have multiple Merchant IDs.
  • You cannot modify an existing Merchant ID, or use a different Merchant ID for cancel (void payment) or refund transactions compared to the original payment. Zuora will store the Merchant ID used during payments and use the same Merchant ID to make any cancel or refund transactions against the payment to ensure successful transactions. 
  • For the Delayed Capture flow (authorize, capture payment, and cancel authorization API calls), the Merchant ID must be used in API calls as the gwOptions_merchantId gateway option field to ensure successful transactions. You must ensure that the same Merchant ID value from the authorize call is used for payment capture and void authorization calls as well. See Create authorization for more information.