Check Card Account (ANI)

La API Check Card Account valida una tarjeta sin procesar un pago. Realiza hasta tres verificaciones más un perfilado de capacidades de la tarjeta y devuelve los resultados:

• AVS — Address Verification Service (coincidencia de la dirección de facturación) — todas las redes de tarjetas
• CVC — Card Verification Code (coincidencia del código de seguridad) — todas las redes de tarjetas
• AAV Cardholder Name — Account Name Inquiry de Visa (coincidencia del nombre del tarjetahabiente contra los registros del emisor) — solo tarjetas Visa

Las verificaciones AVS y CVC son controles estándar realizados para cualquier tarjeta. La verificación del nombre del tarjetahabiente está impulsada por el producto Account Name Inquiry (ANI) de Visa, que consulta los registros del banco emisor para verificar que el nombre enviado coincida con el nombre legal en la cuenta. ANI solo está disponible para tarjetas Visa — para tarjetas no Visa, verificationResults.aavCardholderName devuelve NOT_SUPPORTED.

La respuesta también reporta la capacidad OCT (push/payout) y AFT (fondeo/pull) de la tarjeta para que puedas decidir la elegibilidad de una tarjeta para un flujo determinado antes de iniciar una transacción.

¿Qué es Visa ANI?

Account Name Inquiry (ANI) es un producto de Visa que permite a los comercios verificar el nombre del tarjetahabiente directamente con el banco emisor antes de una transacción financiera o de forma independiente a ella. Cuando se envía una tarjeta, Visa reenvía el primer nombre, segundo nombre y apellido proporcionados al emisor, quien los compara contra el nombre legal en la cuenta y devuelve un resultado de coincidencia.

Detalles clave sobre Visa ANI:

• Solo Visa — ANI es un servicio de la red Visa. No está disponible para Mastercard, Amex, Discover u otras redes.
• Participación del emisor — ANI se volvió obligatorio para los emisores Visa de EE. UU. y Canadá en octubre de 2023, lo que significa que la mayoría de los emisores Visa en estos mercados lo soportan. Algunos emisores fuera de estos mercados pueden aún no soportar ANI, en cuyo caso el resultado será NOT_SUPPORTED.
• Coincidencia de nombres — Visa verifica los componentes de primer nombre, segundo nombre y apellido por separado contra los registros del emisor. Como mínimo, debe proporcionarse el apellido. El emisor devuelve la coincidencia más cercana cuando hay varios nombres registrados (p. ej., cuentas conjuntas).
• Independiente del pago — ANI opera de forma independiente a la transacción financiera. No se retienen ni se mueven fondos.
• Exclusiones — Las tarjetas empresariales/corporativas y las tarjetas prepagadas no recargables sin un nombre registrado no son soportadas por ANI.

Casos de Uso

• Onboarding — Valida la tarjeta de un cliente antes de almacenarla para cargos futuros
• Prevención de fraude — Confirma que la persona que envía la tarjeta es el tarjetahabiente real
• Mejora de KYC — Cruza el nombre en la tarjeta con el nombre proporcionado durante la verificación de identidad
• Elegibilidad de payout — Verifica octStatus antes de enviar fondos a una tarjeta; verifica aftStatus antes de extraerlos
• Verificación de tarjeta guardada — Comprueba que una tarjeta almacenada sigue siendo válida y pertenece a la persona esperada

Cómo Funciona

1. Tokenize card          2. POST /v2/check-card-account       3. Read results
   (client-side)             (server-side)
       │                          │                             For all cards:
       ▼                          ▼                               → verificationResults.avs
   inyo.js encrypts       Gateway verifies AVS + CVC             → verificationResults.cvc
   card + name →          for all cards. If Visa,                → octStatus / aftStatus
   returns cardTokenId    also queries ANI for                  For Visa cards only:
                          cardholder name match →                 → verificationResults.aavCardholderName

Nota: Esta API no realiza cargos a la tarjeta ni crea un pago. Es puramente una llamada de validación. No se requiere ningún monto en la solicitud.

Endpoint

POST https://{FQDN}/v2/check-card-account

Encabezados:

Cuerpo de la Solicitud

El payload es simplificado en comparación con las solicitudes de pago estándar — no se necesitan los campos amount, paymentType ni capture.

Objeto Raíz

Objeto sender

El remitente vincula la verificación de la tarjeta a una identidad verificada — se requieren email, phoneNumber y al menos una entrada en documents.

Objeto sender.documents[]

Objeto sender.address

Objeto sender.paymentMethod

Ejemplo de Solicitud

