Antes de empezar
Necesitas un ID de cliente, una capacidad bancaria lista para el método y moneda previstos y una cartera emitida lista propiedad del mismo cliente. ConallowPending, puedes guardar la solicitud mientras el banco seleccionado todavía revisa al cliente. Completa el trabajo abierto mediante Capacidades y tareas.
1. Crea o selecciona la cartera de liquidación
Crea una cartera emitida mediante Cuentas y carteras y vuelve a leerla. Continúa solo cuando su estado actual permita la liquidación. Guarda eldata.id derivado de la respuesta como SETTLEMENT_WALLET_ID. No utilices una cartera externa para settlement.accountId.
2. Crea la cuenta bancaria emitida
UtilizaPOST /v3/customers/{customerId}/accounts con estas cabeceras:
Request headers
Request body
data.id devuelto como BANK_ACCOUNT_ID. Conserva también data.status, data.openTaskIds, data.details y la relación de liquidación.
Campos opcionales de la solicitud:
Elige el banco
Envíainstitution cuando el cliente necesite datos bancarios de un banco específico. Swipelux reserva una cuenta emitida por cliente, método, moneda e institución. Una solicitud sin institution devuelve 409 conflict si el cliente ya tiene una cuenta emitida para ese método y moneda en cualquier banco. Una solicitud con institution devuelve 409 conflict solo si ya existe una cuenta para ese banco.
Las lecturas de la cuenta devuelven el banco seleccionado como institution con id, name y bic. bic puede ser null.
La idempotencia se aplica al banco seleccionado. Repetir la misma solicitud devuelve la cuenta original. Cambiar institution con la misma Idempotency-Key devuelve 409 idempotency_conflict.
Guarda la solicitud antes de la aprobación del banco
De forma predeterminada, Swipelux acepta una solicitud de cuenta bancaria emitida solo cuando la capacidad bancaria está lista. Para recopilar antes la configuración de la cuenta del cliente, envíaallowPending: true junto con institution:
Request body with allowPending
status: "in_review" con statusReason.code establecido en waiting_for_approval. La respuesta también incluye applicationId y los openTaskIds de la aplicación. Completa esas tareas mediante Capacidades y tareas.
La solicitud guardada conserva su ID de cuenta, su cartera de liquidación y su plaza de cuenta. Cuando la aplicación y la capacidad estén listas, Swipelux aprovisiona los datos bancarios con el mismo BANK_ACCOUNT_ID. Sigue leyendo ese ID. No crees otra solicitud.
Mientras la solicitud guardada espera, ocupa la plaza de cuenta. Otra solicitud allowPending para la misma plaza con un Idempotency-Key diferente devuelve 409 conflict. El campo holder.accountId del problema indica la cuenta en espera. Lee esa cuenta en lugar de reintentar.
Si la aplicación se rechaza, se cancela o se archiva antes, la cuenta pasa a rejected. Ya no ocupa la plaza de cuenta.
Elige la moneda de liquidación
De forma predeterminada, los depósitos se liquidan en la moneda de la cartera de liquidación. Establecesettlement.currency en USDC o USDT para elegir el activo entregado independientemente de la moneda de la cartera:
Request body with settlement currency
USDT requiere una cuenta USD y una cartera de liquidación en una red que admita la entrega de USDT. De lo contrario, la solicitud devuelve 400 invalid_settlement_target. Las lecturas de la cuenta devuelven la opción guardada, también mientras la cuenta se está aprovisionando.
El ID de la cuenta bancaria y el ID de la cartera tienen roles distintos. Lee el aprovisionamiento y los datos bancarios mediante el ID de la cuenta bancaria. Utiliza el ID de la cartera de liquidación para identificar dónde se acreditan los depósitos.
3. Monitorea el aprovisionamiento
LeeGET /v3/customers/{customerId}/accounts/{accountId} tras la creación y después de cada webhook relevante.
Mantén la interfaz del cliente en pendiente mientras details esté ausente. Si openTaskIds no está vacío, completa las últimas tareas y vuelve a obtener la cuenta. No infieras la disponibilidad a partir del tiempo transcurrido.
Si la cuenta se guardó con allowPending: true, permanece en in_review con statusReason.code establecido en waiting_for_approval hasta que el banco aprueba la aplicación.
Si el último statusReason.code es awaiting_assignment, crea el primer cobro para el mismo cliente, capacidad y cartera de liquidación mediante Recibir fondos y luego vuelve a leer la cuenta bancaria. Sigue esta ruta solo cuando la cuenta actual lo solicite.
4. Presenta los datos bancarios de forma segura
Muestra únicamente los datos completos devueltos por la última lectura de la cuenta. Cuandodetails.referenceRequired sea true, muestra el details.reference exacto y hazlo copiable. Cuando sea false, no inventes una referencia.
Para las cuentas swift emitidas, muestra details.bankName, details.swiftCode (el BIC del banco receptor), details.accountNumber, details.accountHolderName y details.accountHolderAddress cuando se devuelvan. Los remitentes deben copiar la dirección del beneficiario exactamente en la transferencia internacional. Muestra también details.bankAddress y cualquier campo de banco intermediario que devuelva la cuenta.
Estos datos bancarios son reutilizables. No los reemplaces con coordenadas de financiación de un cobro cotizado, que pertenecen únicamente a esa transferencia.
A continuación, añade Webhooks para que las actualizaciones de aprovisionamiento lleguen a tu aplicación sin mantener al cliente en una pantalla de sondeo.