Acme logoAcme docs
GuidesAPI referenceChangelog
Bank payment rules

Acme Citibank Philippines Payments (H2H)

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.
  • Single payments are not supported.

Supported types: PH_PESONET, PH_RTGS, TT, BKTR.

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

  • 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.
  • 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

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

  • 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

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.
fieldpattern / charsetmax lengthmandatory/optional
paymentDateYYYY-MM-DDM
payments[N].customerReferenceSWIFT (uppercase only)15O
payments[N].paymentDetailsPESONet105O
payments[N].receiver.namePESONet35M
payments[N].receiver.bankBIC11M
payments[N].receiver.bankNameSWIFT140M
payments[N].receiver.bankAccountNumberAlphanumeric34M
payments[N].receiver.localRoutingIdentifier8 digits (BRSTN)
Example: 01033001		8M
payments[N].receiver.address.line1SWIFT35O
payments[N].receiver.address.line2SWIFT35O
payments[N].receiver.address.citySWIFT35O
payments[N].receiver.address.stateSWIFT35O
payments[N].receiver.address.postalCodeSWIFT16O
payments[N].receiver.address.countryPH2O

Example Request:

{
  "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

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.
fieldpattern / charsetmax lengthmandatory/optional
paymentDateYYYY-MM-DDM
payments[N].customerReferenceSWIFT (uppercase only)15O
payments[N].paymentDetailsSWIFT140O
payments[N].bankChargeBearerSENDER or RECEIVER or SHAREDM
payments[N].paymentAdviceEmails[N]Valid email address
Example: ["finance@company.com"]		50 per email (max 1 email)O
payments[N].receiver.nameSWIFT35M
payments[N].receiver.bankBIC11M
payments[N].receiver.bankAccountNumberAlphanumeric34M
payments[N].receiver.address.line1SWIFT35O
payments[N].receiver.address.line2SWIFT35O
payments[N].receiver.address.citySWIFT35Conditional: M if address is provided (ISO 20022)
payments[N].receiver.address.stateSWIFT35O
payments[N].receiver.address.postalCodeSWIFT16O
payments[N].receiver.address.countryPH2Conditional: M if address is provided (ISO 20022)

Example Request:

{
  "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

Important

  • Currency can be any valid ISO 4217 currency code.
  • purposeCode is mandatory. Use a 10 digit code from Citibank Philippines Purpose Codes.
  • receiver.address.city and receiver.address.country are always mandatory. See ISO 20022 Migration.
  • If bankChargeBearer is not provided, Acme sends SHARED.
fieldpattern / charsetmax lengthmandatory/optional
paymentDateYYYY-MM-DDM
payments[N].customerReferenceSWIFT (uppercase only)15O
payments[N].paymentDetailsSWIFT140O
payments[N].instructionForSenderBankSWIFT35O
payments[N].purposeCodeAlphanumeric
See purpose codes		10M
payments[N].bankChargeBearerSENDER or RECEIVER or SHARED
Default to SHARED if not provided.		O
payments[N].paymentAdviceEmails[N]Valid email address
Example: ["finance@company.com"]		50 per email (max 1 email)O
payments[N].receiver.nameSWIFT35M
payments[N].receiver.bankBIC11M
payments[N].receiver.intermediaryBankBIC11O
payments[N].receiver.bankAccountNumberAlphanumeric34M
payments[N].receiver.address.line1SWIFT35O
payments[N].receiver.address.line2SWIFT35O
payments[N].receiver.address.citySWIFT35M (ISO 20022)
payments[N].receiver.address.stateSWIFT35O
payments[N].receiver.address.postalCodeSWIFT16O
payments[N].receiver.address.countryISO 3166-1 alpha-22M (ISO 20022)

Example Request:

{
  "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

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.
  • Do not send bankChargeBearer.
fieldpattern / charsetmax lengthmandatory/optional
paymentDateYYYY-MM-DDM
payments[N].customerReferenceSWIFT (uppercase only)15O
payments[N].paymentDetailsSWIFT140O
payments[N].instructionForSenderBankSWIFT35O
payments[N].purposeCodeAlphanumeric
See purpose codes		10O
payments[N].paymentAdviceEmails[N]Valid email address
Example: ["finance@company.com"]		50 per email (max 1 email)O
payments[N].receiver.nameSWIFT35M
payments[N].receiver.bankAccountNumberAlphanumeric10M
payments[N].receiver.address.line1SWIFT35O
payments[N].receiver.address.line2SWIFT35O
payments[N].receiver.address.citySWIFT35O
payments[N].receiver.address.stateSWIFT35O
payments[N].receiver.address.postalCodeSWIFT16O
payments[N].receiver.address.countryPH2O

Example Request:

{
  "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

Sent asbankReferencebankReferencesAvailable from
A fileAcctSvcrRef, else ClrSysRefAcctSvcrRef, ClrSysRef, StsId, as Citi sends themCiti'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:

{
  "bankReference": "01720322200000001",
  "bankReferences": {
    "AcctSvcrRef": "01720322200000001"
  }
}

Acme Citibank Malaysia Payments (API and H2H)

Previous Page

Acme Citibank Taiwan Payments (H2H)

Next Page

On this page

Common DefinitionsGeneral notesISO 20022 MigrationPayment Customer ReferencePH_PESONETPH_RTGSTTBKTRBank references