curl -X POST https://{FQDN}/v2/check-card-account \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalPaymentId": "card-check-001",
    "ipAddress": "203.0.113.42",
    "sender": {
      "firstName": "John",
      "lastName": "Smith",
      "email": "[email protected]",
      "phoneNumber": "+15555550123",
      "birthDate": "1985-04-12",
      "birthCountryCode": "US",
      "documents": [
        {
          "document": "123-45-6789",
          "type": "SSN",
          "countryCode": "US"
        }
      ],
      "address": {
        "countryCode": "US",
        "stateCode": "NY",
        "city": "New York",
        "line1": "123 Main Street",
        "zipCode": "10001"
      },
      "paymentMethod": {
        "type": "CARD",
        "cardTokenId": "ab5fc589-8b48-4531-94c0-68b0629c13fe"
      }
    }
  }'

Respuesta

Verificada (200)

{
  "card": {
    "created": "2026-05-16 16:37:40",
    "issuerName": "MODULR FS, LTD.",
    "issuerCountry": "UNITED KINGDOM",
    "bin": "446203",
    "lastFour": "0000"
  },
  "verificationResults": {
    "avs": "PARTIAL_MATCH",
    "cvc": "NOT_SUPPORTED",
    "aavCardholderName": "APPROVED"
  },
  "octStatus": {
    "capable": false,
    "highPerforming": false,
    "lowPerforming": false
  },
  "aftStatus": {
    "capable": true,
    "highPerforming": true,
    "lowPerforming": false
  },
  "redirectAcsUrl": ""
}

Desafío 3DS (200)

El banco emisor requiere autenticación del tarjetahabiente antes de devolver los resultados de verificación. redirectAcsUrl viene poblado y los resultados de verificación quedan pendientes hasta que el desafío se completa:

{
  "card": {
    "issuerName": "MODULR FS, LTD.",
    "issuerCountry": "UNITED KINGDOM",
    "bin": "446203",
    "lastFour": "0000"
  },
  "verificationResults": {
    "avs": "N/A",
    "cvc": "N/A",
    "aavCardholderName": "N/A"
  },
  "redirectAcsUrl": "https://{FQDN}/secure-code/start-challenge?token=dce568c6-..."
}

Cuando redirectAcsUrl no está vacío, redirige al tarjetahabiente a esa URL. Consulta Manejo de 3D Secure para el flujo completo.

Campos de la Respuesta

card

verificationResults

octStatus / aftStatus

Indicadores de capacidad de la tarjeta. OCT (Original Credit Transaction) refleja la capacidad de la tarjeta para recibir pushes/payouts; AFT (Account Funding Transaction) refleja su capacidad para fondear pulls.

redirectAcsUrl

Interpretación de los Resultados de Verificación

Resultado AVS (verificationResults.avs)

Compara la dirección de facturación proporcionada en la solicitud con la dirección registrada en el emisor de la tarjeta.

Resultado CVC (verificationResults.cvc)

Valida el código de seguridad de 3 o 4 dígitos impreso en la tarjeta.

Resultado AAV Cardholder Name (verificationResults.aavCardholderName)

Solo tarjetas Visa. Verifica si el firstName y lastName de la solicitud coinciden con el nombre legal registrado en el banco emisor. Está impulsado por el servicio Account Name Inquiry (ANI) de Visa.

Importante: ANI solo se realiza para tarjetas Visa. Para Mastercard, Amex, Discover y otras redes, aavCardholderName devolverá NOT_SUPPORTED. En esos casos, confía en AVS y CVC para la verificación.

Formato del nombre: La comparación del nombre del tarjetahabiente la realiza el emisor de Visa, que verifica los componentes de primer nombre, segundo nombre y apellido por separado. Asegúrate de enviar el nombre exactamente como aparece en la tarjeta. Visa soporta hasta 35 caracteres por campo de nombre. Los sufijos (Jr., III) y prefijos (Dr.) no son soportados por ANI y deben omitirse.

Ejemplo de Integración

Paso 1 — Tokeniza la Tarjeta

Usa inyo.js para recopilar y tokenizar los datos de la tarjeta del lado del cliente. El nombre del tarjetahabiente ingresado en el campo data-field="cardholder" se incluye en el token.

const tokenizer = new InyoTokenizer({
  targetId: '#payment-form',
  publicKey: 'YOUR_PUBLIC_KEY',
  storeLaterUse: false,
  threeDSData: { enable: true, enablePostMessage: true },
  successCallback: (response) => {
    if (response.reasonCode === 'WAITING_TRANSACTION') {
      checkCardAccount(response.additionalData.token);
    }
  },
  errorCallback: (err) => console.error('Tokenization failed:', err)
});

Paso 2 — Llama a Check Card Account

Envía el token a tu backend, que llama a la API Check Card Account:

