Skip to main content

Overview of Citi payment gateway integration

Zuora

Overview of Citi payment gateway integration

  1. Last updated
  2. Save as PDF

Supported features

The following table provides a quick reference for the supported features. For details about each feature, see the later sections in this article.

Supported payment methods

ACH

ACH payment method verification is supported through the ValidiFi account validation service. See Enable the support for ValidiFi account validation for ACH for details.
Supported payment operations
  • Payment
  • Non-referenced refund
Support Gateway Options fields Yes
Citi payment production endpoint used for Zuora gateway integration service

https://tts.apib2b.citi.com/citiconnect/prod/authenticationservices/v2/oauth/token

https://tts.apib2b.citi.com/citiconnect/prod/paymentservices/v2/payment/inquiry

https://tts.apib2b.citi.com/citiconnect/prod/paymentservices/v2/payment/initiation
Support Gateway Reconciliation Yes
Citi production endpoint used for Gateway Reconciliation service sftp://psftp-citi.ms.gxs.com:2022
Support inquiry call Yes. See Electronic payment processing for details.

Support for Gateway Options fields

SEC (Standard Entry Class) codes, which are defined and maintained by NACHA, describe the authorization methods of ACH transactions. For ACH payment transactions through the Citi payment gateway integration, you can specify SEC code processing rules through the paymentOption field by using the Gateway Options type. You can specify the SEC code information in paymentOption through the following API operations. The payment option applied to a payment can either derive from a related payment schedule or payment schedule item, or can be specified when creating the payment

For more information about how to use the paymentOption field, see the preceding API Reference articles.

Zuora will not validate the transactional level SEC code information you specified and will directly send it to the gateway.

If the transactional level SEC code information is specified, you can retrieve it through Data Source Export, Data Query, or the response of the related API operations.

To enable the paymentOption field, submit a request at  Zuora Global Support.

Support for Gateway Reconciliation 

Citi payment gateway integration supports the following Gateway Reconciliation event types:

  • Payment settlement
  • Payment rejection
  • Refund settlement
  • Refund rejection (To enable this feature, submit a ticket to Zuora Global Support)

The following table describes Zuora’s actions for each Gateway Reconciliation event:

Object Zuora event Zuora action
Payment Settlement Payment status is set to Processed and gateway state is Settled.
Payment Rejection Payment status is set to Processed and gateway state is set to FailedToSettle. Zuora creates an external refund with the reason code set to "Payment Rejection" if the code is active in the Reason Codes list. Otherwise, Zuora creates an external refund with the reason code set to the default reason code in the list.
Refund Settlement Refund status is set to Processed and gateway state is set to Settled.
Refund Rejection
  • If the source of the refund is payment, Zuora updates the refund gateway state to FailedToSettle and reverses the refund amount on the payment by creating an external payment. The external payment status is set to Processed, and its gateway state is set to NotSubmitted. The status of the rejected refund is set to Processed. 
  • If the source of the refund is CreditMemo, Zuora does not create any external payment but still sets the statuses as previously described.

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)

Limitation

Validating the ACH payment methods is currently not supported by the Citi payment gateway integration.