# Acme Zand Bank UAE Payments (API) (/guides/zand-ae-payments)
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.
See [Acme Zand Bank UAE Transactions](/guides/zand-ae-transactions) for [Transactions API](/reference/get-transactions) `transactionType` categorization.
## Common Definitions [#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 [#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](https://www.centralbank.ae/media/ipaifsll/bop-purposeofpaymentcodestable-en-18092017.pdf).
## BKTR [#bktr]
Book Transfer — intra-Zand. Same-bank transfer between two Zand accounts.
* 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:
```json
{
"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_fts]
UAE Interbank Fund Transfer Service via the domestic API. Used for high-value transfers
(> 50,000 AED).
* 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:
```json
{
"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_ibft]
UAE Interbank Immediate Payment Instruction (IPI) via the domestic API. Used for low-value
transfers (≤ 50,000 AED).
* 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:
```json
{
"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 [#tt]
Telegraphic Transfer — Cross-border International SWIFT transfer
* `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:
```json
{
"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 [#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. |