Check Card Account

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 — correspondência do nome do portador com os registros do emissor — cartões Visa e Mastercard (veja Verificação do Nome do Portador)

As verificações de AVS e CVC são checagens padrão realizadas para qualquer cartão. A verificação do nome do portador pergunta ao banco emissor se o nome enviado corresponde ao nome legal na conta.

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.

Verificação do Nome do Portador

A verificação de nome compara sender.firstName e sender.lastName com o nome legal que o banco emissor tem registrado. Cada bandeira faz isso pelo próprio serviço:

Para as duas bandeiras:

• Habilitada por conta — A Inyo habilita a verificação de nome para cada bandeira na sua conta. Depois de habilitada, todo cartão dessa bandeira é verificado pelo serviço da própria bandeira em cada chamada da Check Card Account. Enquanto não estiver habilitada, a verificação roda sem ela e aavCardholderName não traz veredito.
• Nenhum valor é movimentado — A verificação de nome roda sem transação financeira. Nenhum valor é retido ou movimentado.
• A verificação é aprovada mesmo quando o nome não confere — A resposta mantém o formato verificado. Decida pelo aavCardholderName.
• Outras bandeiras — Amex, Discover e outras redes não têm verificação de nome; aavCardholderName vem como NOT_SUPPORTED.
• Formato do nome — Envie o nome exatamente como aparece no cartão, com pelo menos o sobrenome. Omita sufixos (Jr., III) e prefixos (Dr.). Em contas conjuntas o emissor retorna a correspondência mais próxima.

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 (somente cartões Visa)
• Verificação de cartão em arquivo — Confirme que um cartão armazenado ainda é válido e pertence à pessoa esperada

Como Funciona

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

    B->>G: Dados do cartão +<br/>nome do portador
    G-->>B: cardTokenId
    B->>S: cardTokenId
    S->>G: POST<br/>/v2/check-card-account
    alt Mastercard com<br/>validação de nome
        G->>I: Account Validation:<br/>nome + CVC
    else Outros cartões
        G->>I: Autorização de valor zero:<br/>AVS + CVC
        opt Visa com verificação<br/>de nome
            G->>I: Consulta de nome<br/>ANI
        end
    end
    I-->>G: Resultados
    G-->>S: verificationResults +<br/>octStatus / aftStatus

Nota: Esta API não cobra o cartão — ela roda como uma autorização de valor zero, então nenhum recurso é retido ou movimentado. Nenhum amount é 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. Internamente o gateway executa a verificação como uma autorização CHECK de valor zero, então a requisição é validada contra o schema do endpoint e contra o schema compartilhado de pagamentos com cartão. As tabelas abaixo refletem o resultado combinado.

Objeto Raiz

Objeto sender

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

Resposta

Três desfechos compartilham o HTTP 200 e não compartilham a forma do corpo. Ramifique pelos campos presentes, nunca só pelo código de status.

Verificado (200)

A autorização de valor zero foi aprovada. card, verificationResults, octStatus, aftStatus e redirectAcsUrl estão sempre 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": ""
}

Chamadas repetidas são respondidas com o resultado armazenado. Depois que o ANI foi executado para um dado firstName + lastName + token do cartão, uma chamada idêntica devolve o resultado registrado em vez de consultar o emissor novamente. Alterar qualquer um dos nomes gera uma nova consulta ao emissor. Uma verificação de nome Mastercard nunca é respondida com resultado armazenado.

Desafio 3DS (200)

O banco emissor exige autenticação do portador antes de os resultados serem conhecidos. O corpo mantém a forma verificada, redirectAcsUrl vem preenchido e todas as verificações retornam NOT_SUPPORTED até o desafio ser concluído:

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

Quando redirectAcsUrl não está vazio, redirecione o portador para essa URL — e não leia as verificações deste corpo, elas ainda não trazem veredito. Veja Tratando o 3D Secure para o fluxo completo.

Recusado (200)

Quando a autorização de valor zero subjacente não é aprovada, o endpoint responde com a forma de resposta de pagamento. Não há objeto verificationResults, e os resultados das verificações chegam 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": ""
}

Teste a existência de verificationResults antes de lê-lo. Note que N/A pode aparecer nesses campos planos — nunca aparece dentro de verificationResults.

Erro de Validação (400)

Todos os campos que falharam na validação são reportados de uma só vez:

