Número de ruta (BANK)
Cómo validar el número de ruta ABA de un retiro BANK y obtener el nombre y el logo del banco con GET /withdraw/bank-lookup.
Desde el 21 de octubre de 2026 el método BANK (transferencia en USD) es solo para bancos de Estados Unidos: el campo Nro de Ruta o ACH debe ser un número de ruta ABA de 9 dígitos con dígito de control válido. Un código SWIFT/BIC ya no se acepta ahí: para un banco fuera de EE. UU. usa el método BANK_INTL (ver Ejemplos por método).
Mientras tu cliente teclea la ruta, puedes consultar a qué banco pertenece y mostrar su nombre y su logo, como hace el asistente de retiro de QvaPay.
GET /withdraw/bank-lookup?routing=026009593
Requiere autenticación (Bearer o credenciales de App). Devuelve el banco titular del número de ruta y, cuando varias fintech operan sobre ese mismo número (p. ej. Mercury sobre Choice Bank, o Revolut US y Ramp sobre Lead Bank), la lista brands para que el cliente indique cuál es la suya.
{
"data": {
"routing": "091311229",
"valid": true,
"bank": {
"name": "Choice Bank",
"city": "FARGO",
"state": "ND",
"url": "https://bankwithchoice.com/",
"primary_color": "#00668f",
"logo_url": "https://media.qvapay.com/banks/ins_119497.png",
"institution_id": "ins_119497",
"source": "plaid",
"brands": [
{ "institution_id": "ins_116794", "name": "Mercury", "url": "https://mercury.com/", "primary_color": "#5e6cd4", "logo_url": "https://media.qvapay.com/banks/ins_116794.png" }
]
},
"degraded": false,
"checked_at": "2026-10-21T15:00:00.000Z"
}
}| Campo | Significado |
|---|---|
valid | false si la ruta no tiene 9 dígitos o falla el dígito de control (entonces reason es format, checksum o bic, y bank es null) |
bank | null cuando el número es válido pero ningún directorio lo conoce. No es motivo para rechazar el retiro: escribe el nombre del banco que te dé el cliente |
bank.brands | Fintechs que operan sobre ese número de ruta; opcional mostrarlas |
degraded | true si algún directorio no respondió a tiempo. Vuelve a consultar más tarde si necesitas el dato |
logo_url, city, state, url, primary_color | Pueden venir null |
La consulta es informativa: POST /withdraw solo valida los 9 dígitos y el dígito de control, nunca que el banco esté en el directorio. Las respuestas se cachean (una ruta se resuelve una sola vez), y hay un límite por usuario de unas 60 consultas por minuto (429 si se supera).
Validar antes de llamar
El dígito de control ABA se puede comprobar en el cliente sin red, y así solo consultas rutas que pueden existir:
const abaValid = (rn) => /^\d{9}$/.test(rn) && [...rn].reduce((sum, ch, i) => sum + Number(ch) * [3, 7, 1][i % 3], 0) % 10 === 0
abaValid('026009593') // true (Bank of America)
abaValid('026009594') // false (un dígito mal tecleado)Error en POST /withdraw
| Respuesta | Causa |
|---|---|
400 code: "BANK_ROUTING_INVALID" | Nro de Ruta o ACH no es un ABA válido. reason indica format (no son 9 dígitos), checksum (dígito de control) o bic (es un SWIFT/BIC; la respuesta trae expected_method: "BANK_INTL") |
400 code: "SWIFT_INVALID" | En BANK_INTL / BANK_EUR, el campo SWIFT no tiene forma de BIC (8 u 11 caracteres) |
El control del ABA se despliega por canal: hoy lo exige el asistente web, y las apps y los clientes API reciben un aviso en los registros de QvaPay antes de que pase a ser obligatorio para todos. Envía rutas válidas desde ya.