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.

Legacy Format Deprecation

The previous format using preferred_channel, fee_type, network, bank_account_details, and payment_details will be removed after April 30, 2026. See Legacy Format for details. Please migrate to the format described below.

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",
    "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. 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.

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.

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.

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.

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).

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
  • 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).

Legacy Format​

Deprecation Notice

This format will be removed after April 30, 2026. Please migrate to the format described above using channel + channel_data per item.

The legacy format uses preferred_channel at the payout level (applied to all items) and network at the item level.

preferred_channelstring

Deprecated. Payout channel applied to all items. SAVE (default), TURBO (fast), or BREB (instant interbank).

fee_typestring

Deprecated. Will be removed after April 30, 2026.

origin_source_iduuid

Wallet ID where the tokens come from.

itemsArray<New Payout Item (Legacy)>

Items using network + bank_account_details or payment_details.

BANK network (SAVE/TURBO):

LEGACY — BANK EXAMPLE
{
  "origin_source_id": "2af83836-43ea-407b-ab4e-9c64ee817b28",
  "items": [
    {
      "amount": "20000",
      "full_name": "John Doe",
      "token": "COPM",
      "legal_identifier_type": "CC",
      "legal_identifier": "123456789",
      "country_iso": "CO",
      "network": "BANK",
      "bank_account_details": {
        "bank_name": "BANCO_FALABELLA",
        "type": "SAVINGS",
        "number": "2109309321"
      }
    }
  ]
}

BREB network:

LEGACY — BREB EXAMPLE
{
  "preferred_channel": "BREB",
  "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",
      "network": "BREB",
      "payment_details": {
        "key_value": "@johndoe123",
        "key_type": "ALPHANUMERIC"
      }
    }
  ]
}

Response​

Returns a Payout object.