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.1. Crea una cotización
Crea el precio conPOST /v3/quotes. Envía estas cabeceras:
data.id como QUOTE_ID. Presenta los importes y comisiones devueltos en lugar de reconstruirlos a partir de la tasa.
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:
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.
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.
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.
Una cuenta bancaria emitida es distinta: proporciona datos reutilizables para depósitos posteriores. Consulta Emitir una cuenta bancaria cuando esa sea la experiencia prevista.
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.