Check Card Account (ANI)

A API Check Card Account valida um cartão sem processar um pagamento. Ela executa até três verificações, além do perfil de capacidades do cartão, e retorna os resultados:

• AVS — Address Verification Service (correspondência do endereço de cobrança) — todas as bandeiras
• CVC — Card Verification Code (correspondência do código de segurança) — todas as bandeiras
• AAV Cardholder Name — Account Name Inquiry da Visa (correspondência do nome do portador com os registros do emissor) — somente cartões Visa

As verificações de AVS e CVC são checagens padrão realizadas para qualquer cartão. A verificação do nome do portador é fornecida pelo produto Account Name Inquiry (ANI) da Visa, que consulta os registros do banco emissor para verificar se o nome enviado corresponde ao nome legal na conta. O ANI só está disponível para cartões Visa — para cartões de outras bandeiras, verificationResults.aavCardholderName retorna NOT_SUPPORTED.

A resposta também informa a capacidade OCT (push/payout) e AFT (funding/pull) do cartão, para que você possa decidir a elegibilidade de um cartão para um determinado fluxo antes de iniciar uma transação.

O que é o Visa ANI?

O Account Name Inquiry (ANI) é um produto da Visa que permite que estabelecimentos verifiquem o nome do portador diretamente com o banco emissor antes ou independentemente de uma transação financeira. Quando um cartão é enviado, a Visa encaminha o primeiro nome, o nome do meio e o sobrenome fornecidos ao emissor, que os compara com o nome legal na conta e retorna um resultado de correspondência.

Detalhes importantes sobre o Visa ANI:

• Somente Visa — o ANI é um serviço da rede Visa. Não está disponível para Mastercard, Amex, Discover ou outras redes.
• Participação dos emissores — o ANI tornou-se obrigatório para emissores Visa dos EUA e do Canadá em outubro de 2023, o que significa que a maioria dos emissores Visa nesses mercados o suporta. Alguns emissores fora desses mercados podem ainda não suportar o ANI; nesse caso, o resultado será NOT_SUPPORTED.
• Correspondência de nomes — a Visa verifica separadamente o primeiro nome, o nome do meio e o sobrenome contra os registros do emissor. No mínimo, o sobrenome deve ser fornecido. O emissor retorna a correspondência mais próxima quando há vários nomes registrados (ex.: contas conjuntas).
• Independente do pagamento — o ANI opera independentemente da transação financeira. Nenhum valor é retido ou movimentado.
• Exclusões — cartões corporativos/empresariais e cartões pré-pagos não recarregáveis sem nome registrado não são suportados pelo ANI.

Casos de Uso

• Onboarding — Valide o cartão de um cliente antes de armazená-lo para cobranças futuras
• Prevenção de fraude — Confirme que a pessoa que enviou o cartão é o portador real
• Reforço de KYC — Cruze o nome no cartão com o nome fornecido durante a verificação de identidade
• Elegibilidade para payout — Verifique octStatus antes de enviar fundos para um cartão; verifique aftStatus antes de captar
• Verificação de cartão em arquivo — Confirme que um cartão armazenado ainda é válido e pertence à pessoa esperada

Como 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 não cobra o cartão nem cria um pagamento. É uma chamada puramente de validação. Nenhum valor é exigido na requisição.

Endpoint

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

Cabeçalhos:

Corpo da Requisição

O payload é simplificado em comparação com requisições de pagamento padrão — não são necessários os campos amount, paymentType ou capture.

Objeto Raiz

Objeto sender

O sender vincula a verificação do cartão a uma identidade verificada — email, phoneNumber e pelo menos uma entrada em documents são obrigatórios.

Objeto sender.documents[]

Objeto sender.address

Objeto sender.paymentMethod

Exemplo de Requisição

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"
      }
    }
  }'

Resposta

Verificado (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": ""
}

Desafio 3DS (200)

O banco emissor exige autenticação do portador antes de retornar os resultados da verificação. redirectAcsUrl vem preenchido e os resultados da verificação ficam pendentes até que o desafio seja concluído:

{
  "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-..."
}

Quando redirectAcsUrl não estiver vazio, redirecione o portador para ele. Consulte Tratando 3D Secure para o fluxo completo.

Campos da Resposta

card

verificationResults

octStatus / aftStatus

Indicadores de capacidade do cartão. OCT (Original Credit Transaction) reflete a capacidade do cartão de receber pushes/payouts; AFT (Account Funding Transaction) reflete a capacidade de financiar pulls.

redirectAcsUrl

Entendendo os Resultados da Verificação

Resultado do AVS (verificationResults.avs)

Compara o endereço de cobrança fornecido na requisição com o endereço registrado no emissor do cartão.

Resultado do CVC (verificationResults.cvc)

Valida o código de segurança de 3 ou 4 dígitos impresso no cartão.