{
  "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 da Resposta

Campos nulos são omitidos da resposta, então um registro de cartão sem nome do emissor simplesmente não traz a chave issuerName.

card

verificationResults

octStatus / aftStatus

Indicadores de capacidade do cartão, preenchidos somente para cartões Visa. OCT (Original Credit Transaction) reflete a capacidade do cartão de receber envios/payouts; AFT (Account Funding Transaction) reflete a capacidade de financiar cobranças.

Para um cartão não Visa a consulta de readiness não é executada, então os três indicadores voltam como false. Isso significa "não avaliado" — não "incapaz".

redirectAcsUrl

Entendendo os Resultados da Verificação

Os três valores são as descrições de resultado do emissor/adquirente resolvidas pelo mapeamento de códigos de provedor do gateway, com uma normalização adicional no gateway: um resultado ausente, vazio, NA ou N/A se torna NOT_SUPPORTED. Por isso N/A nunca chega até você dentro de verificationResults.

Somente APPROVED é aprovação. O conjunto de valores depende do emissor e do adquirente, então compare por igualdade com APPROVED em vez de enumerar strings de falha.

Resultado do AVS (verificationResults.avs)

Compara o endereço de cobrança de sender.address com o endereço registrado no emissor do cartão. Os cinco campos de endereço obrigatórios alimentam a comparação.

Resultado do CVC (verificationResults.cvc)

Valida o código de segurança capturado durante a tokenização. A requisição da Check Card Account não carrega código de segurança — ele viaja dentro do token do cartão.

Resultado do Nome do Portador AAV (verificationResults.aavCardholderName)

Se sender.firstName e sender.lastName correspondem ao nome legal registrado no banco emissor. Quais bandeiras fazem essa verificação, e os valores que cada uma retorna, estão em Verificação do Nome do Portador.

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: `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) {
    // 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('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

Ramifique primeiro pela forma do corpo e depois pelas verificações. Somente APPROVED é aprovação, e aavCardholderName traz veredito apenas para cartões Visa e Mastercard, depois que a verificação de nome estiver habilitada para essa bandeira na sua conta.

function evaluateCardCheck(result) {
  // Recusado: a forma de resposta de pagamento, sem o objeto verificationResults
  if (!result.verificationResults) {
    return { accept: false, reason: result.message || `Recusado (${result.responseCode})` };
  }

  // Desafio 3DS pendente — as verificações ainda não trazem veredito
  if (result.redirectAcsUrl) {
    return { accept: false, reason: 'Desafio 3DS necessário' };
  }

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

  // Tudo que não é APPROVED nem um valor sem sinal é divergência
  if (!passed(cvc) && !noSignal(cvc)) {
    return { accept: false, reason: `O CVC não correspondeu (${cvc})` };
  }
  if (!passed(aavCardholderName) && !noSignal(aavCardholderName)) {
    return { accept: false, reason: `O nome não correspondeu aos registros do emissor (${aavCardholderName})` };
  }
  if (!passed(avs) && !noSignal(avs)) {
    return { accept: false, reason: `O AVS não correspondeu (${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: 'Nenhuma verificação retornou resultado — aplique sua própria lógica de risco' };
}

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. No sandbox o resultado do nome é escolhido pelo sender.lastName para qualquer bandeira, então lá uma verificação Mastercard roda como uma Visa: avs traz resultado e aavCardholderName nunca vem como NOT_CHECKED. Consulte Dados de Teste — Cartões para os valores de simulação de nome, CVV e AVS.

Boas Práticas

1. Envie o endereço de cobrança completo — countryCode, stateCode, city, line1 e zipCode são todos obrigatórios, e são exatamente o que o AVS compara. Envie state junto de stateCode para que o registro de endereço armazenado também o tenha.

2. Faça o nome do tokenizador coincidir com o da API — O campo cardholder do formulário do tokenizador deve conter o mesmo nome enviado em sender.firstName e sender.lastName. Na verificação de nome da Visa e da Mastercard, divergência entre o nome tokenizado e o da API faz o emissor retornar um resultado sem correspondência.

3. Decida por APPROVED, não por strings de falha — Os valores de resultado vêm do emissor e do adquirente, então o vocabulário de falha não é fixo. Aceite apenas APPROVED; trate qualquer outro valor que não seja NOT_CHECKED ou NOT_SUPPORTED como divergência.

4. Trate NOT_CHECKED e NOT_SUPPORTED com cuidado — Nenhum dos dois é falha. Ambos significam que a verificação não produziu resultado, seja porque a bandeira não tem verificação de nome, porque o emissor não executa a verificação, ou porque há um desafio 3DS pendente. Recorra às verificações que retornaram resultado.

5. octStatus / aftStatus são exclusivos de Visa — Para um cartão não Visa a consulta de readiness nunca é executada e os três indicadores vêm como false. Não leia isso como "este cartão não pode receber um payout".

6. Ramifique pela forma do corpo, não pelo código de status — Uma verificação recusada responde HTTP 200 com a forma de resposta de pagamento e sem verificationResults. Teste a existência desse objeto antes de lê-lo.

7. Envie externalPaymentId e ipAddress — Ambos são obrigatórios, e o IP precisa ser um literal IPv4 ou IPv6 válido. Um valor ausente ou malformado falha na validação com HTTP 400 antes de qualquer contato com o cartão.

8. Use antes de armazenar cartões — Rode 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.

9. Use o nome legal do cartão — As verificações de nome da Visa e da Mastercard comparam com o nome legal que o emissor tem registrado, não apelidos ou nomes preferidos. Omita sufixos (Jr., III) e prefixos (Dr.), que as verificações de nome não suportam.

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