Acme Citibank US Payments

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

Common DefinitionsCopy Anchor Link

• 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: /, -, :

US_ACHCopy Anchor Link

Note: CCD subtype is for sending to corporate accounts, it can only send to CHECKING account type. PPD subtype is for sending to personal accounts, it can use either CHECKING or SAVINGS.

Example:

{
  "type": "US_ACH",
  "subtype": "CCD",
  "currency": "USD",
  "payments": [
    {
      "amount": 100,
      "customerReference": "REF 01",
      "receiver": {
        "name": "Recipient Name",
        "bankName": "Test Bank",
        "localRoutingIdentifier": "123456789",
        "bankAccountNumber": "987654321",
        "accountType": "CHECKING"
      }
    },
    {
      "amount": 200,
      "customerReference": "REF 02",
      "receiver": {
        "name": "Recipient Two",
        "bankName": "Test Bank",
        "localRoutingIdentifier": "123456789",
        "bankAccountNumber": "967854321",
        "accountType": "CHECKING"
      }
    }
  ]
}

US_WIRE_DOMCopy Anchor Link

US Domestic Wire

• Use US_WIRE_DOM for book transfer and USD payments, use US_WIRE_INTL for other currencies

  field	pattern / charset	max length	mandatory/optional
  customerReference	SWIFT (uppercase only)	16	M
  paymentDetails	SWIFT	140	O
  bankChargeBearer	SENDER or RECEIVER or SHARED Default to SHARED if not provided.		O
  instructionForSenderBank	SWIFT	35	O
  receiver.name	SWIFT	140	M
  receiver.bank	Alphanumeric	11	M
  receiver.localRoutingIdentifier	Either bank or localRoutingIdentifier must be provided (not both) 4 digits: USCH (CHIPS ABA / participant number) or 6 digits: USCHU (CHIPS UID) or 9 digits: USABA (ABA)	9	M
  receiver.intermediaryBank	Alphanumeric	11	O
  receiver.bankName	SWIFT	35	M
  receiver.bankAccountNumber	Alphanumeric	34	M
  receiver.address.line1	SWIFT	35	O
  receiver.address.line2	SWIFT	35	O
  receiver.address.city	SWIFT	35	Conditional: M if address is provided
  receiver.address.state	SWIFT	35	O
  receiver.address.postalCode	SWIFT	16	O
  receiver.address.country	ISO 3166-1 alpha-2	2	Conditional: M if address is provided

US_WIRE_INTLCopy Anchor Link

• Use for any foreign currency except for USD

  field	pattern / charset	max length	mandatory/optional
  customerReference	SWIFT (uppercase only)	16	M
  paymentDetails	SWIFT	140	O
  bankChargeBearer	Only accept SHARED. Default to SHARED if not provided.		O
  instructionForSenderBank	SWIFT	35	O
  receiver.name	SWIFT	140	M
  receiver.bank	Alphanumeric	11	M
  receiver.intermediaryBank	Alphanumeric	11	O
  receiver.bankAccountNumber	Alphanumeric	34	M
  receiver.address.line1	SWIFT	35	O
  receiver.address.line2	SWIFT	35	O
  receiver.address.city	SWIFT	35	Conditional: M if address is provided
  receiver.address.state	SWIFT	35	O
  receiver.address.postalCode	SWIFT	16	O
  receiver.address.country	ISO 3166-1 alpha-2	2	Conditional: M if address is provided

US_RTPCopy Anchor Link

Bank referencesCopy Anchor Link

bankReference is AcctSvcrRef, else ClrSysRef, from Citi's status report on the payment. bankReferences lists every reference Citi sent, keyed by Citi's field name: AcctSvcrRef, ClrSysRef and StsId, as Citi sends them.

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 sent as a file returns:

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