Skip to main content

Create a Payout

Create a new payout to send funds to third parties' bank accounts or BreB keys. Each item specifies its own channel and channel_data, allowing mixed channels in a single payout.

POST/v1/payouts
curl -X POST 'https://api.minteo.finance/v1/payouts' \
-H 'Authorization: Bearer <your-api-key>' \
-H 'Content-Type: application/json' \
-d '{
"origin_source_id": "2af83836-43ea-407b-ab4e-9c64ee817b28",
"items": [
{
"amount": "50000",
"full_name": "John Doe",
"token": "COPM",
"legal_identifier_type": "CC",
"legal_identifier": "123456789",
"country_iso": "CO",
"channel": "TURBO",
"channel_data": {
"bank_name": "BANCO_FALABELLA",
"type": "SAVINGS",
"number": "2109309321"
}
}
]
}'
RESPONSE
{
"output": {
"id": "d5e5262c-5697-408d-bb9b-48c3cf8c2f89",
"created_at": "2024-10-18T01:43:02.763Z",
"updated_at": "2024-10-18T01:43:02.763Z",
"finished_at": null,
"fee_type": "STANDARD",
"fee_amount": "700",
"transfer_amount": "50000",
"refunded_amount": null,
"status": "PENDING",
"status_code": "AWAIT_PROCESSING",
"origin_source_id": "2af83836-43ea-407b-ab4e-9c64ee817b28",
"refund_wallet_id": null,
"public_data": {
"creator_type": "SYSTEM",
"creator_identifier": "pKwqg9A7F832CAIX",
"deposit_wallet_address": "0x6f2D66cF59Cf6C1c2609f0127c91A480020dC2fd"
},
"activities": [
{
"type": "AWAIT_PROCESSING",
"status": "PENDING",
"last_update_at": "2024-10-18T01:43:02.761Z"
}
]
},
"code": "CREATED"
}

Endpoint​

POST/v1/payouts

Scope​

payouts:create

Request​

Request Body​

origin_source_iduuid

Wallet ID where the tokens come from. The wallet must be active. Use Get Wallets to retrieve this ID.

itemsArray<New Payout Item>

The items to create the payout. Each item specifies its own channel and channel_data.

transaction_hashstring

Optional. Hash of the on-chain token deposit that funds this payout, in the format 0x followed by 64 hexadecimal characters. Only EVM chains are supported. See Funding Deposit Transaction Hash.

refund_wallet_iduuid

Optional. ID of one of your registered wallets that receives the tokens if the payout is refunded. When omitted, refunds go to the origin source wallet. Use Get Wallets to retrieve this ID. See Refund Wallet.

Item Fields​

amountstring

Numeric string, up to 18 digits before and after the decimal point.

full_namestring

Full name of the third party.

tokenstring

Stablecoin token. Use COPM in production, testCOPM in sandbox.

legal_identifier_typestring

Legal identifier type. Valid values: NIT, CC, CE, PP, PPT. PPT (Permiso por Protección Temporal) is accepted for payouts only, with a numeric value of up to 10 digits. Some disbursement rails do not accept every document type: when the rail chosen for an item cannot pay it, the item is rejected with VALIDATIONS_FAILED before any funds move, and its tokens are refunded.

legal_identifierstring

Legal identifier of the third party. Numeric string.

country_isostring

Country ISO code. Currently only CO.

channelstring

Disbursement channel for this item: SAVE (standard), TURBO (fast), or BREB (instant interbank via BreB keys).

channel_dataobject

Channel-specific details. Structure depends on the channel value — see below.

Minimum Amount

Minimum amount depends on the channel:

  • SAVE / TURBO (bank transfers): minimum 10,000 COP
  • BREB (BreB keys): minimum 100 COP, maximum 11,500,000 COP

Items below the minimum are automatically rejected with status REJECTED and status_code VALIDATIONS_FAILED.

Funding Deposit Transaction Hash​

