# Acme Citibank China Payments (/guides/citi-cn-payments)



This describes validations / allowed data formats for Acme payments going
through Citibank China. These will be validated by Acme and further validated by
the bank. These rules may be stricter than what the bank requires.

### 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 ` `

* Citi restrictions:
  * For SWIFT character set: do not start a field with any of the following characters: `/`, `-`, `:`
  * Acme does not apply a China bank-holiday calendar. The bank may still reject a `paymentDate` that is not a CN working day.

## CN\_ACH [#cn_ach]

China domestic ACH transfer.

<Callout type="warn" title="Important">
  * Currency must be **CNY only**.
  * Payment date cannot be in the past. Maximum 65 days forward.
  * `bankChargeBearer` and `instructionForSenderBank` must not be provided.
  * `receiver.intermediaryBank` and `receiver.address.line1`/`line2`/`state`/`postalCode` must not be provided; only `city` and `country` are accepted.
  * `receiver.name` and `receiver.bank` may be English or Chinese. Backtick is not allowed.
  * Provide `receiver.accountName` only if it differs from `receiver.name`. If provided, the bank uses the account name instead of the beneficiary name.
  * `categoryPurpose` is a batch-level field. `receiver.address.city` is required.
</Callout>

| field                                        | pattern / charset                                                                                                                                                                     | max length                 | mandatory/optional |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ------------------ |
| categoryPurpose (at batch level)             | One of `BONU` `CASH` `CCRD` `CORT` `DCRD` `DIVI` `EPAY` `GOVT` `HEDG` `ICCP` `IDCP` `INTC` `INTE` `LOAN` `OTHR` `PENS` `SALA` `SECU` `SSBE` `SUPP` `TAXS` `TRAD` `TREA` `VATX` `WHLD` | 4                          | O                  |
| payments\[N].customerReference               | SWIFT (uppercase only)                                                                                                                                                                | 15                         | M                  |
| payments\[N].paymentDetails                  | English or Chinese                                                                                                                                                                    | 70                         | O                  |
| payments\[N].paymentAdviceEmails\[N]         | Valid email address <br /> Example: `["finance@company.com"]`                                                                                                                         | 50 per email (max 1 email) | O                  |
| payments\[N].transferLocality                | `INTRA_CITY` or `INTER_CITY`                                                                                                                                                          |                            | M                  |
| payments\[N].receiver.name                   | English or Chinese; backtick not allowed                                                                                                                                              | 60                         | M                  |
| payments\[N].receiver.bank                   | English or Chinese; backtick not allowed                                                                                                                                              | 60                         | M                  |
| payments\[N].receiver.bankAccountNumber      | Numeric                                                                                                                                                                               | 32                         | M                  |
| payments\[N].receiver.localRoutingIdentifier | Numeric                                                                                                                                                                               | 12                         | O                  |
| payments\[N].receiver.accountName            | English or Chinese                                                                                                                                                                    | 44                         | O                  |
| payments\[N].receiver.address.city           | English or Chinese                                                                                                                                                                    | 35                         | M                  |
| payments\[N].receiver.address.country        | Fixed value `CN`                                                                                                                                                                      | 2                          | O                  |

## CN\_RTGS [#cn_rtgs]

China domestic RTGS transfer for high-value payments.

<Callout type="warn" title="Important">
  * Currency must be **CNY only**.
  * Payment date cannot be in the past. Maximum 90 days forward.
  * `receiver.localRoutingIdentifier` must be exactly 12 digits (CNAPS).
  * `receiver.bank` is optional.
  * `bankChargeBearer`, `instructionForSenderBank`, `transferLocality`, `purposeCode`, `receiver.intermediaryBank`, and `receiver.address` must not be provided.
  * `receiver.name`, `receiver.bank`, and `paymentDetails` must not contain a backtick.
  * Provide `receiver.accountName` only if it differs from `receiver.name`. If provided, the bank uses the account name instead of the beneficiary name.
</Callout>

