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 (USDT salvo que lo cambies con PUT /v1/settlement). Envía settlement_asset (USDT, USDC, BTC o GOLD) para pagar esta operación puntual desde otro saldo: el total en USDT 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 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).
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; 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.
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.
Saldo virtual a debitar para esta operación. Omítelo para usar el asset de settlement predeterminado de tu cuenta (USDT salvo que lo cambies con PUT /v1/settlement).
USDT, USDC, BTC, GOLD Respuesta
Respuesta idempotente de un payout existente.
La tasa de tu cuenta al momento de la ejecución (unidades locales por 1 USDT).
Saldo virtual desde el que realmente se debitó la operación.
USDT, USDC, BTC, GOLD 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, processing, completed, failed 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.
Presente (true) cuando la respuesta es una repetición idempotente.