Antes de empezar
Necesitas una capacidad de cobro lista y una cartera de destino emitida lista para el mismo cliente. Completa cualquier trabajo abierto mediante Capacidades y tareas y luego vuelve a obtener ambos recursos. SWIFT agrupado no admite cobros. Para recibir depósitos SWIFT, emite una cuenta SWIFT nominativa. Consulta Emitir una cuenta bancaria.1. Crea una cotización
Crea el precio conPOST /v3/quotes. Envía estas cabeceras:
Request headers
Request body
data.id como QUOTE_ID. Presenta los importes y comisiones devueltos en lugar de reconstruirlos a partir de la tasa.
Importes mínimos
Las cotizaciones de cobro bancario pueden exigir un importe mínimo, por ejemplo 20.00 USD para Wire agrupado.POST /v3/quotes devuelve 422 amount_not_deliverable cuando el importe está por debajo del mínimo o es demasiado pequeño para cubrir las comisiones de transferencia.
2. Ejecuta la cotización
Ejecuta la cotización actual antes de su expiración conPOST /v3/transfers. Utiliza una nueva clave para esta transferencia prevista:
Request headers
Request body
data.id de la transferencia como TRANSFER_ID y conserva su estado actual.
Añade una URL de retorno para tarjeta y Apple Pay
Para una cotización de tarjeta o Apple Pay, puedes incluir unredirectUrl opcional en la misma solicitud. Cuando el cliente finaliza el checkout alojado, la página de checkout abre esta URL para devolver al cliente a tu aplicación.
Request body with redirectUrl
redirectUrl debe ser una URL HTTPS absoluta de como máximo 2048 caracteres y no debe contener credenciales incrustadas. Enviar redirectUrl para una cotización que no admite navegación de retorno falla la validación en lugar de ignorarse.
La llegada a redirectUrl es solo navegación del navegador. No confirma que el pago ni la transferencia se hayan completado. Determina la finalización a partir del estado de la transferencia en el paso 4 y de los eventos de webhook.
Preselecciona el método de checkout para una cotización de tarjeta
Para una cotización de tarjeta, puedes incluir uncheckoutMethod opcional en la misma solicitud para elegir con qué opción de pago se abre el checkout alojado. Los valores actuales son card, apple_pay, google_pay, cash_app, sepa y blik. La lista es abierta y puede crecer, así que tolera los valores que no reconozcas en las lecturas de la transferencia. El checkout se abre con el método solicitado cuando está disponible para el cliente y su dispositivo, y el cliente aún puede elegir cualquier otro método que ofrezca el checkout. Omítelo para mantener la preselección predeterminada.
Request body with checkoutMethod
checkoutMethod es una preferencia, no una garantía. La disponibilidad depende del cliente, de su dispositivo y del checkout, por lo que solicitar un método no lo hace disponible. Aquí sepa y blik son opciones de pago dentro del checkout de tarjeta, no capacidades, rails ni cuentas de Swipelux. La preselección no cambia la capacidad, los importes ni las comisiones de la cotización, y el checkout confirma las comisiones finales. Las lecturas de la transferencia devuelven el valor solicitado; no confirman qué método usó el cliente. Enviar checkoutMethod para una cotización que no es de tarjeta falla la validación en lugar de ignorarse, y una repetición con la misma clave de idempotencia debe enviar el mismo checkoutMethod.
3. Recupera las instrucciones de financiación
LeeGET /v3/transfers/{transferId}/instructions. Renderiza la variante data.instructions devuelta sin asumir su tipo.
Estos datos son específicos de la transferencia. Nunca reutilices las coordenadas bancarias, el código, la URL alojada, el importe, la referencia ni la expiración de una transferencia para otro cobro.
Para instrucciones bancarias, cuando reference.required sea true, muestra el reference.value exacto junto a las coordenadas bancarias y hazlo copiable. Muestra el importe y la moneda devueltos del mismo conjunto de instrucciones.
Las instrucciones bancarias también pueden incluir los campos opcionales bankName, bankAddress, accountHolderName y accountHolderAddress. Muestra cada campo devuelto junto a las demás coordenadas bancarias. Los bancos emisores suelen exigir la dirección del banco receptor para swift y otras transferencias internacionales, así que muestra bankAddress siempre que se devuelva.
Bank instructions
4. Monitorea la liquidación
LeeGET /v3/transfers/{transferId} tras la ejecución y después de cada evento. Impulsa el estado visible al cliente a partir del último data.state.
Utiliza data.stateDetail y data.openTaskIds cuando la transferencia necesite otra acción. No la marques como completada a partir de un calendario esperado.
A continuación, añade Webhooks y mantén el estado de la transferencia sincronizado hasta que alcance un resultado que tu producto gestione.