async function checkCardAccount(cardTokenId) {
  const response = await fetch('https://{FQDN}/v2/check-card-account', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      externalPaymentId: crypto.randomUUID(),
      ipAddress: customerIpAddress,
      sender: {
        firstName: 'John',
        lastName: 'Smith',
        email: '[email protected]',
        phoneNumber: '+15555550123',
        documents: [
          { document: '123-45-6789', type: 'SSN', countryCode: 'US' }
        ],
        paymentMethod: {
          type: 'CARD',
          cardTokenId: cardTokenId
        }
      }
    })
  });

  const result = await response.json();

  if (result.redirectAcsUrl) {
    // Manejar 3DS — redirigir o abrir un iframe
    window.open(result.redirectAcsUrl, '_blank');
    return;
  }

  // Evaluar las señales de verificación estructuradas
  console.log('AVS:', result.verificationResults.avs);
  console.log('CVC:', result.verificationResults.cvc);
  console.log('ANI (Name):', result.verificationResults.aavCardholderName);
  console.log('Push (OCT) capable:', result.octStatus?.capable);
  console.log('Pull (AFT) capable:', result.aftStatus?.capable);
}

Paso 3 — Evalúa los Resultados

Combina todas las señales para tomar una decisión. Recuerda que aavCardholderName solo es significativo para tarjetas Visa — para otras redes será NOT_SUPPORTED.

function evaluateCardCheck(result) {
  // Desafío 3DS pendiente — resultados aún no disponibles
  if (result.redirectAcsUrl) {
    return { accept: false, reason: '3DS challenge required' };
  }

  const { avs, cvc, aavCardholderName } = result.verificationResults;

  // CVC no coincide — tarjeta no está en posesión
  if (cvc === 'FAILED') {
    return { accept: false, reason: 'Invalid security code' };
  }

  // Visa ANI: nombre no coincide — alto riesgo
  // (NOT_SUPPORTED significa tarjeta no Visa o emisor sin soporte de ANI — no es una falla)
  if (aavCardholderName === 'FAILED') {
    return { accept: false, reason: 'Cardholder name does not match issuer records (Visa ANI)' };
  }

  // Todas las verificaciones disponibles pasaron
  if (avs === 'APPROVED' && (cvc === 'APPROVED' || cvc === 'NOT_SUPPORTED')) {
    const aniStatus = aavCardholderName === 'NOT_SUPPORTED'
      ? 'not available (non-Visa or unsupported issuer)'
      : 'name verified';
    return { accept: true, reason: `AVS + CVC passed; ANI: ${aniStatus}` };
  }

  // Resultados parciales — usa tu propia lógica de riesgo
  return { accept: true, reason: 'Partial verification — review recommended' };
}

Pruebas

Usa la siguiente tarjeta de prueba en sandbox para Check Card Account:

Usa el nombre de tarjetahabiente AUTHORISED para simular un resultado aprobado. Consulta Datos de Prueba — Tarjetas para los valores de simulación de CVV y AVS.

Buenas Prácticas

1. Envía siempre la dirección de facturación — Incluir la dirección habilita la verificación AVS junto con el CVC (y ANI para Visa), dándote múltiples señales de fraude independientes sin importar la red de la tarjeta.

2. Haz coincidir el nombre del tokenizador con el nombre de la API — El campo cardholder del formulario del tokenizador debe contener el mismo nombre que pasas como sender.firstName y sender.lastName. Para Visa ANI, las discrepancias entre el nombre tokenizado y el nombre de la API harán que el emisor devuelva un resultado de no coincidencia.

3. No dependas de una sola señal — Evalúa AVS + CVC en conjunto para todas las tarjetas, y agrega el resultado de ANI para Visa. Un solo resultado FAILED no significa necesariamente fraude, pero múltiples fallas son un indicador fuerte.

4. Maneja NOT_SUPPORTED con elegancia — El campo aavCardholderName devuelve NOT_SUPPORTED para todas las tarjetas no Visa, y para tarjetas Visa de emisores que aún no soportan ANI. Este es el comportamiento esperado — recurre a los resultados de AVS y CVC para tu decisión de fraude.

5. Verifica OCT/AFT antes de transaccionar — Usa octStatus.capable para confirmar que una tarjeta puede recibir un payout antes de un push, y aftStatus.capable antes de un pull. Los niveles highPerforming / lowPerforming te ayudan a anticipar las tasas de éxito de autorización.

6. Úsalo antes de almacenar tarjetas — Ejecuta una llamada a Check Card Account antes de guardar un token de tarjeta con storeLaterUse: true para confirmar que la tarjeta es válida y pertenece a la persona esperada.

7. Usa el nombre legal de la tarjeta — Visa ANI compara contra el nombre legal que el emisor tiene registrado, no apodos ni nombres preferidos. Omite los sufijos (Jr., III) y prefijos (Dr.) ya que no son soportados por Visa ANI.

Qué Sigue

• Tokenización de Tarjetas — Configura la tokenización de tarjetas del lado del cliente
• Manejo de AVS / CVC — Análisis a fondo de la verificación de dirección y código de seguridad
• Manejo de 3D Secure — Maneja las respuestas CHALLENGE
• Autorización de un Pago con Tarjeta — Crea transacciones de pago reales después de la validación