Check Card Account

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 — coincidencia del nombre del tarjetahabiente contra los registros del emisor — tarjetas Visa y Mastercard (ver Verificación del Nombre del Tarjetahabiente)

Las verificaciones AVS y CVC son controles estándar realizados para cualquier tarjeta. La verificación del nombre del tarjetahabiente pregunta al banco emisor si el nombre enviado coincide con el nombre legal en la cuenta.

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.

Verificación del Nombre del Tarjetahabiente

La verificación de nombre compara sender.firstName y sender.lastName con el nombre legal que el banco emisor tiene registrado. Cada red la realiza con su propio servicio:

Para ambas redes:

• Habilitada por cuenta — Inyo habilita la verificación de nombre para cada red en tu cuenta. Una vez habilitada, toda tarjeta de esa red se verifica con el servicio de su propia red en cada llamada a Check Card Account. Mientras no esté habilitada, la verificación se ejecuta sin ella y aavCardholderName no trae veredicto.
• No se mueve dinero — La verificación de nombre se ejecuta sin transacción financiera. No se retienen ni se mueven fondos.
• La verificación se aprueba aunque el nombre no coincida — La respuesta mantiene la forma verificada. Decide según aavCardholderName.
• Otras redes — Amex, Discover y otras redes no tienen verificación de nombre; aavCardholderName devuelve NOT_SUPPORTED.
• Formato del nombre — Envía el nombre exactamente como aparece en la tarjeta, con al menos el apellido. Omite sufijos (Jr., III) y prefijos (Dr.). En una cuenta conjunta el emisor devuelve la coincidencia más cercana.

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 (solo tarjetas Visa)
• Verificación de tarjeta guardada — Comprueba que una tarjeta almacenada sigue siendo válida y pertenece a la persona esperada

Cómo Funciona

sequenceDiagram
    participant B as Navegador<br/>inyo.js
    participant S as Tu servidor
    participant G as Inyo
    participant I as Emisor

    B->>G: Datos de la tarjeta +<br/>nombre del tarjetahabiente
    G-->>B: cardTokenId
    B->>S: cardTokenId
    S->>G: POST<br/>/v2/check-card-account
    alt Mastercard con<br/>validación de nombre
        G->>I: Account Validation:<br/>nombre + CVC
    else Otras tarjetas
        G->>I: Autorización de monto cero:<br/>AVS + CVC
        opt Visa con verificación<br/>de nombre
            G->>I: Consulta de nombre<br/>ANI
        end
    end
    I-->>G: Resultados
    G-->>S: verificationResults +<br/>octStatus / aftStatus

Nota: Esta API no realiza cargos a la tarjeta — se ejecuta como una autorización de monto cero, así que no se retienen ni mueven fondos. No se requiere amount 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. Internamente el gateway ejecuta la verificación como una autorización CHECK de monto cero, por lo que la solicitud se valida contra el esquema del endpoint y contra el esquema compartido de pagos con tarjeta. Las tablas siguientes reflejan el resultado combinado.

Objeto Raíz

Objeto sender

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": "ANI-0001",
    "ipAddress": "203.0.113.42",
    "sender": {
      "firstName": "John",
      "lastName": "Smith",
      "email": "[email protected]",
      "address": {
        "countryCode": "USA",
        "stateCode": "NY",
        "state": "NY",
        "city": "New York",
        "line1": "123 Main Street",
        "line2": "",
        "zipCode": "10001"
      },
      "paymentMethod": {
        "type": "CARD",
        "cardTokenId": "ab5fc589-8b48-4531-94c0-68b0629c13fe"
      }
    }
  }'

Respuesta

Tres resultados comparten el HTTP 200 y no comparten la forma del cuerpo. Ramifica según los campos presentes, nunca solo según el código de estado.

Verificada (200)

La autorización de monto cero fue aprobada. card, verificationResults, octStatus, aftStatus y redirectAcsUrl siempre están presentes:

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

Las llamadas repetidas se responden con el resultado almacenado. Una vez que ANI se ejecutó para un firstName + lastName + token de tarjeta dados, una llamada idéntica devuelve el resultado registrado en lugar de volver a consultar al emisor. Cambiar cualquiera de los dos nombres genera una nueva consulta al emisor. Una verificación de nombre Mastercard nunca se responde con un resultado almacenado.

Desafío 3DS (200)

El banco emisor requiere autenticación del tarjetahabiente antes de que se conozcan los resultados. El cuerpo conserva la forma verificada, redirectAcsUrl viene poblado y todas las verificaciones devuelven NOT_SUPPORTED hasta que el desafío se complete:

