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:
P2P transfers are asynchronous. A successful response can be pending (automatic evaluation) or in_review (human review). Funds remain reserved until approval. Rejection returns them to the sender’s balance and changes the status to cancelled. Poll GET /api/transfers/{id} or subscribe to transfer webhooks. Cancellation is only available while unclaimed; a successful POST does not mean the recipient has received the money.
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.
Authentication
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.
La llave también fija el ambiente: una sk_test_ solo lista y resuelve objetos de prueba (live_mode: false) y una sk_live_ solo objetos reales. Un ID del otro ambiente responde 404 (401 en /customers).
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
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
Monto en centavos que se debita del balance en currency
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
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.
(Opcional) Nota o descripción del movimiento. En retiros bancarios, el beneficiario la ve como concepto en su página de seguimiento.
Solo destinos bank_account — correo del beneficiario. Le enviamos la fecha estimada de llegada y el link de seguimiento, y le avisamos cuando el retiro sale hacia su banco o no se completa.
Solo destinos bank_account — retiro instantáneo (sujeto a elegibilidad y comisión)
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.
ID del movimiento (tr_ / wi_ / sw_)
Estado canónico del movimiento
Estado crudo del registro subyacente (p. ej. approved, rejected, review_requested)
Comisión en centavos (retiros instantáneos / internacionales; 0 para p2p)
Monto neto que llega al destino después de comisiones
Correo del beneficiario al que le avisamos el estado del retiro. Solo aplica a movimientos wi_.
Página pública de seguimiento para el beneficiario (monto que recibe, cuenta enmascarada, estado y fecha estimada de llegada). Solo aplica a movimientos wi_; compártela con quien recibe el dinero.
Cuenta cuyo balance movió este envío. Siempre presente, para que una lista que abarca varias cuentas de una organización siga siendo atribuible.
Momento en que Recurrente envió el retiro al banco; solo aplica a retiros bancarios (wi_).
Momento de liquidación bancaria confirmada. Solo está presente para retiros bancarios confirmados o completados (wi_).
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.
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.
Lo que le pedimos al banco que imprima en el estado de cuenta del beneficiario. Solo aplica a movimientos wi_.
Fila del ledger que registró este movimiento (GET /api/balance_transactions/{id}). Vacío mientras el dinero no haya salido del balance.
Destino del movimiento. Los campos presentes dependen de type.
Fecha de creación
(Solo registros tr_) Cuenta emisora — campo legado
(Solo registros tr_) Destinatario — campo legado
ID del transfer original; solo aparece en reversos por reembolso
ID del reembolso que originó el reverso