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.

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.

ingenico epayments gateway configuration

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:
    • 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 when 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 custom fields configured on the Payment or Account objects. If the Merchant ID is available on the Payment object, it will be used; if not, Zuora will check if the Merchant ID is available on the Account object and use it if it exists; otherwise, Zuora will use the Merchant ID specified in the Merchant ID field on the gateway configuration page.
      Note: With this check box selected, you can also use the merchantId gateway option field as the credential if you use the Zuora API.
    • (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.
      • Enable Level 2 Processing
      • Enable Level 3 Processing
      • ProductCode Custom Field API Name 
      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.
    • (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

This feature is only available for a small set of early adopters, and we are actively soliciting feedback from them. If you want to have access to this feature, submit a request at Zuora Global Support

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

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

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

Limitations

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.