{
  "card": {
    "created": "2026-05-16 16:37:40",
    "issuerName": "MODULR FS, LTD.",
    "issuerCountry": "UNITED KINGDOM",
    "bin": "446203",
    "lastFour": "0000",
    "cardType": "DEBIT",
    "storeLaterUse": false
  },
  "verificationResults": {
    "avs": "NOT_SUPPORTED",
    "cvc": "NOT_SUPPORTED",
    "aavCardholderName": "NOT_SUPPORTED"
  },
  "octStatus": {
    "capable": false,
    "highPerforming": false,
    "lowPerforming": false
  },
  "aftStatus": {
    "capable": false,
    "highPerforming": false,
    "lowPerforming": false
  },
  "redirectAcsUrl": "https://{FQDN}/secure-code/start-challenge?token=dce568c6-..."
}

Cuando redirectAcsUrl no está vacío, redirige al tarjetahabiente hacia esa URL — y no leas las verificaciones de este cuerpo, todavía no traen veredicto. Consulta Manejo de 3D Secure para el flujo completo.

Rechazada (200)

Cuando la autorización de monto cero subyacente no es aprobada, el endpoint responde con la forma de respuesta de pago. No hay objeto verificationResults, y los resultados de las verificaciones llegan como campos planos:

{
  "paymentId": "870bf24b-885f-4b1f-a8de-3c3944d5e266",
  "parentPaymentId": "870bf24b-885f-4b1f-a8de-3c3944d5e266",
  "externalPaymentId": "ANI-GMT9433682",
  "created": "2026-01-26 16:25:50",
  "amount": 0.00,
  "approved": false,
  "status": "DECLINED",
  "responseCode": "PAY_022",
  "message": "Rejected by provider",
  "issuerName": "MASTERCARD EUROPE",
  "issuerCountry": "BELGIUM",
  "avsResult": "N/A",
  "cvcResult": "N/A",
  "aavCardholderNameResult": "N/A",
  "redirectAcsUrl": ""
}

Comprueba la existencia de verificationResults antes de leerlo. Nota que N/A puede aparecer en estos campos planos — nunca aparece dentro de verificationResults.

Error de Validación (400)

Se reportan a la vez todos los campos que fallaron la validación:

{
  "code": "VE_001",
  "message": "Validation error",
  "errors": [
    {
      "field": "sender.address.city",
      "message": "sender.address.city can't be empty"
    },
    {
      "field": "sender.paymentMethod.cardTokenId",
      "message": "sender.paymentMethod.cardTokenId does not match the expected format uuid"
    }
  ]
}

Campos de la Respuesta

Los campos nulos se omiten de la respuesta, así que un registro de tarjeta sin nombre de emisor simplemente no trae la clave issuerName.

card

verificationResults

octStatus / aftStatus

Indicadores de capacidad de la tarjeta, poblados solo para tarjetas Visa. OCT (Original Credit Transaction) refleja la capacidad de la tarjeta de recibir envíos/payouts; AFT (Account Funding Transaction) refleja su capacidad de fondear cobros.

Para una tarjeta no Visa la consulta de readiness no se ejecuta, por lo que los tres indicadores vuelven en false. Eso significa "no evaluado" — no "no capaz".

redirectAcsUrl

Interpretación de los Resultados de Verificación

Los tres valores son las descripciones de resultado del emisor/adquirente resueltas por el mapeo de códigos de proveedor del gateway, con una normalización adicional a nivel de gateway: un resultado ausente, vacío, NA o N/A se convierte en NOT_SUPPORTED. Por eso N/A nunca te llega dentro de verificationResults.

Solo APPROVED es una aprobación. El conjunto de valores depende del emisor y del adquirente, así que compara por igualdad con APPROVED en lugar de enumerar cadenas de falla.

Resultado AVS (verificationResults.avs)

Compara la dirección de facturación de sender.address con la dirección registrada en el emisor de la tarjeta. Los cinco campos de dirección requeridos alimentan la comparación.

Resultado CVC (verificationResults.cvc)

Valida el código de seguridad capturado durante la tokenización. La solicitud de Check Card Account no lleva código de seguridad — este viaja dentro del token de la tarjeta.

Resultado AAV Cardholder Name (verificationResults.aavCardholderName)

