COP payout integration guide

Pay a Colombian recipient in Colombian pesos (COP), to a bank account or a Bre-B key. For the general flow, see Payout lifecycle. The quote, confirm, and webhook steps are the same as for EUR, and so is the fee model. Supported payout currencies compares every payout currency side by side.

Before you start

Your organization must be enabled for COP. Until it is, a request in it fails with 403 PAYOUT_CURRENCY_NOT_ENABLED.
The recipient’s account needs the Colombian-peso receiving capability, ACTIVE before you pay. Capabilities lists the id, and Be paid in Colombian pesos lists the identity the recipient owes.
COP 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 or Bre-B key

A Colombian recipient can be paid in two ways, and the address you register decides which. The recipient owes a nationality and an identity document, or for an organization a NIT. See Be paid in Colombian pesos.

Bank account
Bre-B key

Register the account with routingFamily CO_LOCAL, the four-digit bankCode, the accountNumber, and the bankAccountType. The payout goes over CO_ACH. OpenFX decides whether it settles the same day or in the next clearing batch, and you can’t choose.The bankAccountType is checked against the kinds the bank accepts, and a kind it doesn’t accept is rejected when you create the address. No name check runs, so verifications[] stays empty.

cURL

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": "CO_LOCAL",
      "bankCode": "1007",
      "accountNumber": "24512345678",
      "bankAccountType": "SAVINGS"
    }
  }'

Register the key with routingFamily CO_BREB and the brebKey, written exactly as the account holder gave it: a mobile number, an email address, an identity document number, or a handle with its leading @. You don’t say which kind it is. The payout goes over BREB, Colombia’s instant transfer system.A key lookup (BREB_KEY_LOOKUP) runs while you create the address and compares the holder the key is registered to with the account holder’s name. Only a NO_MATCH result rejects the address. A lookup that can’t complete leaves it payable.Each BREB payout is capped at about COP 12,110,000. A larger receiveAmount is refused when the payout is priced, with 422 AMOUNT_OUT_OF_RANGE. error.details carries the exact bound.

cURL

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": "CO_BREB", "brebKey": "@camilarestrepo" }
  }'

Memos

On CO_ACH and BREB, a receiverMemo is at most 40 letters, digits, and spaces. A memo that is too long or holds any other character fails with 400 RECEIVER_MEMO_INVALID. OpenFX never truncates it.

Track settlement

Trace a payout with the receiving bank lists the settlementTraceId key for CO_ACH and BREB.

Common mistakes

Naming a sender. COP has no sending capability. Remove sender from the quote and the payout.
Sending purpose. Only AED takes one.
Paying a Bre-B recipient more than the cap. A receiveAmount above about COP 12,110,000 fails with 422 AMOUNT_OUT_OF_RANGE.

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.

AED payout integration guide

Paying UAE bank accounts by IBAN.

Payment Webhooks

Every payout and address event.

Get Started

Convert

Send

COP payout integration guide

Before you start

Register the bank account or Bre-B key

Memos

Track settlement

Common mistakes

What’s next

Payout lifecycle

Capabilities

EUR payout integration guide

MXN payout integration guide

AED payout integration guide

Payment Webhooks

​Before you start

​Register the bank account or Bre-B key

​Memos

​Track settlement

​Common mistakes

​What’s next

Payout lifecycle

Capabilities

EUR payout integration guide

MXN payout integration guide

AED payout integration guide

Payment Webhooks

Before you start

Register the bank account or Bre-B key

Memos

Track settlement

Common mistakes

What’s next