RErecurrente
transfers

Crear una transferencia

Changed on

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:

destinationA dónde vaRegistro creado
"ba_..."Retiro a tu cuenta bancariawi_ (asíncrono)
"ac_..."Transferencia instantánea a esa cuenta de Recurrentetr_
"@handle"Transferencia a la cuenta con ese handletr_
"co_..."Transferencia al teléfono de ese contacto guardadotr_
"+50255667788"Envío a un teléfono; queda unclaimed hasta que lo reclamen con KYCtr_

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.

post/transfers

Request

Headers

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. En retiros bancarios, el beneficiario la ve como concepto en su página de seguimiento.

recipient_emailstring email

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.

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_)

status'pending' | 'in_review' | 'processing' | 'sent' | 'unclaimed' | 'completed' | 'failed' | 'cancelled'

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

recipient_emailstring nullable

Correo del beneficiario al que le avisamos el estado del retiro. Solo aplica a movimientos wi_.

tracking_urlstring nullable

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.

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

Changes

  • 33bad9197d59Revision changes
    • breaking

      added to the response property oneOf list for the response status

    • breaking

      added to the response property oneOf list for the response status

    • breaking

      added to the response property oneOf list for the response status

    • breaking

      the / response's property type changed from object to array for status

    • breaking

      the / response's property type changed from object to array for status

    • breaking

      the / response's property type changed from object to array for status

  • 3d76463f9fd8Revision changes
    • warning

      deleted the header request parameter X-SECRET-KEY

    • info

      the endpoint scheme security secretKey was added to the API