> This page is for Enterprise. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://citi-demo.ferndocs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://citi-demo.ferndocs.com/_mcp/server. # Payments ### 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](https://developer.citi.com/apim/go/paymentrules) 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. #### Payment Refund The **Payment Refund endpoint** allows you, as an initiating party (or debtor), to initiate a refund request with the receiving party (or creditor) of a payment that was previously executed. *Please note this is only available in Singapore and India.* #### Payment Reconfirmation The **Payment Reconfirmation endpoint** is available only for Financial Institutions reconfirming a previously initiated payment using the Payment Initiation endpoint, if a pacs message with a status "Pending reconfirmation" was received. > **Note** > > 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. > > | Existing PIUID | New PIUID for P2C | > | -------------- | ----------------- | > | 400 | A01 | > | 894 | A02 | > | 896 | A03 | > > 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: | Format | Payment Initiation | Stop Payment | Payment Status Inquiry GET\* | Payment Status Inquiry POST\* | Enhanced Payment Status Inquiry\* | Payment Refund | Payment Reconfirmation | | ------ | ----------------------- | ------------ | ---------------------------- | ----------------------------- | --------------------------------- | -------------- | ---------------------- | | XML | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | *Custom* | | JSON | *Available for US Only* | *Custom* | ✓ | ✓ | ✓ | | | | SWIFT | | | | | ✓ | | | *\* Payment Status Inquiry APIs (including Enhanced) are synchronous APIs which also have webhooks available.* Below are the formats requests and responses are sent in: | Type | Payment Initiation | Stop Payment | Payment Status Inquiry GET | Payment Status Inquiry POST | Enhanced Payment Status Inquiry | Payment Refund | Payment Reconfirmation | | -------- | ------------------------------------------------------------------------------------------- | --------------------------------------------- | -------------------------- | --------------------------- | ------------------------------------------------------------------------------- | ---------------------- | ---------------------- | | Request | ISOXML - pain.001.001.03 for outgoing payments / ISOXML - pain.008.001.02 for direct debits | ISO XML camt.056.001.08 / Custom JSON formats | Custom schema formatting | Custom schema formatting | Custom schema formatting | ISOXML pain.007.001.09 | ISOXML pacs.008.001.08 | | Response | ISOXML - pain.002.001.03 | ISO XML pacs.002.001.10 | ISOXML - pain.002.001.03 | ISOXML - pain.002.001.03 | ISOXML - pain.002.003.02 / ISOXML - pacs.002.001.10 / SWIFT defined JSON format | ISOXML pain.002.001.03 | ISOXML pacs.002.001.10 | #### Payment methods For more information on payment methods, refer to the table below: | Item | Automated Clearing House (ACH) | Wires | Instant Payments | Citi Token Services | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Description | Electronic money transfers sent from one bank to another through the ACH network. Ideal for recurring payments such as payroll. ACH transfers are primarily done through direct deposits. | Electronic money transfer sent from one institution (banks or non-bank services) to another. Ideal for single payments. | Electronic money transfer that involves almost immediate transfer of money between bank accounts. | Solely owned and managed by Citi, Citi Token Services uses a private and permissioned blockchain that processes multimillion dollar transactions between participating Citi branches. | | Local Clearing Hours | Business hours | Extended hours | Typically 24x7x365 | Typically 24x7x365 | | Funds Availability | 1 - 3 business days | Several hours (4-12 hours) | Within seconds | Near-instant | | Inter Bank/Clearing Settlement | Typically once a day, net | Multiple times a day / batch cycles | Immediate / real-time | Immediate / real-time | | File Processing | Batch | Individual | Individual | Individual | | Payment Confirmation | Only if returned | Inter-bank | End-to-End | End-to-End | | Value and Volume | Low value, high volume | High value, low volume | Low value, high volume | High value, low volume | | Domestic? | ✓ | ✓ | ✓ | ✓\* | | Cross-Border? | N/A | ✓ | ✓ | ✓\* | * 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)). > **Note** > > 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. > **Note** > > 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. > **Warning** > > 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](/enterprises/api-docs/authentication/overview) for more details.