Create a BRE-B payout

Requires an approved customer. Creates a Bre-B external account and verifies name + key before returning the deposit transaction. 409 destination_mismatch if verify does not match. 409 needs_kyc if KYC is incomplete.

POST /api/integrations/breb/payouts

Create a BRE-B payout

cURL

curl --request POST \
  --url http://localhost:3000/api/integrations/breb/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "userAddress": "0x2222222222222222222222222222222222222222",
  "destinationCop": "10000",
  "breBKey": "31234567890",
  "accountOwnerName": "Ana Pérez"
}
'

200

{
  "payoutId": "<string>",
  "status": "<string>",
  "fromToken": "<string>",
  "sourceAmount": "<string>",
  "fees": [
    {
      "code": "swap",
      "amountUsd": "<string>",
      "to": "<string>",
      "status": "quoted"
    }
  ],
  "quote": {
    "display": "<string>",
    "effectiveUsdCop": "<string>"
  },
  "receipt": {
    "title": "Retiro Bre-B",
    "status": "<string>",
    "completedAt": "<string>",
    "transactionType": "withdrawal",
    "payoutId": "<string>",
    "breBKey": "<string>",
    "breBKeyLast4": "<string>",
    "beneficiaryName": "<string>",
    "totalPaid": {
      "amount": "<string>",
      "currency": "USD"
    },
    "exchangeRate": {
      "display": "1 USD = 3000 COP",
      "effectiveUsdCop": "<string>",
      "sellRateUsdCop": "<string>"
    },
    "commission": {
      "mode": "included_in_rate",
      "displayAmount": "0",
      "displayCurrency": "COP",
      "note": "<string>"
    },
    "totalReceived": {
      "amount": "<string>",
      "currency": "COP"
    },
    "feesItemized": [
      {
        "code": "swap",
        "amountUsd": "<string>",
        "to": "<string>",
        "status": "quoted"
      }
    ]
  },
  "deposit": {
    "chain": "<string>",
    "currency": "<string>",
    "address": "<string>",
    "amount": "<string>"
  },
  "transaction": {
    "approvalTarget": "<string>",
    "to": "<string>",
    "data": "<string>",
    "value": "0"
  },
  "feeTransaction": {
    "approvalTarget": "<string>",
    "to": "<string>",
    "data": "<string>",
    "value": "0"
  },
  "destinationPreview": {
    "accountOwnerName": "<string>",
    "bankName": "<string>",
    "documentLast4": "<string>"
  }
}

Authorizations

Authorization · string · header · required

Integration API key. Send as Bearer copby_live_pk_….

Headers

Idempotency-Key · string

Replays the same payout when reused by this integration

Body

application/json

userAddress · string · required

Pattern: ^0x[a-fA-F0-9]{40}$

Example:

"0x2222222222222222222222222222222222222222"

destinationCop · string · required

Example:

"10000"

breBKey · string · required

accountOwnerName · string · required

fromToken · enum<string> · default: USDC

Available options: USDC, COPm

quoteId · string

Response

200

application/json

Prepared payout

payoutId · string

status · string

fromToken · string

sourceAmount · string

fees · object[]

Hide child attributes

fees. code · enum<string>

Available options: swap, bridge_fx, bridge, copby

fees. amountUsd · string

fees. to · string | null

fees. status · enum<string>

Available options: quoted, verified, pending

quote · object

Hide child attributes

quote. display · string | null

quote. effectiveUsdCop · string | null

receipt · object

Consumer receipt (REQ-INT-RCPT-01). Fees are included in exchangeRate.effectiveUsdCop. Use feesItemized only for partner backoffice / disputes.

Hide child attributes

receipt. title · string

Example:

"Retiro Bre-B"

receipt. status · string

receipt. completedAt · string | null

receipt. transactionType · enum<string>

Available options: withdrawal

receipt. payoutId · string

receipt. breBKey · string | null

Masked key (last4), e.g. ···3143

receipt. breBKeyLast4 · string | null

receipt. beneficiaryName · string | null

receipt. totalPaid · object

Hide child attributes

receipt.totalPaid. amount · string

receipt.totalPaid. currency · enum<string>

Available options: USD

receipt. exchangeRate · object

Hide child attributes

receipt.exchangeRate. display · string | null

Example:

"1 USD = 3000 COP"

receipt.exchangeRate. effectiveUsdCop · string | null

receipt.exchangeRate. sellRateUsdCop · string | null

Wholesale Bridge rate (ops); hide on consumer UI

receipt. commission · object

Hide child attributes

receipt.commission. mode · enum<string>

Available options: included_in_rate

receipt.commission. displayAmount · string

Example:

"0"

receipt.commission. displayCurrency · enum<string>

Available options: COP, USD

receipt.commission. note · string

receipt. totalReceived · object

Hide child attributes

receipt.totalReceived. amount · string

receipt.totalReceived. currency · enum<string>

Available options: COP

receipt. feesItemized · object[]

Hide child attributes

receipt.feesItemized. code · enum<string>

Available options: swap, bridge_fx, bridge, copby

receipt.feesItemized. amountUsd · string

receipt.feesItemized. to · string | null

receipt.feesItemized. status · enum<string>

Available options: quoted, verified, pending

deposit · object

Hide child attributes

deposit. chain · string

deposit. currency · string

deposit. address · string

deposit. amount · string

transaction · object

Hide child attributes

transaction. approvalTarget · string | null

transaction. to · string

transaction. data · string

transaction. value · string

Example:

"0"

feeTransaction · object

Hide child attributes

feeTransaction. approvalTarget · string | null

feeTransaction. to · string

feeTransaction. data · string

feeTransaction. value · string

Example:

"0"

destinationPreview · object

Hide child attributes

destinationPreview. accountOwnerName · string

destinationPreview. bankName · string | null

destinationPreview. documentLast4 · string | null