sepa. El catálogo es provider-agnostic: expone país, EUR y sepa, mientras
la cuenta usa el pricing e idempotencia normal de payouts.
Corredor de enrutamiento
V1 registra un único corredor:country=EU, currency=EUR y method=sepa.
EU es el código de catálogo para Europa, no el país real del beneficiario.
El país real sale de las dos primeras letras del IBAN normalizado; el IBAN
debe pertenecer al conjunto admitido por SEPA Instant.
GB queda fuera de SEPA Instant V1: un IBAN británico falla rápido con HTTP
400 antes del despacho porque sepaInstReachable=false. SEPA Credit Transfer
para GB es un alcance futuro separado. GET /v1/payouts/methods devuelve la
única fila EU/EUR/sepa cuando el corredor está habilitado.
Contrato del beneficiario
El objetobeneficiary debe incluir:
Usa una sola clave de idempotencia para toda la operación.
description es
opcional en la API, pero si se envía se normaliza para el wire SEPA: se pliegan
los diacríticos, se aplica el mapa europeo explícito de abajo, el resultado
debe caber en el charset corporativo del proveedor y queda limitado a 140
puntos de código Unicode. Si todavía contiene un carácter fuera de ese
charset, la creación falla con 400 invalid_payload. Si se omite, el adapter
genera una descripción SEPA interna válida.
Los nombres usan el mismo pliegue determinista antes de validar el charset:
Una persona debe resolver a nombre y apellido. Los monónimos no se pueden
pagar como
individual en V1; envía given_name y first_surname, o un
name de varias palabras.
Crear un payout
processing; ante un retry del
cliente usa la misma clave de idempotencia.
Fuente EUR e identidad ordenante
Para una cuenta cliente, cada payoutsepa debe resolver un IBAN virtual
asignado y activo con propósito funding_usdt. Este es el propósito de fondeo
para los payouts de clientes; los retiros de EUR Banking usan el propósito
separado banking_eur.
Envía source_virtual_iban_id en el nivel superior cuando necesites elegir un
IBAN virtual funding_usdt activo específico:
- Con exactamente un IBAN virtual
funding_usdtactivo, omitir el parámetro selecciona esa cuenta de forma determinista. - Sin una fuente activa, la API devuelve
422 funding_account_required. - Con varias fuentes activas, la API devuelve
422 ambiguous_source_vibanhasta que envíes el UUID elegido. - Un UUID explícito que no pertenece a la cuenta o no está activo devuelve
404 not_foundo422 funding_account_required.
BANK_EUR se usa en operaciones EUR Banking,
no en payouts de clientes.
Los holds de payout creados antes de esta puerta de origen quedan
grandfathered: continúan por su flujo existente de dispatch y reconciliación y
no se rechazan retroactivamente.
Casos límite de idempotencia y selección del origen
El vIBAN de origen es parte de la intención del payout. Si el conjunto de vIBAN activos cambia entre dos requests secuenciales, reintentar con la misma clave de idempotencia devuelve el payout original. Si una request concurrente observa un conjunto distinto, devuelve409 idempotency_conflict; ambos
resultados son seguros y no crean un segundo débito. No uses una clave nueva
para adivinar el resultado.
La misma clave no puede representar simultáneamente el origen default y un
source_virtual_iban_id explícito: ese replay devuelve
409 idempotency_conflict. La comparación estricta evita cambiar en silencio
la cuenta ordenante.
Estados y returns
Suscríbete a
payout_status_changed. SEPA no agrega un webhook nuevo: el
callback se verifica y entra al mismo pipeline de estados.
Errores
¿El BIC es obligatorio?
¿El BIC es obligatorio?
No. El IBAN es obligatorio; el BIC es opcional.
¿Puedo enviar USD por este método?
¿Puedo enviar USD por este método?
No.
sepa es exclusivamente EUR y se rechaza antes del despacho.¿Un return crea un webhook nuevo?
¿Un return crea un webhook nuevo?
No.
payout_status_changed lleva status_code: reversed y el resultado
normal del reembolso.