Resultado do Nome do Portador AAV (verificationResults.aavCardholderName)

Somente cartões Visa. Verifica se firstName e lastName na requisição correspondem ao nome legal registrado no banco emissor. Isso é fornecido pelo serviço Account Name Inquiry (ANI) da Visa.

Importante: o ANI é realizado apenas para cartões Visa. Para Mastercard, Amex, Discover e outras redes, aavCardholderName retornará NOT_SUPPORTED. Nesses casos, baseie-se em AVS e CVC para a verificação.

Formatação do nome: a comparação do nome do portador é feita pelo emissor Visa, que verifica separadamente o primeiro nome, o nome do meio e o sobrenome. Certifique-se de passar o nome exatamente como aparece no cartão. A Visa suporta até 35 caracteres por campo de nome. Sufixos (Jr., III) e prefixos (Dr.) não são suportados pelo ANI e devem ser omitidos.

Exemplo de Integração

Etapa 1 — Tokenize o Cartão

Use o inyo.js para coletar e tokenizar os dados do cartão no lado do cliente. O nome do portador digitado no campo data-field="cardholder" é incluído no 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)
});

Etapa 2 — Chame a Check Card Account

Envie o token para o seu backend, que chama a 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) {
    // Trate o 3DS — redirecione ou abra um iframe
    window.open(result.redirectAcsUrl, '_blank');
    return;
  }

  // Avalie os sinais de verificação estruturados
  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);
}

Etapa 3 — Avalie os Resultados

Combine todos os sinais para tomar uma decisão. Lembre-se de que aavCardholderName só é significativo para cartões Visa — para outras redes, será NOT_SUPPORTED.

function evaluateCardCheck(result) {
  // Desafio 3DS pendente — resultados ainda não disponíveis
  if (result.redirectAcsUrl) {
    return { accept: false, reason: '3DS challenge required' };
  }

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

  // CVC divergente — cartão não está em posse
  if (cvc === 'FAILED') {
    return { accept: false, reason: 'Invalid security code' };
  }

  // Visa ANI: nome divergente — alto risco
  // (NOT_SUPPORTED significa cartão não-Visa ou emissor sem suporte a ANI — não é uma falha)
  if (aavCardholderName === 'FAILED') {
    return { accept: false, reason: 'Cardholder name does not match issuer records (Visa ANI)' };
  }

  // Todas as verificações disponíveis passaram
  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 parciais — use sua própria lógica de risco
  return { accept: true, reason: 'Partial verification — review recommended' };
}

Testes

Use o seguinte cartão de teste no sandbox para a Check Card Account:

Use o nome de portador AUTHORISED para simular um resultado aprovado. Consulte Dados de Teste — Cartões para valores de simulação de CVV e AVS.

Boas Práticas

1. Sempre envie o endereço de cobrança — Incluir o endereço habilita a verificação AVS junto com o CVC (e o ANI para Visa), fornecendo múltiplos sinais de fraude independentes, qualquer que seja a bandeira do cartão.

2. Faça o nome do tokenizador corresponder ao nome da API — O campo cardholder do formulário do tokenizador deve conter o mesmo nome que você passa em sender.firstName e sender.lastName. Para o Visa ANI, divergências entre o nome tokenizado e o nome enviado à API farão o emissor retornar um resultado de não correspondência.

3. Não dependa de um único sinal — Avalie AVS + CVC em conjunto para todos os cartões e adicione o resultado do ANI para Visa. Um único FAILED não significa necessariamente fraude, mas múltiplas falhas são um forte indicador.

4. Trate NOT_SUPPORTED adequadamente — O campo aavCardholderName retorna NOT_SUPPORTED para todos os cartões não-Visa e para cartões Visa de emissores que ainda não suportam ANI. Esse é o comportamento esperado — recorra aos resultados de AVS e CVC para sua decisão de fraude.

5. Verifique OCT/AFT antes de transacionar — Use octStatus.capable para confirmar que um cartão pode receber um payout antes de um push, e aftStatus.capable antes de um pull. Os níveis highPerforming / lowPerforming ajudam a antecipar as taxas de sucesso de autorização.

6. Use antes de armazenar cartões — Execute uma chamada de Check Card Account antes de salvar um token de cartão com storeLaterUse: true para confirmar que o cartão é válido e pertence à pessoa esperada.

7. Use o nome legal do cartão — O Visa ANI compara com o nome legal registrado no emissor, não apelidos ou nomes preferidos. Omita sufixos (Jr., III) e prefixos (Dr.), pois não são suportados pelo Visa ANI.

Próximos Passos

• Tokenizando Cartões — Configure a tokenização de cartões no lado do cliente
• Tratando AVS / CVC — Aprofunde-se na verificação de endereço e código de segurança
• Tratando 3D Secure — Trate respostas CHALLENGE
• Autorizando um Pagamento com Cartão — Crie transações de pagamento reais após a validação