| field                                        | pattern / charset                                             | max length                 | mandatory/optional |
| -------------------------------------------- | ------------------------------------------------------------- | -------------------------- | ------------------ |
| payments\[N].customerReference               | SWIFT (uppercase only)                                        | 15                         | M                  |
| payments\[N].paymentDetails                  | English or Chinese; backtick not allowed                      | 140                        | O                  |
| payments\[N].paymentAdviceEmails\[N]         | Valid email address <br /> Example: `["finance@company.com"]` | 50 per email (max 1 email) | O                  |
| payments\[N].receiver.name                   | English or Chinese; backtick not allowed                      | 60                         | M                  |
| payments\[N].receiver.bank                   | English or Chinese; backtick not allowed                      | 60                         | O                  |
| payments\[N].receiver.bankAccountNumber      | Numeric                                                       | 32                         | M                  |
| payments\[N].receiver.localRoutingIdentifier | Numeric (exactly 12 digits)                                   | 12                         | M                  |
| payments\[N].receiver.accountName            | English or Chinese                                            | 60                         | O                  |

## CN\_TT\_INTL [#cn_tt_intl]

Telegraphic transfer for international payments. Currency must not be CNY; use `CN_TT_DOM` for RMB.

<Callout type="warn" title="Important">
  * Currency must **not** be CNY.
  * Payment date cannot be in the past. Maximum 90 days forward.
  * `receiver.bank` must be a BIC.
  * `instructionForSenderBank` and `receiver.localRoutingIdentifier` must not be provided.
  * SAFE BOP reporting is required. See [SAFE BOP](#safe-bop). Acme validates list size, string length, and amount shape only.
  * Provide `receiver.accountName` only if it differs from `receiver.name`. If provided, the bank uses the account name instead of the beneficiary name.
  * `receiver.address.city` and `receiver.address.country` are mandatory. The full address must fit in 3 lines of 35 SWIFT characters.
</Callout>

| field                                    | pattern / charset                                                                                            | max length                 | mandatory/optional |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------- | ------------------ |
| payments\[N].customerReference           | SWIFT (uppercase only)                                                                                       | 15                         | M                  |
| payments\[N].paymentDetails              | English or Chinese; backtick not allowed                                                                     | 140                        | O                  |
| payments\[N].paymentAdviceEmails\[N]     | Valid email address <br /> Example: `["finance@company.com"]`                                                | 50 per email (max 1 email) | O                  |
| payments\[N].bankChargeBearer            | `SENDER` / `RECEIVER` / `SHARED`                                                                             |                            | O                  |
| payments\[N].regulatoryInstructionInfo   | Array of strings (include Citi prefixes, e.g. `/CNS1/`)                                                      | 35 per entry (max 3)       | M                  |
| payments\[N].regulatoryAmounts           | Array of `{ amount, currency }`. `amount` is a positive integer in [minor units](/guides/minor-units-format) | max 2 entries              | M                  |
| payments\[N].regulatoryInformation       | Array of strings. List index is the Inf slot. **Exactly 6** entries; unused slots `""`                       | 35 per entry               | M                  |
| payments\[N].receiver.name               | English or Chinese; backtick not allowed                                                                     | 35                         | M                  |
| payments\[N].receiver.bank               | BIC (8 or 11 characters, [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362))                                 | 11                         | M                  |
| payments\[N].receiver.intermediaryBank   | BIC (8 or 11 characters)                                                                                     | 11                         | O                  |
| payments\[N].receiver.bankAccountNumber  | SWIFT                                                                                                        | 34                         | M                  |
| payments\[N].receiver.accountName        | English or Chinese                                                                                           | 35                         | O                  |
| payments\[N].receiver.address.line1      | SWIFT                                                                                                        | 35                         | O                  |
| payments\[N].receiver.address.line2      | SWIFT                                                                                                        | 35                         | O                  |
| payments\[N].receiver.address.city       | SWIFT                                                                                                        | 35                         | M                  |
| payments\[N].receiver.address.state      | SWIFT                                                                                                        | 35                         | O                  |
| payments\[N].receiver.address.postalCode | SWIFT                                                                                                        | 35                         | O                  |
| payments\[N].receiver.address.country    | [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)                                       | 2                          | M                  |

## CN\_TT\_DOM [#cn_tt_dom]

RMB cross-border payment. Despite the type name, this is not a domestic FCY rail. Currency must be **CNY only**; use `CN_TT_INTL` for other currencies.

<Callout type="warn" title="Important">
  * Currency must be **CNY only**.
  * Payment date cannot be in the past. There is no Acme forward-date cap.
  * `receiver.bank` is a bank name, not a BIC.
  * `receiver.name` and `receiver.bank` must be SWIFT characters. Backtick is not allowed on those fields.
  * `instructionForSenderBank`, `receiver.localRoutingIdentifier`, and `receiver.intermediaryBank` must not be provided.
  * SAFE BOP reporting is required. See [SAFE BOP](#safe-bop). Acme validates list size, string length, and amount shape only.
  * Provide `receiver.accountName` only if it differs from `receiver.name`. If provided, the bank uses the account name instead of the beneficiary name.
  * If an address is provided, the full address must fit in 3 lines of 35 SWIFT characters.
</Callout>

| field                                    | pattern / charset                                                                                                    | max length                 | mandatory/optional |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------- | ------------------ |
| payments\[N].customerReference           | SWIFT (uppercase only)                                                                                               | 16                         | M                  |
| payments\[N].paymentDetails              | English or Chinese                                                                                                   | 140                        | O                  |
| payments\[N].paymentAdviceEmails\[N]     | Valid email address <br /> Example: `["finance@company.com"]`                                                        | 50 per email (max 1 email) | O                  |
| payments\[N].bankChargeBearer            | `SENDER` / `RECEIVER` / `SHARED`                                                                                     |                            | O                  |
| payments\[N].purposeCode                 | One of `GOD` `STR` `CTF` `RMT` `OTF` `02112` `02113` `02114` `02115` `02116` `02117` `02123` `02124` `02125` `02127` |                            | O                  |
| payments\[N].regulatoryInstructionInfo   | Array of strings (include Citi prefixes, e.g. `/CNS1/`)                                                              | 35 per entry (max 3)       | M                  |
| payments\[N].regulatoryAmounts           | Array of `{ amount, currency }`. `amount` is a positive integer in [minor units](/guides/minor-units-format)         | max 2 entries              | M                  |
| payments\[N].regulatoryInformation       | Array of strings. List index is the Inf slot. **Exactly 6** entries; unused slots `""`                               | 35 per entry               | M                  |
| payments\[N].receiver.name               | SWIFT; backtick not allowed                                                                                          | 35                         | M                  |
| payments\[N].receiver.bank               | SWIFT (bank name, not BIC); backtick not allowed                                                                     | 35                         | M                  |
| payments\[N].receiver.bankAccountNumber  | SWIFT                                                                                                                | 34                         | M                  |
| payments\[N].receiver.accountName        | English or Chinese                                                                                                   | 60                         | O                  |
| 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                                                                                                                | 35                         | O                  |
| payments\[N].receiver.address.country    | [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)                                               | 2                          | O                  |

## SAFE BOP [#safe-bop]

For `CN_TT_INTL` and `CN_TT_DOM` you must send three payment fields. They are not interchangeable:

| field                       | Role                         | How you can tell them apart                                                                        |
| --------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------- |
| `regulatoryInstructionInfo` | Prefixed remarks and invoice | Every string **starts with** `/CNS1/`, `/CNS2/`, or `/CNIN/`                                       |
| `regulatoryInformation`     | SAFE form slots              | First string **starts with** `O/C/…` (no `/CNS` prefix). **Always 6 slots**; unused slots are `""` |
| `regulatoryAmounts`         | Code 1 / Code 2 money        | Objects with `amount` and `currency`, not strings                                                  |

Use application form type &#x2A;*`O` (overseas)*&#x2A; for both types. Customer type is &#x2A;*`C` (business)**.

Acme only checks list size, string length (≤35), and amount shape. Citi checks the actual SAFE content.

| field                       | Limits                                                                                 |
| --------------------------- | -------------------------------------------------------------------------------------- |
| `regulatoryInstructionInfo` | Non-empty; ≤3 strings                                                                  |
| `regulatoryAmounts`         | Non-empty; ≤2. `amount` is [minor units](/guides/minor-units-format) (`1`–`999999999`) |
| `regulatoryInformation`     | **Exactly 6** strings. List index = slot (`[0]` is slot 1). Unused slots are `""`      |

Use this table with Citi’s *Values — CHINA SAFE BOP Declaration Sub-form*. Join the parts of a slot with `/`.

**`regulatoryInformation`**

| Citi sub-form field                   | Send as                                                              |
| ------------------------------------- | -------------------------------------------------------------------- |
| Application Form Type                 | Slot `[0]`, 1st part — use `O` (overseas)                            |
| Customer Type                         | Slot `[0]`, 2nd part — use `C` (business)                            |
| BOP Transaction Code 1                | Slot `[0]`, 3rd part — 6 digits                                      |
| Payment Purpose                       | Slot `[0]`, 4th part — `A` `D` `R` `O`                               |
| Name of Applicant                     | Slot `[0]`, 5th part                                                 |
| BOP Transaction Code 2                | Slot `[1]`, 1st part — optional; leave empty if unused               |
| Payment classified for bonded goods   | Slot `[1]`, 2nd part — `Y` or `N`                                    |
| Applicant Phone Number                | Slot `[1]`, 3rd part                                                 |
| Payment Character                     | Slot `[2]` — only if form type is `D`                                |
| SAFE Approval/Register/Service Number | Slot `[3]`, 1st part — optional                                      |
| Fund Source Type                      | Slot `[3]`, 2nd part — optional `F` `P` `O`                          |
| Unit Code For Business                | Slot `[4]`, 1st part — required because customer type is `C`         |
| Resident Country/Region               | Slot `[4]`, 2nd part — 3 characters from the China SAFE country list |
| Contract Number                       | Slot `[5]` — required when bonded goods is `Y`                       |

**`regulatoryAmounts`**

| Citi sub-form field             | Send as                                                |
| ------------------------------- | ------------------------------------------------------ |
| BOP Transaction Code 1 Amount   | `[0].amount` (minor units) — goes with Inf slot `[0]`  |
| BOP Transaction Code 1 Currency | `[0].currency`                                         |
| BOP Transaction Code 2 Amount   | `[1].amount` — only if Code 2 is used (Inf slot `[1]`) |
| BOP Transaction Code 2 Currency | `[1].currency` — only if Code 2 is used                |

**`regulatoryInstructionInfo`** (each string starts with the code word)

| Citi sub-form field           | Send as                                                                      |
| ----------------------------- | ---------------------------------------------------------------------------- |
| BOP Transaction Code 1 Remark | `/CNS1/{remark}` — required for form type `O` (overseas)                     |
| BOP Transaction Code 2 Remark | `/CNS2/{remark}` — required for form type `O` (overseas) when Code 2 is used |
| Invoice Number                | `/CNIN/{invoice}` — required when bonded goods is `Y`                        |

### Typical payment [#typical-payment]

Bonded goods `N`, no second BOP code. Send **all 6 strings**. Unused slots (Payment Character, SAFE number, contract) are `""` so later slots stay in position. Replace the `{…}` values.

```json
{
  "regulatoryInstructionInfo": ["/CNS1/{code 1 remark}"],
  "regulatoryAmounts": [
    { "amount": {same minor units as amount}, "currency": "{payment currency}" }
  ],
  "regulatoryInformation": [
    "O/C/{6-digit BOP code}/{purpose}/{applicant name}",
    "/N/{phone}",
    "",
    "",
    "{unit code}/{SAFE country}",
    ""
  ]
}
```

| Index | Slot | In this template                                    |
| ----- | ---- | --------------------------------------------------- |
| `[0]` | 1    | Form, customer, BOP code 1, purpose, applicant name |
| `[1]` | 2    | Code 2 (empty), bonded `N`, phone                   |
| `[2]` | 3    | `""` — Payment Character, only if form type is `D`  |
| `[3]` | 4    | `""` — optional SAFE number / fund source           |
| `[4]` | 5    | Unit code + SAFE country                            |
| `[5]` | 6    | `""` — contract number, only if bonded is `Y`       |

Do not skip middle or trailing unused slots. Send `""` so the index still matches the Citi slot.

| Placeholder          | What to put                                                                                          |
| -------------------- | ---------------------------------------------------------------------------------------------------- |
| `{code 1 remark}`    | Short remark for BOP code 1 (required for overseas). The whole string including `/CNS1/` must be ≤35 |
| `{6-digit BOP code}` | BOP Transaction Code 1                                                                               |
| `{purpose}`          | `A` advance payment, `D` payment against delivery, `R` refund, `O` others                            |
| `{applicant name}`   | English ≤20 or Simplified Chinese ≤10                                                                |
| `{phone}`            | Applicant phone, ≤20                                                                                 |
| `{unit code}`        | Business unit code Citi issued (required because customer type is `C`)                               |
| `{SAFE country}`     | 3 characters from the China SAFE country list (for example `CHN`)                                    |

### When you need extra fields [#when-you-need-extra-fields]

**Second BOP code**

* Slot `[1]` becomes `{code2}/N/{phone}` (or `Y` if bonded)
* Add `{ "amount": …, "currency": … }` as `regulatoryAmounts[1]` (this amount is sent with Inf slot `[1]`, not as a separate amount-only block)
* Add `/CNS2/{code 2 remark}` to `regulatoryInstructionInfo`

**Bonded goods `Y`**

* Slot `[1]` uses `Y` instead of `N`
* Add `/CNIN/{invoice number}` to `regulatoryInstructionInfo`
* Put the contract number in slot `[5]` instead of `""`

**Optional slot `[3]`**

* `{SAFE approval or register number}/{fund source}`
* Fund source: `F` FX, `P` purchase, `O` others
* If you skip it, keep `""` so later slots do not move

**Domestic form type `D`**

* Do not use `D` for these payment types unless Citi told you to
* If you do, slot `[2]` must be Payment Character: `X` bonded area, `E` export processing zone, `D` diamond exchange, `M` downstream processing, `O` other

### Example: `CN_TT_INTL` [#example-cn_tt_intl]

USD 10,000.00, BOP code `600101`, advance payment, not bonded. Replace `12345678` with your Citi unit code.

```json
{
  "amount": 1000000,
  "currency": "USD",
  "customerReference": "CNTT002",
  "bankChargeBearer": "SHARED",
  "regulatoryInstructionInfo": ["/CNS1/Trade settlement"],
  "regulatoryAmounts": [{ "amount": 1000000, "currency": "USD" }],
  "regulatoryInformation": ["O/C/600101/A/Zhang Wei", "/N/13800138000", "", "", "12345678/CHN", ""],
  "receiver": {
    "name": "Shanghai Export Co",
    "bank": "CITIUS33XXX",
    "bankAccountNumber": "9876543210",
    "accountName": "Shanghai Export Account Title",
    "address": {
      "line1": "100 Wall Street",
      "city": "New York",
      "state": "NY",
      "postalCode": "10005",
      "country": "US"
    }
  }
}
```

That SAFE block means:

| String                   | Meaning                                                         |
| ------------------------ | --------------------------------------------------------------- |
| `/CNS1/Trade settlement` | Code 1 remark                                                   |
| `O/C/600101/A/Zhang Wei` | Overseas, business, code `600101`, advance, applicant Zhang Wei |
| `/N/13800138000`         | No Code 2, not bonded, phone                                    |
| `12345678/CHN`           | Unit code + resident country China                              |

### Example: `CN_TT_DOM` [#example-cn_tt_dom]

Same three SAFE fields. Use **CNY** for `amount` and `regulatoryAmounts`.

```json
{
  "amount": 1000000,
  "currency": "CNY",
  "customerReference": "CNTTDOM0001",
  "bankChargeBearer": "SHARED",
  "paymentDetails": "Invoice 2024-001",
  "regulatoryInstructionInfo": ["/CNS1/Trade settlement"],
  "regulatoryAmounts": [{ "amount": 1000000, "currency": "CNY" }],
  "regulatoryInformation": ["O/C/600101/A/Zhang Wei", "/N/13800138000", "", "", "12345678/CHN", ""],
  "receiver": {
    "name": "Shanghai Import Export Co",
    "bank": "Bank of Shanghai Co Ltd",
    "bankAccountNumber": "9876543210",
    "accountName": "账户户名",
    "address": {
      "line1": "100 Huangpu Road",
      "city": "Shanghai",
      "country": "CN"
    }
  }
}
```