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.

X-SECRET-KEYstring required

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.

Idempotency-Keystring

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 body

amount_in_centsinteger required

Monto en centavos que se debita del balance en currency

currency'GTQ' | 'USD'

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.

notestring

(Opcional) Nota o descripción del movimiento

is_instantboolean

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

should_perform_currency_conversionboolean

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.

idstring

ID del movimiento (tr_ / wi_ / sw_)

Estado canónico del movimiento

status_detailstring

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

amount_in_centsinteger

Monto en centavos debitado del balance

currencystring

Moneda del balance de origen

fee_in_centsinteger

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

net_amount_in_centsinteger

Monto neto que llega al destino después de comisiones

notestring nullable

Nota del movimiento

account_idstring

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_atstring date-time nullable

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

settled_atstring date-time nullable

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

bank_referencestring nullable

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_status'available' | 'pending' | 'unsupported'

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 nullable

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

balance_transaction_idstring nullable

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

created_atstring date-time

Fecha de creación

reversal_of_idstring

ID del transfer original; solo aparece en reversos por reembolso

refund_idstring

ID del reembolso que originó el reverso

Crear una transferencia

Headers

Request body

Response

Changes