Payments
A full-service set of methods for automating and managing payments end-to-end.
Overview
The Payments API endpoints provide a full-service set of methods for automating and managing payments. From payment initiation through reconciliation and confirmation, you can build a seamless, end-to-end workflow to automate your payment processing. The Payments API supports various payment methods, such as ACH, Wires, Instant Payments, and Distributed Ledger technology via Citi Token Services.
The payments lifecycle consists of initiation, response, status update inquiry and response, and confirmation request and response. A single Payment Initiation endpoint allows you to send your payment instruction for any country/currency combination for all payment methods.
The payment status is continuously updated until the funds reach the beneficiary’s account. You can retrieve or pull the status of your payment using the Payment Status Inquiry endpoint. Subscribe to the Payment Status Notification service, which allows Citi to push any new status as notifications to your endpoint URL.
When utilizing Enhanced Payment Status Inquiry and the Enhanced Payment Status Notifications (webhooks) endpoints allow you to monitor granular statuses as the payment moves through the Clearing network and into the beneficiary account, as per the SWIFT GPI standards.
For e-Commerce Marketplace and PI clients globally, Citi offers Pay2China API services, which is a solution to facilitate last-mile disbursement to merchants in China, for goods which have been sold overseas through e-Commerce platforms.
What will this help me with?
Operating Efficiency — Reduce errors and costs with higher levels of automation and enable payments to reach beneficiaries quicker with same-day transfer of funds.
Enhanced Visibility — Get increased visibility on in-flight payments with payment status reporting and notifications.
New Business Models — Extend the reach of existing distribution networks by embedding payment initiation and management directly into your systems and processes for potential new revenue streams.
How it works
Payment Initiation
The Payment Initiation endpoint allows you to make domestic and cross-border payments from an account held with Citi. Determine the payment type, currency, and country, and access the Payment Formatting Rules tool to generate a sample XML payload with the required parameters.
Stop Payment
The Stop Payment endpoint can issue a stop payment instruction for a previously initiated payment using the Payment Initiation endpoint. Citi will initiate an attempt to stop the payment, however, if the payment has already been executed, the stop request may be rejected.
Payment Status Inquiry
The Payment Status Inquiry endpoint (GET or POST) enables you to obtain the most up-to-date status of your payment. After initiating the payment, you may inquire for the most recent status of your payment using the End-To-End-Id, Payment Creation Date, Instructed Amount and Currency, and Execution Date.
Enhanced Payment Status Inquiry
The Enhanced Payment Status Inquiry endpoint enables you to access the Citi Payment Insights (CPI) solution, designed to standardize payments and receivables information centrally across all of Citi’s branches globally, including payments made through the Payment Initiation endpoint.
For Pay2China services, prior to using the Payment Initiation endpoint, use the Beneficiary Validation endpoint to onboard and validate the identity details of the merchant before initiating the payment. To access the Beneficiary Validation API Reference page, reach out to your Citi Representative for Express Instant Payments API documentation access.
For Pay2China services, refer to the Payment Initiation Unique Identifiers (PIUIDs) below to generate a sample XML payload with the required fields.
You can also use Webhook notifications to post near real-time Payment Status Reports (PSRs) to the partner’s endpoint URL which will update into their systems.
Availability
Formats
Below are the available formats for the Payments API endpoints:
* Payment Status Inquiry APIs (including Enhanced) are synchronous APIs which also have webhooks available.
Below are the formats requests and responses are sent in:
Payment methods
For more information on payment methods, refer to the table below:
- Domestic and Cross-Border payments through Citi Token Services are only available for US Dollar (USD) transactions and in participating Citi branches only (United States (US), United Kingdom (UK), Singapore (SG) and Hong Kong (HK)).
Book transfers, which are money transfers sent from one Citi deposit account to another Citi deposit account, are supported by all four payment methods listed above.
When choosing a payment method and configuring your API payload, there are several things to take into consideration:
- Settlement time will vary according to payment type - settlement times range from five minutes or less for Instant Payments to multiple days for Wires and ACH payments.
- Not all payment types are available in all participating countries. Contact your Citi representative for additional information specific to your country and payment type. Different payment types require different payloads, so it is important to choose the payment type applicable to your workflow.
Only the below mentioned Payment API endpoint versions and higher are available 24x7:
- Payment Initiation - version 3.0.0
- Payment Status Inquiry GET - version 3.0.0
- Payment Status Inquiry POST - version 3.0.0
- Payment Refund - version 2.0.0
Although Citi strives to make APIs 24x7 available wherever possible, there may still be planned or unplanned downtimes albeit at a much-reduced frequency and with shortened windows. Citi’s Service representatives will send information about any near-term planned downtimes 3-4 business days prior to those events so that you can plan business activities related to your API interface circumventing any possible impact to your business and customers.
Countries
Available for all payment types in any country where Citi operates. Please speak with your Citi Representative for additional details.
Security requirements
Citi uses access tokens to authenticate and authorize API requests from your application. To receive an access token from Citi you will first send an API request to our OAuth endpoint using your API credentials: client ID and secret key. Please visit the Authentication guide for more details.