Transaction Hash

Send transaction_hash to state which deposit funds the payout. This is useful when several payouts from the same wallet share the same amount. It must be the hash of the transfer of the payout's token from the origin source wallet to the deposit wallet, for the payout's exact transfer amount. Sandbox and live behave the same for this field.

The deposit is reserved for this payout: another payout from the same wallet and amount that did not send a hash will not take it. Without transaction_hash, deposits are matched to payouts in order of creation.

The hash is verified against the chain after the payout is created:

  • While the transaction is pending or not yet final, the payout keeps waiting.
  • If the deposit arrived before this payout was created and already funded another payout from the same wallet and amount that sent no hash, the payout waits with status code AWAIT_REPLACEMENT_DEPOSIT. As soon as another deposit of the same amount arrives from that wallet, it funds that other payout and this payout gets the deposit it claimed.
  • If the transaction cannot be found on chain, the payout is ABORTED with status code TRANSACTION_NOT_FOUND.
  • If the transaction does not match the payout (wrong sender, receiver, token or amount, reverted, already used by another order, bridge or payout, or refunded or invalid), the payout is ABORTED with status code TRANSACTION_MISMATCH.

The request is rejected with 422 Unprocessable (the response message carries the code) when:

  • VALIDATION_ERRORS: the hash format is invalid.
  • TRANSACTION_HASH_UNSUPPORTED_CHAIN: the origin source wallet is not on an EVM chain.
  • TRANSACTION_HASH_ALREADY_CLAIMED: another pending payout already claims this hash.
  • TRANSACTION_HASH_ALREADY_USED: the deposit already funds an order, a bridge, or a payout that claimed it, or it was refunded or is invalid.

Refund Wallet​

Refund Wallet

When a payout is refunded (for example, an item fails validations or the bank transfer fails), its tokens go back to a wallet. By default that is the origin source wallet. Send refund_wallet_id to send the refund to another of your wallets instead, for example when the deposit comes through an intermediary. Sandbox and live behave the same for this field.

The refund wallet must be one of your registered wallets, active, and on the same chain and token as the origin source wallet. It is checked when the payout is created and then used for every refund of that payout. The payout object returns it in refund_wallet_id (null when not sent).

The request is rejected (the response message carries the code) when:

  • 404 REFUND_WALLET_NOT_FOUND: the wallet does not exist or is not one of your wallets.
  • 422 REFUND_WALLET_NOT_ACTIVE: the wallet is not active. details.status carries its status.
  • 422 REFUND_WALLET_INCOMPATIBLE: the wallet is on another chain or token than the origin source wallet. details carries both.
  • 422 VALIDATION_ERRORS: refund_wallet_id is not a valid UUID.

The origin source wallet must be active too: otherwise the request is rejected with 422 SOURCE_NOT_ACTIVE.

SAVE / TURBO​

When channel is SAVE or TURBO, channel_data contains bank account details:

bank_namestring

Name of the bank. See Available Banks below. Use OUTBANK in sandbox.

typestring

Account type: SAVINGS or CHECKING.

numberstring

Bank account number. Numeric string. In sandbox, use 1111111111 for success or 2222222222 to simulate a KYC failure.

SAVE / TURBO EXAMPLE
{
"origin_source_id": "2af83836-43ea-407b-ab4e-9c64ee817b28",
"items": [
{
"amount": "50000",
"full_name": "John Doe",
"token": "COPM",
"legal_identifier_type": "CC",
"legal_identifier": "123456789",
"country_iso": "CO",
"channel": "TURBO",
"channel_data": {
"bank_name": "BANCO_FALABELLA",
"type": "SAVINGS",
"number": "2109309321"
}
}
]
}

BREB​

When channel is BREB, channel_data contains BreB key details:

key_typestring

The type of BreB key. Valid values: ALPHANUMERIC, PHONE, EMAIL, ID, BCODE.

key_valuestring