Si sender.firstName y sender.lastName coinciden con el nombre legal registrado en el banco emisor. Qué redes realizan esta verificación, y los valores que devuelve cada una, están en Verificación del Nombre del Tarjetahabiente.

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: `ANI-${crypto.randomUUID()}`,
      ipAddress: customerIpAddress,
      sender: {
        firstName: 'John',
        lastName: 'Smith',
        email: '[email protected]',
        address: {
          countryCode: 'USA',
          stateCode: 'NY',
          state: 'NY',
          city: 'New York',
          line1: '123 Main Street',
          line2: '',
          zipCode: '10001'
        },
        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('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

Ramifica primero según la forma del cuerpo y después según las verificaciones. Solo APPROVED es una aprobación, y aavCardholderName trae veredicto solo para tarjetas Visa y Mastercard, una vez que la verificación de nombre esté habilitada para esa red en tu cuenta.

function evaluateCardCheck(result) {
  // Rechazada: la forma de respuesta de pago, sin objeto verificationResults
  if (!result.verificationResults) {
    return { accept: false, reason: result.message || `Rechazada (${result.responseCode})` };
  }

  // Desafío 3DS pendiente — las verificaciones aún no traen veredicto
  if (result.redirectAcsUrl) {
    return { accept: false, reason: 'Se requiere desafío 3DS' };
  }

  const { avs, cvc, aavCardholderName } = result.verificationResults;
  const passed = (v) => v === 'APPROVED';
  const noSignal = (v) => v === 'NOT_CHECKED' || v === 'NOT_SUPPORTED';

  // Todo lo que no sea APPROVED ni un valor sin señal es una discrepancia
  if (!passed(cvc) && !noSignal(cvc)) {
    return { accept: false, reason: `El CVC no coincidió (${cvc})` };
  }
  if (!passed(aavCardholderName) && !noSignal(aavCardholderName)) {
    return { accept: false, reason: `El nombre no coincidió con los registros del emisor (${aavCardholderName})` };
  }
  if (!passed(avs) && !noSignal(avs)) {
    return { accept: false, reason: `El AVS no coincidió (${avs})` };
  }

  const verified = [['AVS', avs], ['CVC', cvc], ['Name', aavCardholderName]]
    .filter(([, value]) => passed(value))
    .map(([name]) => name);

  return verified.length > 0
    ? { accept: true, reason: `Verificado por ${verified.join(' + ')}` }
    : { accept: true, reason: 'Ninguna verificación devolvió resultado — aplica tu propia lógica de riesgo' };
}

Pruebas

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

Usa el nombre de tarjetahabiente AUTHORISED para simular un resultado aprobado. En sandbox el resultado del nombre se elige por sender.lastName para cualquier red, así que allí una verificación Mastercard se ejecuta como una Visa: avs trae resultado y aavCardholderName nunca devuelve NOT_CHECKED. Consulta Datos de Prueba — Tarjetas para los valores de simulación de nombre, CVV y AVS.

Buenas Prácticas

1. Envía la dirección de facturación completa — countryCode, stateCode, city, line1 y zipCode son todos requeridos, y son exactamente lo que compara AVS. Envía state junto con stateCode para que el registro de dirección almacenado también lo tenga.

2. Haz coincidir el nombre del tokenizador con el de la API — El campo cardholder del formulario del tokenizador debe contener el mismo nombre que envías en sender.firstName y sender.lastName. En la verificación de nombre de Visa y Mastercard, una discrepancia entre el nombre tokenizado y el de la API hace que el emisor devuelva un resultado sin coincidencia.

3. Decide por APPROVED, no por cadenas de falla — Los valores de resultado provienen del emisor y del adquirente, así que el vocabulario de falla no es fijo. Acepta solo APPROVED; trata cualquier otro valor que no sea NOT_CHECKED ni NOT_SUPPORTED como una discrepancia.

4. Maneja NOT_CHECKED y NOT_SUPPORTED con cuidado — Ninguno es una falla. Ambos significan que la verificación no produjo resultado, ya sea porque la red no tiene verificación de nombre, porque el emisor no ejecuta la verificación, o porque hay un desafío 3DS pendiente. Apóyate en las verificaciones que sí devolvieron resultado.

5. octStatus / aftStatus son solo para Visa — Para una tarjeta no Visa la consulta de readiness nunca se ejecuta y los tres indicadores vienen en false. No lo interpretes como "esta tarjeta no puede recibir un payout".

6. Ramifica por la forma del cuerpo, no por el código de estado — Una verificación rechazada responde HTTP 200 con la forma de respuesta de pago y sin verificationResults. Comprueba la existencia de ese objeto antes de leerlo.

7. Envía externalPaymentId e ipAddress — Ambos son requeridos, y la IP debe ser un literal IPv4 o IPv6 válido. Un valor ausente o mal formado falla la validación con HTTP 400 antes de que se contacte la tarjeta.

8. Úsalo antes de almacenar tarjetas — Ejecuta una llamada de 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.

9. Usa el nombre legal de la tarjeta — Las verificaciones de nombre de Visa y Mastercard comparan contra el nombre legal que el emisor tiene registrado, no apodos ni nombres preferidos. Omite sufijos (Jr., III) y prefijos (Dr.), que las verificaciones de nombre no soportan.

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