Payouts

A payout sends money to a person from your balance. Methods: mobile_payment (mobile payment, by phone) and bank_transfer (transfer to an account). The payout goes out right away; the outcome arrives by webhook.

Balance

A payout reserves the amount from your available balance when it is created (available → reserved), captures it when it is confirmed and releases it if it fails. The balance is an accounting record, not a brake: the payout goes out even if available ends up negative. GET /v2/balances shows you available and reserved per currency.

Cancelling

POST /v2/payouts/{id}/cancel cancels a payout that is still pending.

Cancelled → status: failed, failure.code: cancelled, balance released.
Too late → 409 not_cancellable (check the status: it was probably already confirmed).
The provider did not answer clearly → 503 temporarily_unavailable: the payout is still pending, nothing changed, and do not retry blindly: look it up.

Routes

Create a payout

POST/v2/payouts

Scopepayouts:crear

Creates a payout and sends it. It is ONE step: the amount is reserved from your available balance when created and deducted when confirmed; if the payout fails, it becomes available again.

Requires the payouts:crear scope.

The beneficiary fields are the ones the method declares in GET /v2/capabilities. purpose is optional: remittance by default.

The result usually arrives later: the operation stays pending / processing and the outcome reaches you by webhook (payout.confirmed / payout.failed) or by looking it up.

Parameter	In	Required	Description
`Idempotency-Key`	header	yes	A unique key per request, 8 to 128 characters. The same key returns the same operation.

Code	Meaning
`201`	The payout exists. `status` says what happened.
`400`	The request failed validation. `details` names each field. Codes: `amount_out_of_range`, `bank_unsupported`, `body_invalid`, `country_unsupported`, `currency_unsupported`, `field_invalid`, `field_required`, `idempotency_key_required`, `method_unavailable`.
`401`	The key is missing or invalid. Codes: `unauthorized`.
`403`	The key is valid but lacks the scope. Codes: `scope_missing`.
`409`	The same `Idempotency-Key` with a different body. Codes: `idempotency_key_reused`.
`503`	It could not be processed right now. Retry later with the same `Idempotency-Key`. Codes: `temporarily_unavailable`.

Look up a payout

GET/v2/payouts/{id}

Scopeoperaciones:leer

The current state. Requires the operaciones:leer scope.

Parameter	In	Required	Description
`id`	path	yes	The operation `id`.

Code	Meaning
`200`	The payout.
`401`	The key is missing or invalid. Codes: `unauthorized`.
`403`	The key is valid but lacks the scope. Codes: `scope_missing`.
`404`	There is no operation with that id in your company. Codes: `not_found`.

Cancel a pending payout

POST/v2/payouts/{id}/cancel

Scopepayouts:crear

Asks to cancel a payout that is still pending / processing. Only if the last known state allows it; if the payout was already executed or already finished, 409 not_cancellable.

Once cancelled, the payout ends failed with failure.code = cancelled, the amount returns to your available balance and you receive payout.failed. If the cancellation could not be confirmed right away, 503 temporarily_unavailable: the payout is still pending and you can try again.

Requires the payouts:crear scope.

Parameter	In	Required	Description
`id`	path	yes	The operation `id`.

Code	Meaning
`200`	The payout, cancelled.
`401`	The key is missing or invalid. Codes: `unauthorized`.
`403`	The key is valid but lacks the scope. Codes: `scope_missing`.
`404`	There is no operation with that id in your company. Codes: `not_found`.
`409`	The payout can no longer be cancelled. Codes: `not_cancellable`.
`503`	The cancellation could not be confirmed right now. The payout is still pending; retry. Codes: `temporarily_unavailable`.

Payout fields

Field	Type	Required	Description
`amount`	`string` `^[0-9]+(\.[0-9]+)?$`	yes	Decimal string with a point and the currency’s decimals.
`beneficiary`	`Beneficiario`	yes
`country`	`string` `^[A-Za-z]{2}$`	yes	ISO 3166-1 alpha-2.
`currency`	`string` `^[A-Za-z]{3}$`	yes	ISO 4217.
`metadata`	`object`	no	Anything you want to store, up to 4 KB. Comes back as is.
`method`	`CodigoDeMetodo`	yes
`purpose`	`Proposito`	no
`reference`	`string`	no	Your reference. Comes back as is in the operation.

`beneficiary`

Field	Type	Required
`account_number`	`string`	no
`bank_code`	`string`	no
`document`	`object`	no
`name`	`string`	no

purpose is remittance by default; payroll for payroll.

beneficiary.name is optional: if you send it, it is used; if not, the system fills it in from the document («Titular V-12345678») before sending the payout.

The system sets the concept. What the beneficiary sees on their bank statement is concept, for example «Pago TCP7K2M9Q»: «Pago», your company’s three-letter prefix and six characters taken from the operation id. You don’t send it or change it; it comes in the operation so you can show it to your user or find it on a statement. Your reference and metadata are stored and come back as is, but they are not sent to the bank.

Examples

curl -X POST https://api.tucapi.app/v2/payouts \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: order-4821" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "1500.50",
    "beneficiary": {
      "account_number": "04121234567",
      "bank_code": "0102",
      "document": {
        "number": "12345678",
        "type": "V"
      },
      "name": "Jane Doe"
    },
    "country": "VE",
    "currency": "VES",
    "metadata": {
      "order": "B-2"
    },
    "method": "mobile_payment",
    "purpose": "remittance",
    "reference": "remittance 456"
  }'

{
  "amount": "1500.50",
  "bank_reference": null,
  "country": "VE",
  "created_at": "2026-09-23T14:59:05Z",
  "created_by": "company",
  "currency": "VES",
  "failure": null,
  "id": "6f1c2a9e-3b4d-4c5e-8f70-1a2b3c4d5e6f",
  "metadata": {
    "order": "B-2"
  },
  "method": "mobile_payment",
  "pending_reason": "processing",
  "purpose": "remittance",
  "reference": "remittance 456",
  "status": "pending",
  "type": "payout",
  "updated_at": "2026-09-23T14:59:05Z"
}

curl -X POST https://api.tucapi.app/v2/payouts/$ID/cancel \
  -H "Authorization: Bearer $API_KEY"

{
  "amount": "1500.50",
  "bank_reference": null,
  "country": "VE",
  "created_at": "2026-09-23T14:59:05Z",
  "created_by": "company",
  "currency": "VES",
  "failure": {
    "code": "cancelled",
    "message": "La operación fue cancelada."
  },
  "id": "6f1c2a9e-3b4d-4c5e-8f70-1a2b3c4d5e6f",
  "metadata": {
    "order": "B-2"
  },
  "method": "mobile_payment",
  "pending_reason": null,
  "purpose": "remittance",
  "reference": "remittance 456",
  "status": "failed",
  "type": "payout",
  "updated_at": "2026-09-23T14:59:05Z"
}