# Acme Citibank Philippines Payments (H2H) (https://docs.tryacme.com/guides/citi-ph-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 Philippines. 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: `PH_PESONET`, `PH_RTGS`, `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 ` `

* PESONet Character Set:
  * The 26 uppercase Latin letters `A`-`Z`
  * The 26 lowercase Latin letters `a`-`z`
  * The 10 digits `0`-`9`
  * Full stop `.`
  * Comma `,`
  * Hyphen `-`
  * Ampersand `&`
  * Left and right parentheses `(` `)`
  * Space ` `

* BIC:
  * 8 or 11 character Bank Identifier Code in uppercase, for example `BOPIPHMMXXX`.

* 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. It can be at most 20 days ahead.
* `amount` is in minor units. For example, `150000` is PHP 1,500.00. See [Minor units format](https://docs.tryacme.com/guides/minor-units-format).
* The maximum amount per payment is PHP 9,999,999,999.99 for `PH_PESONET`.
* For `PH_RTGS`, `TT` and `BKTR`, it is 999,999,999 minor units. For PHP, that is PHP 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 the Philippines, this applies to `PH_RTGS` and `TT`. `PH_PESONET` and `BKTR` are not in Citi's scope.
> * For `PH_RTGS`, Citi rejects a payment whose address is missing `address.city` or `address.country`.
> * This becomes mandatory in November 2026.
> * For `TT`, Citi has not confirmed the date it starts rejecting these payments.
> * Acme already enforces this:
>   * `PH_RTGS`: the address is optional. If you provide it, `address.city` and `address.country` are mandatory, and `address.country` must be `PH`.
>   * `TT`: `address.city` and `address.country` are always mandatory.
> * 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.

## PH_PESONET [#ph_pesonet]

> **Important**
>
> * Currency must be **PHP only**.
> * Send the 8 digit BRSTN code of the receiver's bank branch in `receiver.localRoutingIdentifier`.
> * `receiver.bankName` is mandatory.
> * Do not send `bankChargeBearer` or `instructionForSenderBank`.
> * Acme sends every `PH_PESONET` payment with Citi purpose code `21` (Standing Instruction Credit). You cannot set the purpose code.

| field | pattern / charset | max length | mandatory/optional |
| --- | --- | --- | --- |
| paymentDate | `YYYY-MM-DD` | | M |
| payments[N].customerReference | SWIFT (uppercase only) | 15 | O |
| payments[N].paymentDetails | PESONet | 105 | O |
| payments[N].receiver.name | PESONet | 35 | M |
| payments[N].receiver.bank | BIC | 11 | M |
| payments[N].receiver.bankName | SWIFT | 140 | M |
| payments[N].receiver.bankAccountNumber | Alphanumeric | 34 | M |
| payments[N].receiver.localRoutingIdentifier | 8 digits (BRSTN) <br /> Example: `01033001` | 8 | 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 | `PH` | 2 | O |

Example Request:

```json
{
  "type": "PH_PESONET",
  "paymentDate": "2026-11-16",
  "senderAccountId": "intacc_0H3BQNTQGBW2W",
  "currency": "PHP",
  "payments": [
    {
      "amount": 2500000,
      "customerReference": "INV2026001",
      "paymentDetails": "Payment for invoice 2026001",
      "receiver": {
        "name": "Juan dela Cruz",
        "bank": "BOPIPHMMXXX",
        "bankName": "Bank of the Philippine Islands",
        "bankAccountNumber": "1234567890",
        "localRoutingIdentifier": "01033001"
      }
    }
  ]
}
```

## PH_RTGS [#ph_rtgs]

> **Important**
>
> * Currency must be **PHP only**.
> * `bankChargeBearer` is mandatory.
> * `purposeCode` is not supported for this payment type.
> * Do not send `instructionForSenderBank`.
> * If you provide `receiver.address`, `address.city` and `address.country` are mandatory, and `address.country` must be `PH`. 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 | 140 | O |
| payments[N].bankChargeBearer | `SENDER` or `RECEIVER` or `SHARED` | | M |
| payments[N].paymentAdviceEmails[N] | Valid email address <br /> 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.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 | 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 | `PH` | 2 | Conditional: M if `address` is provided ([ISO 20022](#iso-20022-migration)) |

Example Request:

```json
{
  "type": "PH_RTGS",
  "paymentDate": "2026-11-16",
  "senderAccountId": "intacc_0H3BQNTQGBW2W",
  "currency": "PHP",
  "payments": [
    {
      "amount": 500000000,
      "customerReference": "INV2026002",
      "paymentDetails": "Payment for invoice 2026002",
      "bankChargeBearer": "SENDER",
      "receiver": {
        "name": "Example Trading Corporation",
        "bank": "BOPIPHMMXXX",
        "bankAccountNumber": "1234567890",
        "address": {
          "line1": "1 Ayala Avenue",
          "city": "Makati City",
          "country": "PH"
        }
      }
    }
  ]
}
```

## TT [#tt]

> **Important**
>
> * Currency can be any valid ISO 4217 currency code.
> * `purposeCode` is mandatory. Use a 10 digit code from [Citibank Philippines Purpose Codes](https://docs.tryacme.com/guides/citi-ph-purpose-codes).
> * `receiver.address.city` and `receiver.address.country` are always mandatory. See [ISO 20022 Migration](#iso-20022-migration).
> * If `bankChargeBearer` is not provided, Acme sends `SHARED`.

| field | pattern / charset | max length | mandatory/optional |
| --- | --- | --- | --- |
| paymentDate | `YYYY-MM-DD` | | M |
| payments[N].customerReference | SWIFT (uppercase only) | 15 | O |
| payments[N].paymentDetails | SWIFT | 140 | O |
| payments[N].instructionForSenderBank | SWIFT | 35 | O |
| payments[N].purposeCode | Alphanumeric <br /> See [purpose codes](https://docs.tryacme.com/guides/citi-ph-purpose-codes) | 10 | M |
| payments[N].bankChargeBearer | `SENDER` or `RECEIVER` or `SHARED` <br /> Default to `SHARED` if not provided. | | O |
| payments[N].paymentAdviceEmails[N] | Valid email address <br /> 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": "INV2026003",
      "paymentDetails": "Payment for invoice 2026003",
      "purposeCode": "0420000005",
      "bankChargeBearer": "SHARED",
      "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 Philippines account. Do not send `receiver.bank`.
> * Currency can be any valid ISO 4217 currency code.
> * `receiver.bankAccountNumber` is up to 10 characters.
> * `purposeCode` is optional. If you send it, use a 10 digit code from [Citibank Philippines Purpose Codes](https://docs.tryacme.com/guides/citi-ph-purpose-codes).
> * Do not send `bankChargeBearer`.

| field | pattern / charset | max length | mandatory/optional |
| --- | --- | --- | --- |
| paymentDate | `YYYY-MM-DD` | | M |
| payments[N].customerReference | SWIFT (uppercase only) | 15 | O |
| payments[N].paymentDetails | SWIFT | 140 | O |
| payments[N].instructionForSenderBank | SWIFT | 35 | O |
| payments[N].purposeCode | Alphanumeric <br /> See [purpose codes](https://docs.tryacme.com/guides/citi-ph-purpose-codes) | 10 | O |
| payments[N].paymentAdviceEmails[N] | Valid email address <br /> 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.bankAccountNumber | Alphanumeric | 10 | 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 | `PH` | 2 | O |

Example Request:

```json
{
  "type": "BKTR",
  "paymentDate": "2026-11-16",
  "senderAccountId": "intacc_0H3BQNTQGBW2W",
  "currency": "PHP",
  "payments": [
    {
      "amount": 2500000,
      "customerReference": "INV2026004",
      "paymentDetails": "Payment for invoice 2026004",
      "receiver": {
        "name": "Example Trading Corporation",
        "bankAccountNumber": "1234567890"
      }
    }
  ]
}
```

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