AED payout integration guide

​

Before you start

• Your organization must be enabled for AED. Until it is, a request in it fails with 403 PAYOUT_CURRENCY_NOT_ENABLED.
• The recipient’s account needs the UAE-dirham receiving capability, ACTIVE before you pay. Capabilities lists the id, and Be paid in UAE dirhams lists the identity the recipient owes.
• AED has no sending capability. Don’t send a sender on a quote or payout, or it fails with 422 SENDER_NOT_SUPPORTED.
• Every POST needs an Idempotency-Key header. See Idempotency.

​

Register the bank account and create the payout

curl -X POST https://api.openfx.com/v3/payments/payout-addresses \
  -H "Authorization: Bearer $OPENFX_JWT" \
  -H "X-Request-Signature: $OPENFX_SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "payoutAddressType": "BANK_ACCOUNT",
    "accountId": "acc_BMY3UenpGBn8ZQ8hio4BgE",
    "bankAccount": { "routingFamily": "AE_LOCAL", "accountNumber": "AE070331234567890123456" }
  }'

• Every payout needs a purpose. Send one of GOODS_AND_SERVICES, INVESTMENTS, PAYROLL, or TREASURY_MANAGEMENT. OTHER is refused. A missing or refused value fails with 400 PURPOSE_INVALID. A quote carries no purpose, so send it when you create the payout.
• You fund it from a stablecoin or AED balance. The financial account must hold USDC, USDT, EURC, or AED. Any other send currency fails with 422 QUOTE_SEND_CURRENCY_UNAVAILABLE.
• Per-payout limits apply. A receiveAmount outside them is refused when the payout is priced, with 422 AMOUNT_OUT_OF_RANGE. error.details carries the exact bound.

curl -X POST https://api.openfx.com/v3/payments/payouts \
  -H "Authorization: Bearer $OPENFX_JWT" \
  -H "X-Request-Signature: $OPENFX_SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "INLINE",
    "financialAccountId": "finacc_AmKC5dMVXUbiAW8VzKBfqz",
    "receiver": { "payoutAddressId": "pytadd_PbDQ126YUAbkNrNX6XbGL" },
    "receiveAmount": "5000.00",
    "receiveCurrency": "AED",
    "purpose": "GOODS_AND_SERVICES",
    "receiverMemo": "Invoice 4012"
  }'

​

Memos

​

Track settlement

​

Common mistakes

• Naming a sender. AED has no sending capability. Remove sender from the quote and the payout.
• Leaving out purpose, or sending OTHER. Both fail with 400 PURPOSE_INVALID. Pick the closest of the other four values.
• Funding the payout from another currency. Fund it from USDC, USDT, EURC, or AED.

​

What’s next

Payout lifecycle

The general payout flow.

Capabilities

The receiving capability and identity each currency needs.

EUR payout integration guide

Paying euro accounts over SEPA or SWIFT.

MXN payout integration guide

Paying Mexican bank accounts over SPEI.

COP payout integration guide

Paying Colombian bank accounts and Bre-B keys.

Payment Webhooks

Every payout and address event.