Crear un payout
Dispersa fiat a una cuenta bancaria local. El monto local se convierte a USDT a la tasa de tu cuenta (la misma que devuelve GET /v1/rates); se debita usdt_amount más la comisión fija (cuando está configurada) y queda retenido hasta que la dispersión se complete. Si falla, se reembolsa el débito completo.
Paga desde cualquier saldo: por defecto el débito sale del asset de settlement predeterminado de tu cuenta (default_settlement_asset — USD es el saldo principal; cámbialo con PUT /v1/settlement). Envía settlement_asset (USD, USDT, USDC, BTC, GOLD, SILVER o PLATINUM) para pagar esta operación puntual desde otro saldo: el total se convierte a ese asset al precio efectivo de settlement del momento (ver el bloque settlement de GET /v1/rates) y el débito, la retención y — si falla — el reembolso viven en ese asset por el monto exacto. Si el precio de ejecución de BTC/GOLD/SILVER/PLATINUM no está disponible, el request devuelve 503 pricing_unavailable; los assets volátiles además tienen un límite por operación (422 settlement_limit_exceeded).
Requiere una llave de idempotencia (campo del body o header Idempotency-Key). Reintentar con la misma llave devuelve el payout original (200 con idempotency_hit: true).
Si el screening técnico del beneficiario está temporalmente no disponible y la cola técnica de screening está disponible, la respuesta es 202 con un recurso en status: pending, status_code: compliance_pending, compliance_pending: true y funds_debited: false, antes de cualquier débito o despacho al core. Después de que el screening devuelve process, el mismo recurso puede seguir en pending con compliance_dispatch_pending, compliance_dispatching o core_unreachable mientras funds_debited es true; conserva la misma clave de idempotencia y espera la conciliación.
Autorizaciones
JWT de sesión (de register/login) o llave de API (pk_...).
X-API-Key: <token> se acepta como header alternativo.
Encabezados
Alternativa al campo idempotency_key del body.
Cuerpo
País de destino ISO 3166-1 alpha-2 (ej. CL, PE, MX).
Moneda local (ej. CLP, PEN, MXN).
Monto en moneda local como string decimal positivo.
"50000.00"
Método de payout de GET /v1/payouts/methods (ej. bank_transfer).
Datos de la cuenta de destino. Las claves requeridas dependen del
país y del método; ver GET /v1/payouts/methods y
GET /v1/payouts/banks. Ejemplos: RUT + banco en Chile, CLABE en
México, CCI en Perú. PIX Brasil: pix_key + pix_key_type (cpf,
cnpj, phone, email, evp), o cuenta bancaria sin llave con
bank_code (ISPB) + branch_code + account_number + tax_id.
Ecuador (corredor de remesas): document_value (cédula) más los
datos del ordenante planos en el mismo objeto (sender_name,
sender_document_value, ...); los nombres estructurados opcionales
(given_name, first_surname, ... y sus pares sender_*)
mandan sobre la separación automática de name.
Argentina: tax_id (CUIT/CUIL de 11 dígitos) + account_number
(CBU o CVU de 22 dígitos, o un alias bancario de 6–20 caracteres con al menos una letra; USD solo CBU) — sin bank_code.
Estados Unidos (USD): identidad y dirección postal completas del
beneficiario en cada transferencia — name, email,
account_number, country_code, address, city,
postal_code, bank_name, bank_country y bank_code
(routing ABA para ach/wire, BIC SWIFT para swift);
account_type (CHECKING/SAVING) es requerido para ach.
El beneficiario puede vivir en CUALQUIER país (country_code
es libre — ej. un ACH a un banco de EE. UU. para alguien que
vive en Alemania); state es requerido solo cuando
country_code es US. El banco receptor debe estar en EE.
UU. para ach/wire (bank_country: "US" — los rails
domésticos no pagan a bancos fuera de EE. UU.) junto con su
bloque de dirección completo (bank_address, bank_city,
bank_postal_code y bank_state para bancos de EE. UU.);
para swift el bloque de dirección del banco es opcional (el
rail lo deriva del BIC) y bank_country puede ser cualquier
país. Las jurisdicciones del Anexo B (CU/IR/KP/SY) siguen
bloqueadas para el país del beneficiario Y del banco (422 prohibited_country). Toda transferencia USD por rail
bancario exige además un documento de respaldo
(invoice/recibo) subido antes con POST /v1/payouts/documents — ver la guía de payouts.
Show child attributes
Show child attributes
Usa el beneficiario guardado más reciente del contacto para este país (y método, si lo envías) en vez de tipear beneficiary de nuevo. Un beneficiary explícito siempre gana; 422 no_saved_destination si el contacto no tiene.
El beneficiario se guarda como contacto automáticamente; envía false para no guardarlo.
Narrativa de pago opcional. Para SEPA, el adapter la pliega al charset corporativo del proveedor, rechaza caracteres no admitidos con 400 invalid_payload y trunca el valor wire a 140 runas.
Saldo virtual a debitar para esta operación. La ejecución en fiat devuelve hoy 503 pricing_unavailable. Omítelo para usar el asset de settlement predeterminado de tu cuenta (USD es el saldo principal).
USD, USDT, USDC, BTC, GOLD, SILVER, PLATINUM, BOB, MXN, ARS IBAN virtual funding_usdt activo opcional que financia un payout SEPA de cliente. Omítelo solo cuando la cuenta tenga exactamente una fuente EUR activa; envíalo si hay varias. La identidad ordenante se lee del registrant del vIBAN.
Instrumento banking BO/BOB activo opcional; fuera de BO/BOB se rechaza y varias fuentes activas requieren este UUID.
Optional rail-specific options. For a deliberate retry after a recent bank rejection, set destination_retry_ack to the most recent prior case ID.
Show child attributes
Show child attributes
Respuesta
Respuesta idempotente de un payout existente.
La tasa de tu cuenta al momento de la ejecución (unidades locales por 1 USDT).
Origen de la tasa ejecutada. lot, blend o spot; se omite en filas históricas sin atribución.
lot, blend, spot Saldo virtual desde el que realmente se debitó la operación.
USD, USDT, USDC, BTC, GOLD, SILVER, PLATINUM Monto exacto debitado del saldo del asset de settlement (en unidades de ese asset). Es igual a total_debit cuando el asset es USDT. Si el payout falla se reembolsa este monto exacto — nunca se re-cotiza.
Precio USD efectivo por unidad del asset de settlement usado para convertir el total en USDT ("1" para USDT/USDC).
pending con compliance_pending: true significa que el screening técnico del beneficiario espera antes de cualquier débito o despacho al core. Después del screening, pending también puede usar compliance_dispatch_pending, compliance_dispatching o core_unreachable mientras el débito permanece retenido.
pending, processing, completed, failed Detalle del estado normalizado. compliance_pending es pre-débito; compliance_dispatch_pending, compliance_dispatching y core_unreachable son códigos durables de transición después del screening.
Falso antes de debitar un payout pendiente de screening. Verdadero después de que el screening pasa y existe el débito/hold, incluso durante las transiciones de despacho.
True cuando el screening o un control duro terminó el payout antes de cualquier débito. Es distinto de un payout fallido cuyo débito se reembolsó después.
Verdadero solo mientras el screening técnico espera antes de cualquier débito o despacho al core; pasa a falso cuando se acepta el resultado process.
Referencia de la transaccion en el banco/rail (ej. el id de transferencia del banco, con el que el beneficiario cruza el pago con su banco). En US ACH/wire/SWIFT es la referencia CBF que vuelve al crear; en el resto de corredores queda vacia hasta que el rail la reporta.
Identificador UETR/SWIFT gpi reportado por el banco después de la ejecución; vacío hasta estar disponible.
Identificador doméstico wire/ACH reportado por el banco después de la ejecución; vacío hasta estar disponible.
Presente (true) cuando la respuesta es una repetición idempotente.
Presente solo cuando existe un comprobante, normalmente después del débito y del estado final. Se omite mientras el payout espera screening técnico antes del débito.