Payout

Payout

curl --request POST \
  --url https://api.example.com/api/v1/user/payout

POST

api

user

payout

Payout

curl --request POST \
  --url https://api.example.com/api/v1/user/payout

Requires Authorization: Bearer <user-access-token> — the token from Verify login code. See Authentication for details.

Initiates a payout to an external destination. The transactionId field acts as an idempotency key — use a unique UUID per operation to safely retry requests without creating duplicate payouts. Payouts are asynchronous. A successful response means the request was accepted for processing; use transaction status endpoints or partner notifications to track the final result.

Request

POST /api/v1/user/payout
Authorization: Bearer <user-access-token>

Body

Field	Type	Required	Description
`transactionId`	string	Yes	UUID idempotency key — unique per operation
`amount`	number	Yes	Decimal amount in the destination asset’s major unit (e.g. `5000` = COP 5,000.00) — not a smallest-unit integer
`asset`	string	Yes	Asset to send — e.g. `"COP"`
`description`	string	No	Optional description
`provider`	string	Yes	Payment provider — e.g. `"cobre"` or `"irisbank"`
`source`	object	Yes	Funding account information provided during setup
`destination.accountNumber`	string	Yes	Bank account number
`destination.accountType`	string	Yes	`"H"` (savings) or `"C"` (checking)
`destination.bankName`	string	No	Bank name
`destination.bankNumber`	string	No	Bank code
`destination.ownerName`	string	Yes	Account holder full name
`destination.ownerDocumentType`	string	Yes	`"CC"`, `"CE"`, `"NIT"`, `"PA"`, or `"PPT"`
`destination.ownerDocumentNumber`	string	Yes	Document number

{
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 5000,
  "asset": "COP",
  "description": "Bank withdrawal",
  "provider": "cobre",
  "source": {
    "metadata": {
      "cobreId": "src_abc123"
    }
  },
  "destination": {
    "accountNumber": "1234567890",
    "accountType": "H",
    "bankName": "Bancolombia",
    "bankNumber": "007",
    "ownerName": "Juan Pérez",
    "ownerDocumentType": "CC",
    "ownerDocumentNumber": "1234567890"
  }
}

Response

200 OK

{
  "success": true,
  "paymentId": "pay_abc123",
  "status": "PROCESSING",
  "message": "Payout accepted"
}

Field	Type	Description
`success`	boolean	`true` when the payout was accepted
`paymentId`	string	Provider payment identifier
`status`	string	Current processing status — commonly `"PENDING"` or `"PROCESSING"`
`message`	string	Human-readable processing message, when available

Payouts are processed asynchronously. An accepted request is not the same as final settlement. Poll Get transaction or listen for partner notifications to track the final status.

Exchange rates / TRM

Cards

Users

Login

User profile

KYC

Account Management

Financials

Request

Body

Response

​Request

​Body

​Response

Request

Body

Response