Skip to navigation
Outgoing Payments

Bulk Payments

Submit a single, consolidated request containing all payment details for batch-driven processes.

View as Markdown

Overview

The Bulk Payments API is an efficient way to handle typically batch-driven processes, such as a scheduled payment run from an ERP, payments to suppliers, insurance claims or payroll. Rather than iterating through payments one by one, you can submit a single, consolidated request containing all payment details. This aims to simplify your integration and helps to make the overall payment process more efficient.

The payment lifecycle through the API involves three key stages: initiation, response, and status updates. The Bulk API initiation endpoint allows you to send your payment instructions for almost any country/currency combination across all supported payment methods.

Payment statuses are frequently updated until the funds successfully reach the beneficiary’s account. By subscribing to the Bulk Payment Status Notification service, you receive real-time updates directly to your specified endpoint URL as payments progress. You can also use enhanced status inquiry API to track the status of individual payment status.

What will this help me with?

Automation and Efficiency — Directly link your ERP (Enterprise Resource Planning) or TMS (Treasury Management System) to the bank’s payment system via API. Automate payment initiation, reducing human intervention and limiting potential errors.

Status Updates — Receive notifications on payment statuses, allowing for quicker and more accurate reconciliation of accounts. Status updates are grouped and sent at set intervals, providing a comprehensive overview of all payments in a batch.

Scalability — Easily handle higher payment volumes without requiring major overhauls to your existing infrastructure allowing you to scale.

How it works

1

Payment Initiation

To begin, you will send a single request to the bulk payments endpoint, which includes a list of all the individual payments you wish to make. You can use the Payment Formatting Rules tool to generate a sample XML payload with the required parameters.

  • Batch Size: Each batch can contain up to 5,000 payments.
  • Unique ID: You must provide a unique ID for each batch in your API call. This ID helps you track and identify your batch throughout its lifecycle.
  • Account and Beneficiaries: Each batch is linked to one debit account or multiple debit accounts and can include multiple beneficiaries. All payments within a single batch can use the same or combination of payment methods.
  • Initial Acknowledgment: Upon successfully receiving your batch request, the API will send an immediate acknowledgment. This confirms that your batch has been received by our system and is ready for further processing.
2

Citi Completes Request

After initiation, to receive updates on the processing of your payments, you need to subscribe to the Bulk Payment Status Notification service. This service will push status updates for all payments within a batch.

Compressing Bulk Payments Requests

To support bulk payments via API channel, requests to Citi must be compressed using GZIP. You can typically send up to 5000 payments in a single API call every two minutes.

To facilitate efficient data transmission and compatibility with the API, follow these steps to prepare your payload. GZIP compression reduces data size, leading to faster network transfer.

Step-by-Step Instructions for Developers:

  1. Construct the ISO 20022 pain.001 Request: Create the XML request containing all necessary payment initiation details according to the ISO 20022 pain.001 standard.
  2. Compress the Payload with GZIP: Take the generated XML request and compress it using the GZIP compression format. This significantly reduces the size of the payload.
  3. Base64 Encode the GZIP Compressed Payload: Convert the binary GZIP compressed data into a Base64-encoded string. This step is crucial for safe transmission over text-based protocols (like HTTP).
  4. Optionally Encrypt the Base64 Payload: For an additional layer of security during transmission, you may choose to encrypt the Base64-encoded string. Consult specific API documentation for required encryption methods if applicable.
  5. Set X-Content-Encoding Header: When sending your HTTP request, ensure that the X-Content-Encoding header is set to gzip. This explicitly indicates to the API that the request payload has been compressed using GZIP. Example Header: X-Content-Encoding: gzip

GZIP Compression Reference:

For more detailed information on GZIP compression, you can refer to: Wikipedia: Gzip.

Bulk Payments Notifications

Bulk payment notifications provide status updates for all payments contained within a specific batch. You need to pre-configure webhooks to receive status updates on your batch.

  • Scheduled Delivery: Notifications are generated at pre-configured intervals. This allows our system to collect as many payment status changes as possible before sending you an update.
  • Event-Driven: A notification is only triggered if at least one payment in a batch has experienced a status change. This prevents redundant notifications, helping to ensure you receive updates only when there’s new information.
  • Notification Content: Each notification includes the Batch ID, the total number of transactions in the batch, and payment status blocks for each payment status.

There are three primary status blocks:

  • Pending: Payments still being processed.
  • Complete: Payments successfully processed and sent to the beneficiary’s account.
  • Rejected: Payments that could not be processed.

The first notification you receive will typically show most payments in a “pending” state. Some payments might immediately appear in a “rejected” state if there are issues with their format or other initial validations. Notifications will continue to be generated until all payments in the batch have moved from “pending” to either “completed” or “rejected.” The payments using batch-based payment methods such as ACH can stay longer in the pending state depending on the time payment is made and batch window for payment processing.

  • Rejection Details: Only the “rejected” status block will include additional information, such as a reason code, explaining why a payment was rejected.
  • Confidentiality: The “pending” and “complete” status blocks contain only the end-to-end payment IDs, without specific transaction or beneficiary details. This design helps assure that payment confidentiality is maintained by default and keeps notifications lightweight.

Availability

Formats

  • XML

Countries

  • Global

Availability subject to change without notice. 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.