Pagos (payouts)

Un pago le manda dinero a una persona desde su saldo. Métodos: mobile_payment (pago móvil, por teléfono) y bank_transfer (transferencia a cuenta). El pago sale en el momento; el desenlace llega por webhook.

Saldo

Un pago reserva el monto de su saldo disponible al crearse (available → reserved), lo captura al confirmarse y lo libera si falla. El saldo es contable, no un freno: el pago sale aunque available quede en negativo. GET /v2/balances le muestra available y reserved por moneda.

Cancelar

POST /v2/payouts/{id}/cancel cancela un pago que todavía está pendiente.

• Cancelado → status: failed, failure.code: cancelled, saldo liberado.
• Ya no se puede → 409 not_cancellable (mire el estado: probablemente ya se confirmó).
• El proveedor no contestó claro → 503 temporarily_unavailable: el pago sigue pendiente, nada cambió, y no lo reintente a ciegas: consulte.

Rutas

Crear un pago

POST/v2/payouts

Alcancepayouts:crear

Crea un pago y lo envía. Es UN paso: el monto se reserva de su saldo disponible al crearlo y se descuenta al confirmarse; si el pago falla, vuelve a estar disponible.

Requiere el alcance payouts:crear.

Los campos de beneficiary son los que el método declara en GET /v2/capabilities. purpose es opcional: remittance por omisión.

El resultado suele llegar después: la operación queda pending / processing y el desenlace le llega por webhook (payout.confirmed / payout.failed) o consultándola.

Parámetro	En	Obligatorio	Descripción
Idempotency-Key	header	sí	Una clave única por pedido, de 8 a 128 caracteres. La misma clave devuelve la misma operación.

Código	Significa
201	El pago existe. status dice qué pasó.
400	El pedido no pasó la validación. details nombra cada campo. Códigos: amount_out_of_range, bank_unsupported, body_invalid, country_unsupported, currency_unsupported, field_invalid, field_required, idempotency_key_required, method_unavailable.
401	La llave falta o no es válida. Códigos: unauthorized.
403	La llave es válida pero no tiene el alcance. Códigos: scope_missing.
409	La misma Idempotency-Key con otro cuerpo. Códigos: idempotency_key_reused.
503	No se pudo procesar ahora. Reintente más tarde con la misma Idempotency-Key. Códigos: temporarily_unavailable.

Consultar un pago

GET/v2/payouts/{id}

Alcanceoperaciones:leer

El estado actual. Requiere el alcance operaciones:leer.

Parámetro	En	Obligatorio	Descripción
id	path	sí	El id de la operación.

Código	Significa
200	El pago.
401	La llave falta o no es válida. Códigos: unauthorized.
403	La llave es válida pero no tiene el alcance. Códigos: scope_missing.
404	No hay una operación con ese identificador en su empresa. Códigos: not_found.

Cancelar un pago pendiente

POST/v2/payouts/{id}/cancel

Alcancepayouts:crear

Pide cancelar un pago que todavía está pending / processing. Sólo si el último estado conocido lo permite; si el pago ya se ejecutó o ya terminó, 409 not_cancellable.

Cancelado, el pago queda failed con failure.code = cancelled, el monto vuelve a su saldo disponible y le llega payout.failed. Si no se pudo confirmar la cancelación en el momento, 503 temporarily_unavailable: el pago sigue pendiente y puede volver a intentar.

Requiere el alcance payouts:crear.

Parámetro	En	Obligatorio	Descripción
id	path	sí	El id de la operación.

Código	Significa
200	El pago, cancelado.
401	La llave falta o no es válida. Códigos: unauthorized.
403	La llave es válida pero no tiene el alcance. Códigos: scope_missing.
404	No hay una operación con ese identificador en su empresa. Códigos: not_found.
409	El pago ya no se puede cancelar. Códigos: not_cancellable.
503	La cancelación no se pudo confirmar ahora. El pago sigue pendiente; reintente. Códigos: temporarily_unavailable.

Los campos de un pago

Campo	Tipo	Obligatorio	Descripción
amount	string ^[0-9]+(\.[0-9]+)?$	sí	Cadena decimal con punto y los decimales de la moneda.
beneficiary	Beneficiario	sí
country	string ^[A-Za-z]{2}$	sí	ISO 3166-1 alfa-2.
currency	string ^[A-Za-z]{3}$	sí	ISO 4217.
metadata	object	no	Lo que usted quiera guardar, hasta 4 KB. Vuelve tal cual.
method	CodigoDeMetodo	sí
purpose	Proposito	no
reference	string	no	Su referencia. Vuelve tal cual en la operación.

beneficiary

Campo	Tipo	Obligatorio	Descripción
account_number	string	no
bank_code	string	no
document	object	no
name	string	no

purpose es remittance por omisión; payroll para nómina.

beneficiary.name es opcional: si usted lo manda, se usa; si no, el sistema lo completa con el documento («Titular V-12345678») antes de mandar el pago.

El concepto lo pone el sistema. Lo que el beneficiario ve en su movimiento bancario es concept, por ejemplo «Pago TCP7K2M9Q»: «Pago», el prefijo de tres letras de su empresa y seis caracteres tomados del id de la operación. Usted no lo manda ni lo cambia; viene en la operación para que pueda mostrárselo a su usuario o buscarlo en un extracto. Su reference y su metadata se guardan y vuelven tal cual, pero no viajan al banco.

Ejemplos

POST /v2/payouts

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

Respuesta 201

{
  "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": {
    "orden": "A-1"
  },
  "method": "mobile_payment",
  "pending_reason": "processing",
  "purpose": "remittance",
  "reference": "factura 123",
  "status": "pending",
  "type": "payout",
  "updated_at": "2026-09-23T14:59:05Z"
}

POST /v2/payouts/{id}/cancel

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

Respuesta 200

{
  "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": {
    "orden": "A-1"
  },
  "method": "mobile_payment",
  "pending_reason": null,
  "purpose": "remittance",
  "reference": "factura 123",
  "status": "failed",
  "type": "payout",
  "updated_at": "2026-09-23T14:59:05Z"
}