Acme Zand Bank UAE Payments (API)

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

Common Definitions

• BIC8 / BIC11:

  • Bank Identifier Code, 8 to 11 characters (uppercase letters + digits).
  • Required for international (TT) transfers.

• IBAN:

  • 23-character International Bank Account Number starting with the AE country prefix.
  • Required for all domestic transfers (BKTR, UAE_FTS, UAE_IBFT).

• customerReference:

  • Must be 16–40 characters (alphanumeric + hyphen).
  • If value is null or shorter than 16, Acme generates a 16 characters UUID and replaces it.

• Allowed currencies: AED, BHD, CNY, EUR, GBP, HKD, INR, QAR, SAR, SGD, USD.

General notes

• For domestic transfers, Zand auto-selects and routes the underlying rail by amount:
  • FTS for amounts > 50,000 AED (high value)
  • IPI for amounts ≤ 50,000 AED (low value)
• The purposeCode is required for all payment types and defaults to FIS if not supplied. Refer to the list from Central Bank UAE.

BKTR

Book Transfer — intra-Zand. Same-bank transfer between two Zand accounts.

Important

• Currency must be one of the 11 allowed currencies (typically AED).
• customerReference must be 16–40 characters.
• Receiver IBAN must be a valid UAE IBAN (23 chars, AE prefix).

field	pattern / charset	max length	mandatory/optional
customerReference	Alphanumeric + hyphen	16–40	M
paymentDetails	Free text	100	M
purposeCode	3-letter code (defaults to FIS)	3	O
receiver.name	Free text	75	M
receiver.iban	UAE IBAN (AE + 21 chars)	23	M

Example Request:

{
  "type": "BKTR",
  "amount": 100000,
  "currency": "AED",
  "customerReference": "1234567890ABCDEF",
  "paymentDetails": "Invoice INV-12345",
  "purposeCode": "FIS",
  "senderAccountId": "intacc_0H3BQNT7HBW2W",
  "receiver": {
    "name": "Test Receiver Name",
    "iban": "AE360961000061010000012"
  }
}

UAE_FTS

UAE Interbank Fund Transfer Service via the domestic API. Used for high-value transfers (> 50,000 AED).

Important

• Currency must be one of the 11 allowed currencies (typically AED).
• customerReference must be 16–40 characters.
• Receiver IBAN must be a valid UAE IBAN (23 chars, AE prefix).

field	pattern / charset	max length	mandatory/optional
customerReference	Alphanumeric + hyphen	16–40	M
paymentDetails	Free text	100	M
purposeCode	3-letter code (defaults to FIS)	3	O
receiver.name	Free text	75	M
receiver.iban	UAE IBAN (AE + 21 chars)	23	M

Example Request:

{
  "type": "UAE_FTS",
  "amount": 250000,
  "currency": "AED",
  "customerReference": "1234567890ABCDEF",
  "paymentDetails": "Invoice INV-12345",
  "purposeCode": "FIS",
  "senderAccountId": "intacc_0H3BQNT7HBW2W",
  "receiver": {
    "name": "Test Receiver Name",
    "iban": "AE070331234567890123456"
  }
}

UAE_IBFT

UAE Interbank Immediate Payment Instruction (IPI) via the domestic API. Used for low-value transfers (≤ 50,000 AED).

Important

• Currency must be one of the 11 allowed currencies (typically AED).
• customerReference must be 16–40 characters.
• Receiver IBAN must be a valid UAE IBAN (23 chars, AE prefix).

field	pattern / charset	max length	mandatory/optional
customerReference	Alphanumeric + hyphen	16–40	M
paymentDetails	Free text	100	M
purposeCode	3-letter code (defaults to FIS)	3	O
receiver.name	Free text	75	M
receiver.iban	UAE IBAN (AE + 21 chars)	23	M

Example Request:

{
  "type": "UAE_IBFT",
  "amount": 5000,
  "currency": "AED",
  "customerReference": "1234567890ABCDEF",
  "paymentDetails": "Invoice INV-12345",
  "purposeCode": "FIS",
  "senderAccountId": "intacc_0H3BQNT7HBW2W",
  "receiver": {
    "name": "Test Receiver Name",
    "iban": "AE220211234567890123456"
  }
}

TT

Telegraphic Transfer — Cross-border International SWIFT transfer

Important

• customerReference minimum 16 characters. Total 16–40 characters.
• Receiver BIC required, 8–11 characters.
• Receiver postal address required (line1, city, country).
• Country must be ISO 3166-1 alpha-2 (2 chars).
• receiver.beneficiaryType must be INDIVIDUAL or COMPANY.

field	pattern / charset	max length	mandatory/optional
customerReference	Alphanumeric + hyphen	16–40	M
paymentDetails	Free text	100	M
purposeCode	3-letter code (defaults to FIS)	3	O
receiver.name	Free text	75	M
receiver.bank	BIC8 / BIC11	8–11	M
receiver.iban	Beneficiary account IBAN	—	M
receiver.address.line1	Free text	—	M
receiver.address.line2	Free text	—	O
receiver.address.city	Free text	—	M
receiver.address.state	Free text	—	O
receiver.address.country	ISO 3166-1 alpha-2	2	M
receiver.address.postalCode	Free text	—	O
receiver.beneficiaryType	INDIVIDUAL or COMPANY	—	O

Example Request:

{
  "type": "TT",
  "amount": 10000,
  "currency": "USD",
  "customerReference": "1234567890ABCDEF",
  "paymentDetails": "Invoice INV-12345",
  "purposeCode": "FIS",
  "senderAccountId": "intacc_0H3BQNT7HBW2W",
  "receiver": {
    "name": "Test Receiver Name",
    "bank": "CHASUS33XXX",
    "iban": "GB29NWBK60161331926819",
    "address": {
      "line1": "123 Main Street",
      "city": "London",
      "country": "GB",
      "postalCode": "EC1A 1BB"
    },
      "beneficiaryType": "COMPANY"
  }
}

Payment Statuses

Zand Status	Terminal?	Acme Payment Status
INITIATED	No	SUBMITTED (workflow in progress)
PROCESSED	Yes	COMPLETED (FTS/IBFT success)
COMPLETED	Yes	COMPLETED
REJECTED	Yes	FAILED
REVERSED	Yes	FAILED (reversed by beneficiary bank — FTS/IBFT only)

Possible result codes for FAILED payments:

resultCode	Description
PAYMENT_REJECTED	Payment rejected.
PAYMENT_CANCELLED	Payment aborted or cancelled by user.
PAYMENT_EXPIRED	Payment expired.
REJECTED_BY_APPROVER	Payment rejected by authorizer.
REJECTED_BY_SENDING_BANK	Payment rejected by sending bank.
REJECTED_BY_RECEIVING_BANK	Payment rejected by receiving bank.
RETURNED	Payment returned (maps from Zand REVERSED).
PROCESSING_ERROR	Processing error encountered.
OTHERS	Default resultCode if status code returned is not a known status code.