# Acme Citibank India Payments (H2H) (https://docs.tryacme.com/guides/citi-in-payments)
> For AI agents: the documentation index is at [llms.txt](https://docs.tryacme.com/llms.txt), with every page in one file at [llms-full.txt](https://docs.tryacme.com/llms-full.txt). Each page is also available as Markdown by appending `.md` to its URL.
This describes validations / allowed data formats for Acme payments going
through Citibank India. These will be validated by Acme and further validated by
the bank. These rules may be stricter than what the bank requires.
> **Channel: H2H**
>
> * Batch payments, sent to Citibank as host-to-host (H2H) files. Create them with [Create a Batch Payment](https://docs.tryacme.com/reference/post-batch-payments).
> * Single payments are not supported.
Supported types: `IN_RTGS`, `IN_ACH`, `IN_IBFT`, `TT`, `BKTR`.
### Common Definitions [#common-definitions]
* SWIFT Character Set:
* The 26 uppercase Latin letters `A`-`Z`
* The 26 lowercase Latin letters `a`-`z`
* The 10 digits `0`-`9`
* Forward slash `/`
* Hyphen `-`
* Question mark `?`
* Colon `:`
* Left and right parentheses `(` `)`
* Full stop `.`
* Comma `,`
* Single quote `'`
* Plus sign `+`
* Space ` `
* IFSC:
* The 11 character Indian Financial System Code of the receiver's bank branch, in uppercase.
* 4 letters, then `0`, then 6 letters or digits. For example `HDFC0001234`.
* BIC:
* 8 or 11 character Bank Identifier Code in uppercase, for example `HDFCINBBXXX`.
* Citi restrictions:
* For SWIFT character set: do not start a field with any of the following characters: `/`, `-`, `:`
## General notes [#general-notes]
* A batch holds up to 1,000 payments.
* `paymentDate` must not be in the past, in India time (IST). It can be at most 90 days ahead.
* `amount` is in minor units. For example, `150000` is INR 1,500.00. See [Minor units format](https://docs.tryacme.com/guides/minor-units-format).
* The maximum amount per payment is 999,999,999 minor units. For INR, that is INR 9,999,999.99.
## ISO 20022 Migration [#iso-20022-migration]
> **Citi address requirements**
>
> * Citi is moving to the ISO 20022 (CBPR+) address format. If a receiver address is provided, it must carry a town name and a country.
> * In India, Citi applies this to `TT`.
> * Citi rejects a `TT` payment whose address is missing `address.city` or `address.country`. This becomes mandatory in November 2026.
> * Acme already enforces this, and applies the same rule to `IN_RTGS`:
> * `TT`: `address.city` and `address.country` are always mandatory.
> * `IN_RTGS`: the address is optional. If you provide it, `address.city` and `address.country` are mandatory, and `address.country` must be `IN`.
> * Acme sends `postalCode`, `city`, `state` and `country` as structured fields, and `line1` and `line2` as address lines.
## Payment Customer Reference [#payment-customer-reference]
* Use `payments[N].customerReference` as the unique identifier of your payments.
* If `customerReference` is not provided, Acme generates a 13 character unique alphanumeric reference.
* The `customerReference` is sent to the bank as the end-to-end ID of the payment.
## IN_RTGS [#in_rtgs]
> **Important**
>
> * Currency must be **INR only**.
> * The minimum amount is INR 200,000.00 per payment.
> * Send the receiver's IFSC in `receiver.localRoutingIdentifier`. Do not send `receiver.bank`.
> * Do not send `bankChargeBearer` or `purposeOfPayment`.
> * `instructionForSenderBank`: Citi accepts only `/CONFIDENTIAL/`.
> * If you provide `receiver.address`, `address.city` and `address.country` are mandatory, and `address.country` must be `IN`. See [ISO 20022 Migration](#iso-20022-migration).
| field | pattern / charset | max length | mandatory/optional |
| --- | --- | --- | --- |
| paymentDate | `YYYY-MM-DD` | | M |
| payments[N].customerReference | SWIFT (uppercase only) | 15 | O |
| payments[N].paymentDetails | SWIFT | 70 | O |
| payments[N].instructionForSenderBank | SWIFT | 35 | O |
| payments[N].paymentAdviceEmails[N] | Valid email address
Example: ["[finance@company.com](mailto:finance@company.com)"] | 50 per email (max 1 email) | O |
| payments[N].receiver.name | SWIFT | 70 | M |
| payments[N].receiver.bankAccountNumber | Alphanumeric | 34 | M |
| payments[N].receiver.localRoutingIdentifier | IFSC | 11 | M |
| payments[N].receiver.address.line1 | SWIFT | 35 | O |
| payments[N].receiver.address.line2 | SWIFT | 35 | O |
| payments[N].receiver.address.city | SWIFT | 35 | Conditional: M if `address` is provided ([ISO 20022](#iso-20022-migration)) |
| payments[N].receiver.address.state | SWIFT | 35 | O |
| payments[N].receiver.address.postalCode | SWIFT | 16 | O |
| payments[N].receiver.address.country | `IN` | 2 | Conditional: M if `address` is provided ([ISO 20022](#iso-20022-migration)) |
Example Request:
```json
{
"type": "IN_RTGS",
"paymentDate": "2026-11-16",
"senderAccountId": "intacc_0H3BQNTQGBW2W",
"currency": "INR",
"payments": [
{
"amount": 50000000,
"customerReference": "INV2026001",
"paymentDetails": "Payment for invoice 2026001",
"receiver": {
"name": "Example Traders Private Limited",
"bankAccountNumber": "50100123456789",
"localRoutingIdentifier": "HDFC0001234",
"address": {
"line1": "1 MG Road",
"city": "Bengaluru",
"country": "IN"
}
}
}
]
}
```
## IN_ACH [#in_ach]
> **Important**
>
> * Currency must be **INR only**.
> * Send the receiver's IFSC in `receiver.localRoutingIdentifier`. Do not send `receiver.bank`.
> * Do not send `bankChargeBearer` or `purposeOfPayment`.
| field | pattern / charset | max length | mandatory/optional |
| --- | --- | --- | --- |
| paymentDate | `YYYY-MM-DD` | | M |
| payments[N].customerReference | SWIFT (uppercase only) | 15 | O |
| payments[N].paymentDetails | SWIFT | 70 | O |
| payments[N].instructionForSenderBank | SWIFT | 35 | O |
| payments[N].paymentAdviceEmails[N] | Valid email address
Example: ["[finance@company.com](mailto:finance@company.com)"] | 50 per email (max 1 email) | O |
| payments[N].receiver.name | SWIFT | 70 | M |
| payments[N].receiver.bankAccountNumber | Alphanumeric | 34 | M |
| payments[N].receiver.localRoutingIdentifier | IFSC | 11 | M |
| payments[N].receiver.address.line1 | SWIFT | 35 | O |
| payments[N].receiver.address.line2 | SWIFT | 35 | O |
| payments[N].receiver.address.city | SWIFT | 35 | O |
| payments[N].receiver.address.state | SWIFT | 35 | O |
| payments[N].receiver.address.postalCode | SWIFT | 16 | O |
| payments[N].receiver.address.country | `IN` | 2 | O |
Example Request:
```json
{
"type": "IN_ACH",
"paymentDate": "2026-11-16",
"senderAccountId": "intacc_0H3BQNTQGBW2W",
"currency": "INR",
"payments": [
{
"amount": 2500000,
"customerReference": "INV2026002",
"paymentDetails": "Payment for invoice 2026002",
"receiver": {
"name": "Example Traders Private Limited",
"bankAccountNumber": "50100123456789",
"localRoutingIdentifier": "HDFC0001234"
}
}
]
}
```
## IN_IBFT [#in_ibft]
> **Important**
>
> * Instant payment through IMPS.
> * Currency must be **INR only**.
> * Send the receiver's IFSC in `receiver.localRoutingIdentifier`. Do not send `receiver.bank`.
> * Do not send `bankChargeBearer` or `purposeOfPayment`.
| field | pattern / charset | max length | mandatory/optional |
| --- | --- | --- | --- |
| paymentDate | `YYYY-MM-DD` | | M |
| payments[N].customerReference | SWIFT (uppercase only) | 15 | O |
| payments[N].paymentDetails | SWIFT | 70 | O |
| payments[N].instructionForSenderBank | SWIFT | 35 | O |
| payments[N].paymentAdviceEmails[N] | Valid email address
Example: ["[finance@company.com](mailto:finance@company.com)"] | 50 per email (max 1 email) | O |
| payments[N].receiver.name | SWIFT | 70 | M |
| payments[N].receiver.bankAccountNumber | Alphanumeric | 34 | M |
| payments[N].receiver.localRoutingIdentifier | IFSC | 11 | M |
| payments[N].receiver.address.line1 | SWIFT | 35 | O |
| payments[N].receiver.address.line2 | SWIFT | 35 | O |
| payments[N].receiver.address.city | SWIFT | 35 | O |
| payments[N].receiver.address.state | SWIFT | 35 | O |
| payments[N].receiver.address.postalCode | SWIFT | 16 | O |
| payments[N].receiver.address.country | `IN` | 2 | O |
Example Request:
```json
{
"type": "IN_IBFT",
"paymentDate": "2026-11-16",
"senderAccountId": "intacc_0H3BQNTQGBW2W",
"currency": "INR",
"payments": [
{
"amount": 1000000,
"customerReference": "INV2026003",
"paymentDetails": "Payment for invoice 2026003",
"receiver": {
"name": "Example Traders Private Limited",
"bankAccountNumber": "50100123456789",
"localRoutingIdentifier": "HDFC0001234"
}
}
]
}
```
## TT [#tt]
> **Important**
>
> * Currency can be any valid ISO 4217 currency code.
> * `purposeOfPayment` and `purposeCode` are both mandatory.
> * `purposeCode` is `S` followed by 4 digits. Use a code from [Citibank India Purpose Codes](https://docs.tryacme.com/guides/citi-in-purpose-codes).
> * Acme sends `purposeOfPayment` as line 1 and `purposeCode` as line 2 of the remittance information, then `paymentDetails`.
> * `instructionForSenderBank`: Citi accepts only `/CONFIDENTIAL/`.
> * `receiver.address.city` and `receiver.address.country` are always mandatory. See [ISO 20022 Migration](#iso-20022-migration).
| field | pattern / charset | max length | mandatory/optional |
| --- | --- | --- | --- |
| paymentDate | `YYYY-MM-DD` | | M |
| payments[N].customerReference | SWIFT (uppercase only) | 15 | O |
| payments[N].paymentDetails | SWIFT | 70 | O |
| payments[N].purposeOfPayment | SWIFT | 35 | M |
| payments[N].purposeCode | `S` followed by 4 digits
See [purpose codes](https://docs.tryacme.com/guides/citi-in-purpose-codes) | 5 | M |
| payments[N].instructionForSenderBank | SWIFT | 35 | O |
| payments[N].paymentAdviceEmails[N] | Valid email address
Example: ["[finance@company.com](mailto:finance@company.com)"] | 50 per email (max 1 email) | O |
| payments[N].receiver.name | SWIFT | 35 | M |
| payments[N].receiver.bank | BIC | 11 | M |
| payments[N].receiver.intermediaryBank | BIC | 11 | O |
| payments[N].receiver.bankAccountNumber | Alphanumeric | 34 | M |
| payments[N].receiver.address.line1 | SWIFT | 35 | O |
| payments[N].receiver.address.line2 | SWIFT | 35 | O |
| payments[N].receiver.address.city | SWIFT | 35 | M ([ISO 20022](#iso-20022-migration)) |
| payments[N].receiver.address.state | SWIFT | 35 | O |
| payments[N].receiver.address.postalCode | SWIFT | 16 | O |
| payments[N].receiver.address.country | [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) | 2 | M ([ISO 20022](#iso-20022-migration)) |
Example Request:
```json
{
"type": "TT",
"paymentDate": "2026-11-16",
"senderAccountId": "intacc_0H3BQNTQGBW2W",
"currency": "USD",
"payments": [
{
"amount": 2500000,
"customerReference": "INV2026004",
"paymentDetails": "Invoice 2026004",
"purposeOfPayment": "Consulting services",
"purposeCode": "S1006",
"receiver": {
"name": "Example Supplies Pte Ltd",
"bank": "DBSSSGSGXXX",
"bankAccountNumber": "0123456789",
"address": {
"line1": "1 Example Road",
"city": "Singapore",
"postalCode": "123456",
"country": "SG"
}
}
}
]
}
```
## BKTR [#bktr]
> **Important**
>
> * Book transfer to another Citibank India account. Do not send `receiver.bank`.
> * Send the receiver's Citibank IFSC in `receiver.localRoutingIdentifier`.
> * Citi processes a `BKTR` payment with an IFSC that does not start with `CITI` as RTGS, not as a book transfer.
> * Currency can be any valid ISO 4217 currency code.
> * `receiver.bankAccountNumber` is up to 30 characters.
> * Do not send `bankChargeBearer` or `purposeOfPayment`.
| field | pattern / charset | max length | mandatory/optional |
| --- | --- | --- | --- |
| paymentDate | `YYYY-MM-DD` | | M |
| payments[N].customerReference | SWIFT (uppercase only) | 15 | O |
| payments[N].paymentDetails | SWIFT | 70 | O |
| payments[N].paymentAdviceEmails[N] | Valid email address
Example: ["[finance@company.com](mailto:finance@company.com)"] | 50 per email (max 1 email) | O |
| payments[N].receiver.name | SWIFT | 70 | M |
| payments[N].receiver.bankAccountNumber | Alphanumeric | 30 | M |
| payments[N].receiver.localRoutingIdentifier | IFSC | 11 | M |
| payments[N].receiver.address.line1 | SWIFT | 35 | O |
| payments[N].receiver.address.line2 | SWIFT | 35 | O |
| payments[N].receiver.address.city | SWIFT | 35 | O |
| payments[N].receiver.address.state | SWIFT | 35 | O |
| payments[N].receiver.address.postalCode | SWIFT | 16 | O |
| payments[N].receiver.address.country | `IN` | 2 | O |
Example Request:
```json
{
"type": "BKTR",
"paymentDate": "2026-11-16",
"senderAccountId": "intacc_0H3BQNTQGBW2W",
"currency": "INR",
"payments": [
{
"amount": 2500000,
"customerReference": "INV2026005",
"paymentDetails": "Payment for invoice 2026005",
"receiver": {
"name": "Example Traders Private Limited",
"bankAccountNumber": "0123456789",
"localRoutingIdentifier": "CITI0100000"
}
}
]
}
```
## Bank references [#bank-references]
| Sent as | `bankReference` | `bankReferences` | Available from |
| --- | --- | --- | --- |
| A file | `AcctSvcrRef`, else `ClrSysRef` | `AcctSvcrRef`, `ClrSysRef`, `StsId`, as Citi sends them | Citi's status report on the payment |
On your Citi statement, the line shows a different Citi reference. Find the payment by your `customerReference`.
What the names mean:
* `AcctSvcrRef`: Citi's own reference for the transaction.
* `ClrSysRef`: the clearing system's reference.
* `StsId`: the id of Citi's status entry.
A rejected payment keeps the references from the report that rejected it.
A completed payment returns:
```json
{
"bankReference": "01720322200000001",
"bankReferences": {
"AcctSvcrRef": "01720322200000001"
}
}
```