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.
- Production
- Sandbox
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" } } ]}'{ "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"}curl -X POST 'https://api.sandbox.minteo.finance/v1/payouts' \-H 'Authorization: Bearer <your-api-key>' \-H 'Content-Type: application/json' \-d '{ "origin_source_id": "d0866d0f-7532-44bc-9466-126764682a0b", "items": [ { "amount": "20000", "full_name": "John Doe", "token": "testCOPM", "legal_identifier_type": "CC", "legal_identifier": "123456789", "country_iso": "CO", "channel": "SAVE", "channel_data": { "bank_name": "OUTBANK", "type": "SAVINGS", "number": "1111111111" } } ]}'{ "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": "20000", "refunded_amount": null, "status": "PENDING", "status_code": "AWAIT_PROCESSING", "origin_source_id": "d0866d0f-7532-44bc-9466-126764682a0b", "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
/v1/payoutsScope
payouts:create
Request
Request Body
origin_source_iduuidWallet 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_hashstringOptional. 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_iduuidOptional. 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
amountstringNumeric string, up to 18 digits before and after the decimal point.
full_namestringFull name of the third party.
tokenstringStablecoin token. Use COPM in production, testCOPM in sandbox.
legal_identifier_typestringLegal 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_identifierstringLegal identifier of the third party. Numeric string.
country_isostringCountry ISO code. Currently only CO.
channelstringDisbursement channel for this item: SAVE (standard), TURBO (fast), or BREB (instant interbank via BreB keys).
channel_dataobjectChannel-specific details. Structure depends on the channel value — see below.
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
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
ABORTEDwith status codeTRANSACTION_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
ABORTEDwith status codeTRANSACTION_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
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.statuscarries its status.422 REFUND_WALLET_INCOMPATIBLE: the wallet is on another chain or token than the origin source wallet.detailscarries both.422 VALIDATION_ERRORS:refund_wallet_idis 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_namestringName of the bank. See Available Banks below. Use OUTBANK in sandbox.
typestringAccount type: SAVINGS or CHECKING.
numberstringBank account number. Numeric string. In sandbox, use 1111111111 for success or 2222222222 to simulate a KYC failure.
{ "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_typestringThe type of BreB key. Valid values: ALPHANUMERIC, PHONE, EMAIL, ID, BCODE.
key_valuestringThe 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).
{ "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:
{ "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
- Production
- Sandbox
BANCAMIABANCIENBANCO_AGRARIOBANCO_AV_VILLASBANCO_BBVABANCO_BTG_PACTUALBANCO_CAJA_SOCIAL_BCSCBANCO_COMPARTIRBANCO_CONTACTARBANCO_COOPERATIVO_COOPCENTRALBANCO_DAVIVIENDABANCO_DE_BOGOTABANCO_DE_OCCIDENTEBANCO_FALABELLABANCO_GNB_SUDAMERISBANCO_JP_MORGANBANCO_MULTIBANKBANCO_MUNDO_MUJERBANCO_PICHINCHABANCO_POPULARBANCO_PROCREDITBANCO_SANTANDERBANCO_SERFINANZABANCO_UNIONBANCO_WBANCOLDEXBANCOLOMBIABANCOOMEVABNP_PARIBASBOLDCITIBANKCOINKCOLTEFINANCIERACONFIARDAVIPLATADING_TECNIPAGOS_SAFINANCIERA_JURISCOOPGLOBAL66IRISITAU_CORPBANCA_COLOMBIA_S_AITAUJFK_COOPERATIVA_FINANCIERAJP_MORGAN_CORPORACION_FINANCIONLULO_BANKMOVII_SANEQUINUPIBANKPOWWIRAPPIPAYSANTANDER_CONSUMERSCOTIABANK_COLPATRIAUALA
OUTBANK
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.