Skip to main content

Citi payment gateway integration

Zuora

Citi payment gateway integration

Zuora partners with Citi to provide a gateway integration called Citi Connect API.

Supported payment methods

The Citibank gateway integration supports the following payment methods:

  • ACH

Supported payment operations

The Citibank gateway integration supports the following payment operations:

  • Payment
  • Non-referenced refund (Credit)

Configure gateway instance

  1. Navigate to Payments Settings > Setup Payment Gateway
  2. Click Gateway Type field and select Citi Connect API.
  3. Click create gateway
  4. Specify the field values. See the field descriptions below for more information.
  5. Click save gateway information.

Common configuration fields

The following are the common configuration fields you must specify for all gateways. See Setting Up Payment Gateways for the general information about setting up a payment gateway and specifying the values for the common fields: 

  • Name
  • Use Gateway Test Environment
  • Cards Accepted
  • Default Authorization Amount - This field is used only for credit card validation.
  • Verify new payment method (optional) - With this checkbox selected, the validate call is triggered for any supported payment method when a new payment method is created.
  • Verify updated payment method (optional) - With this checkbox selected, the validate call is triggered for any supported payment method when an existing payment method is updated.

Additional fields

In addition to common fields, you must configure the following fields that are specific to the Citi Connect API gateway integration. All fields are required.

  • Client Id - ID provided by Citi to retrieve an OAuth token.
  • Client Secret - Password provided by Citi to retrieve an OAuth Token.
  • Account Name - Name of the bank account linked with Citi.
  • Account Number - Account number of the bank account linked with Citi.
  • Accounting Routing Number - Routing number of the bank account linked with Citi.
  • Address - Address of the bank account linked with Citi.
  • Country - Country of the bank account linked with Citi.
  • Citi Connet Client Id - The Client ID used for Gateway Reconciliation. 
  • SSL Keystore - The keystore that contains the certificate for the SSL connection.
  • SSL Keystore Password - The password for the SSL keystore.
  • Encryption Keystore - The keystore that contains the certificate for encryption.
  • Encryption Keystore Password - The password for the encryption keystore.
  • Digital Signature Alias - The alias of the certificate for the Digitial Signature that is within the encryption keystore.
  • Encryption Alias - The alias of Citi's public certificate within the encryption keystore.
  • Decryption Keystore - The keystore that contains the certificate for decryption.
  • Decryption Keystore Password - The password for the decryption keystore.
  • Decryption Keystore Alias - The alias of the certificate within the decryption keystore.

Gateway Reconciliation for Citi

Citi generates two types of Gateway Reconciliation files: the RIP file and the DIP file. The corresponding file names are Zuora_{{CitiConnectClientID}}_RIP_{{DateTime}}.txt and Zuora_{{CitiConnectClientID}}_DIP_{{DateTime}}.txt.

The DIP file is generated once a day at 10:00 pm Eastern Time. The RIP file is generated 3 times a day at 6:30 am, 9:30 am and 9:30 pm Eastern Time, respectively.

Zuora processes these files at 11:00 pm Eastern Time every day by filtering the files based on the Citi Connect Client ID provided on the gateway configuration page. The transactions that are rejected before Citi distributes files to the clearinghouse are not included in the RIP or DIP file. To handle such transactions, Zuora performs API calls to get the status of these transactions in 3-4 business days.

The following table outlines the different event log fields for the DIP file and the RIP file:

Event log field DIP file RIP file
Gateway Reference ID Trace Number 6(80-94) Trace Number 7(07-21)
 
Event Date Effective Entry Date 5(70-75) File Creation Date 1(24-29)
Event Type Transaction Settled Transaction Rejected
 
Amount Amount/Decimal Point Assumed 6(30-39) Amount/Decimal Point Assumed 6(30-39)
Gateway Reason Code N/A Return Reason Code 7(4-6)
Gateway Reason Message N/A Addenda Information 7(36-79)