The recipient's BreB key. Format depends on key_type:
• ALPHANUMERIC — Starts with @ followed by alphanumeric characters (e.g., @johndoe123).
• PHONE — Exactly 10 digits (e.g., 3107654321).
• EMAIL — A valid email address (e.g., john@example.com).
• ID — Alphanumeric document number (e.g., 1234567890).
• BCODE — Commercial entity code: exactly 10 digits, starts with 00 (e.g., 0030653059).

BREB EXAMPLE
{
"origin_source_id": "2af83836-43ea-407b-ab4e-9c64ee817b28",
"items": [
{
"amount": "50000",
"full_name": "Jane Doe",
"token": "COPM",
"legal_identifier_type": "CC",
"legal_identifier": "987654321",
"country_iso": "CO",
"channel": "BREB",
"channel_data": {
"key_type": "PHONE",
"key_value": "3107654321"
}
}
]
}

Mixed Channels​

A single payout can contain items with different channels:

MIXED CHANNELS EXAMPLE
{
"origin_source_id": "2af83836-43ea-407b-ab4e-9c64ee817b28",
"items": [
{
"amount": "50000",
"full_name": "John Doe",
"token": "COPM",
"legal_identifier_type": "CC",
"legal_identifier": "123456789",
"country_iso": "CO",
"channel": "TURBO",
"channel_data": {
"bank_name": "BANCO_FALABELLA",
"type": "SAVINGS",
"number": "2109309321"
}
},
{
"amount": "50000",
"full_name": "Jane Doe",
"token": "COPM",
"legal_identifier_type": "CC",
"legal_identifier": "987654321",
"country_iso": "CO",
"channel": "BREB",
"channel_data": {
"key_type": "PHONE",
"key_value": "3107654321"
}
}
]
}

Available Banks​

For channel_data.bank_name when using SAVE or TURBO:

View available banks
  • BANCAMIA
  • BANCIEN
  • BANCO_AGRARIO
  • BANCO_AV_VILLAS
  • BANCO_BBVA
  • BANCO_BTG_PACTUAL
  • BANCO_CAJA_SOCIAL_BCSC
  • BANCO_COMPARTIR
  • BANCO_CONTACTAR
  • BANCO_COOPERATIVO_COOPCENTRAL
  • BANCO_DAVIVIENDA
  • BANCO_DE_BOGOTA
  • BANCO_DE_OCCIDENTE
  • BANCO_FALABELLA
  • BANCO_GNB_SUDAMERIS
  • BANCO_JP_MORGAN
  • BANCO_MULTIBANK
  • BANCO_MUNDO_MUJER
  • BANCO_PICHINCHA
  • BANCO_POPULAR
  • BANCO_PROCREDIT
  • BANCO_SANTANDER
  • BANCO_SERFINANZA
  • BANCO_UNION
  • BANCO_W
  • BANCOLDEX
  • BANCOLOMBIA
  • BANCOOMEVA
  • BNP_PARIBAS
  • BOLD
  • CITIBANK
  • COINK
  • COLTEFINANCIERA
  • CONFIAR
  • DAVIPLATA
  • DING_TECNIPAGOS_SA
  • FINANCIERA_JURISCOOP
  • GLOBAL66
  • IRIS
  • ITAU_CORPBANCA_COLOMBIA_S_A
  • ITAU
  • JFK_COOPERATIVA_FINANCIERA
  • JP_MORGAN_CORPORACION_FINANCION
  • LULO_BANK
  • MOVII_SA
  • NEQUI
  • NU
  • PIBANK
  • POWWI
  • RAPPIPAY
  • SANTANDER_CONSUMER
  • SCOTIABANK_COLPATRIA
  • UALA
Sandbox Behavior

In sandbox, all payout items are automatically marked as SUCCEEDED after token burn — no real disbursement occurs. This applies to all channels (SAVE, TURBO, and BREB).


Response​

Returns a Payout object.