Referencia APITransfers

Crear una transferencia

Mueve dinero desde tu balance al `destination` que indiques. En la mayoría de los casos basta pasar **el identificador como string** — el formato indica a dónde va el dinero: | `destination` | A dónde va | Registro creado | |---|---|---| | `"ba_..."` | Retiro a tu cuenta bancaria | `wi_` (asíncrono) | | `"ac_..."` | Transferencia instantánea a esa cuenta de Recurrente | `tr_` | | `"@handle"` | Transferencia a la cuenta con ese handle | `tr_` | | `"co_..."` | Transferencia al teléfono de ese contacto guardado | `tr_` | | `"+50255667788"` | Envío a un teléfono; queda `unclaimed` hasta que lo reclamen con KYC | `tr_` | Para stablecoin (requiere verificación de stablecoin) o para ser explícito, usa la forma de objeto: `destination: {type: "crypto_address", address: "0x…", chain: "base", currency: "USDC"}` crea un envío `sw_`. Requiere una llave con movimiento de dinero habilitado y la cuenta verificada. Usa `X-ACCOUNT-ID` para operar sobre una cuenta conectada (hija) verificada — admite destinos `bank_account`, y destinos `account` dentro de su misma plataforma (la cuenta madre o cuentas hermanas), para comisiones y liquidaciones. En Sandbox, `POST /transfers` está bloqueado para todos los destinos porque el balance simulado no es transferible ni retirable.

Authentication

X-SECRET-KEYstring
Tu clave secreta de API. Una llave de cuenta (`sk_live_...`, `sk_test_...`) opera sobre su propia cuenta y, con `X-ACCOUNT-ID`, sobre sus cuentas conectadas. Una llave de organización (`sk_org_live_...`, `sk_org_test_...`) alcanza todas las cuentas de una organización y solo sirve para leer: saldos, movimientos y reportes. Para operar sobre una cuenta debe nombrarla con `X-ACCOUNT-ID`; omitirlo en una lectura devuelve todas las cuentas de la organización. Cualquier otro endpoint responde `403` con `code: organization_key_unsupported`.

Headers

Idempotency-KeystringOptional

Clave de idempotencia para reintentos seguros de operaciones críticas, especialmente las que mueven dinero o cambian estado operativo. Reintentar con la misma clave y el mismo cuerpo devuelve la respuesta original (header Idempotency-Replayed: true); reusarla con parámetros distintos devuelve 409.

Request

This endpoint expects an object.
amount_in_centsintegerRequired

Monto en centavos que se debita del balance en currency

destinationstring or objectRequired

A dónde va el dinero — el identificador como string (ba_/ac_/co_ id, @handle o teléfono), o el objeto tipado para stablecoin y casos avanzados

currencyenumOptional

Moneda del balance de origen. Para destinos bank_account es opcional (por defecto, la moneda de la cuenta bancaria); requerida para los demás destinos.

Allowed values:
notestringOptional

(Opcional) Nota o descripción del movimiento

is_instantbooleanOptional

Solo destinos bank_account — retiro instantáneo (sujeto a elegibilidad y comisión)

should_perform_currency_conversionbooleanOptional

Solo destinos bank_account — convierte el balance a la moneda de la cuenta bancaria destino

Response

Movimiento creado. Los retiros (wi_) y envíos cripto (sw_) son asíncronos — la respuesta trae el estado inicial; consulta el estado o suscríbete a los webhooks.

idstringOptional

ID del movimiento (tr_ / wi_ / sw_)

statusenumOptional

Estado canónico del movimiento

status_detailstringOptional

Estado crudo del registro subyacente (p. ej. approved, rejected, review_requested)

amount_in_centsintegerOptional
Monto en centavos debitado del balance
currencystringOptional
Moneda del balance de origen
fee_in_centsintegerOptional

Comisión en centavos (retiros instantáneos / internacionales; 0 para p2p)

net_amount_in_centsintegerOptional

Monto neto que llega al destino después de comisiones

notestring or nullOptional
Nota del movimiento
account_idstringOptional

Cuenta cuyo balance movió este envío. Siempre presente, para que una lista que abarca varias cuentas de una organización siga siendo atribuible.

sent_atdatetime or nullOptional

Momento en que Recurrente envió el retiro al banco; solo aplica a retiros bancarios (wi_).

settled_atdatetime or nullOptional

Momento de liquidación bancaria confirmada. Solo está presente para retiros bancarios confirmados o completados (wi_).

bank_referencestring or nullOptional

Referencia que devolvió el riel de envío, cuando ese riel devuelve una. Solo aplica a movimientos wi_; no identifica ni enumera transacciones que conformen el retiro.

bank_reference_statusenum or nullOptional

Qué esperar de bank_reference: available si ya existe, pending si el retiro aún no sale y podría traerla, y unsupported si ya salió por un riel que nunca devuelve una. Con unsupported, concilia el depósito por statement_descriptor.

statement_descriptorstring or nullOptional

Lo que le pedimos al banco que imprima en el estado de cuenta del beneficiario. Solo aplica a movimientos wi_.

balance_transaction_idstring or nullOptional

Fila del ledger que registró este movimiento (GET /api/balance_transactions/{id}). Vacío mientras el dinero no haya salido del balance.

destinationobjectOptional

Destino del movimiento. Los campos presentes dependen de type.

created_atdatetimeOptional

Fecha de creación

senderobjectOptional

(Solo registros tr_) Cuenta emisora — campo legado

recipientobjectOptional

(Solo registros tr_) Destinatario — campo legado

reversal_of_idstringOptional

ID del transfer original; solo aparece en reversos por reembolso

refund_idstringOptional

ID del reembolso que originó el reverso

Errors

400
Bad Request Error
403
Forbidden Error
422
Unprocessable Entity Error