Capture o cartão com o SDK de campos

O SDK de campos coloca os inputs de cartão (número, validade, código de segurança e nome) dentro de iframes da Accelerazione, embutidos no seu checkout. O comprador digita nesses campos, o SDK envia os dados direto para a Accelerazione e devolve à sua página um token temporário (tok_…). Você envia esse token ao seu backend e cobra com ele.

O número completo do cartão e o código de segurança nunca chegam à sua página, ao seu JavaScript nem ao seu servidor.

Em resumo:

1. Os campos de cartão são iframes da Accelerazione dentro do seu checkout. A moldura e o layout são seus.
2. Enquanto o comprador digita, sua página recebe só o estado do campo: bandeira, BIN e se está completo.
3. No clique em pagar, o campo envia o cartão direto para a Accelerazione, sem passar pela sua página nem pelo seu servidor.
4. A Accelerazione devolve um token tok_…, que sua página repassa ao seu servidor.
5. Seu servidor cria a cobrança com card.token.

Antes de começarCopiar link da seção

• Habilitação da sua conta para o SDK de campos. Sem ela, a abertura de sessão responde 403 card_sdk_not_enabled.
• Permissão card-token-sessions na chave de API do ambiente.
• O resto da integração de cartão já funcionando: sessão 3DS, coleta do dispositivo e desafio 3DS. O SDK de campos substitui só a coleta dos dados do cartão; o 3DS continua igual.

Os exemplos usam as variáveis de Ambientes e endereços: DM_API_BASE e DM_HOOKS_BASE no servidor e na configuração do checkout.

1. Abra a sessão no servidorCopiar link da seção

Abra uma sessão a cada checkout, no seu backend, com a chave de API. O corpo é vazio: a conta vem da chave.

curl -X POST "$DM_API_BASE/v1/card-token-sessions" \
  -H "Authorization: $DM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "session_token": "cts_9J4W2C7X5N8QK2R4T6Y8V0H2M4P6A1B3",
  "expires_at": "2026-11-02T20:06:00Z",
  "max_tokens": 5
}

Entregue ao navegador só session_token (e, se quiser, expires_at). A chave de API nunca sai do servidor.

2. Carregue o SDK e libere as origensCopiar link da seção

<script src="https://efv0xy10tk.execute-api.us-east-1.amazonaws.com/card/v1/card.js"></script>

O script cria o objeto global DMCard. Ele precisa ser carregado por essa tag, da CDN da Accelerazione: não copie o arquivo para o seu servidor nem o empacote no seu bundle.

Se o checkout usa Content Security Policy, acrescente:

Content-Security-Policy:
  script-src 'self' https://efv0xy10tk.execute-api.us-east-1.amazonaws.com;
  frame-src https://efv0xy10tk.execute-api.us-east-1.amazonaws.com

Mantenha as origens que o 3DS já exige (Hooks e o serviço de coleta). Os campos usam a CSP própria deles e conversam só com a Accelerazione.

3. Monte os camposCopiar link da seção

Escolha entre um bloco único (número, validade, código e nome no mesmo campo) e campos separados. O bloco único é o mais simples e funciona melhor com o preenchimento automático do navegador.

<div id="cartao"></div>
<button id="pagar">Pagar</button>

const dm = DMCard({ sessionToken, locale: 'pt-BR' });
const cartao = dm.create('card').mount('#cartao');

Não misture o bloco único com campos separados na mesma instância. Cada tipo de campo pode ser criado uma vez por instância.

Os containers precisam estar no DOM principal da página: um container dentro de Shadow DOM é recusado com erro. Em Web Components, use um container no light DOM ou num slot.

Acompanhe o estado dos camposCopiar link da seção

Os campos avisam a sua página sobre o estado, nunca sobre o valor:

numero.on('change', ({ empty, complete, error, brand, bin }) => {
  botaoPagar.disabled = !complete;
  mensagem.textContent = error ? error.message : '';
  mostrarBandeira(brand);
});

bin traz os seis primeiros dígitos, para você exibir a bandeira e iniciar a coleta 3DS (passo 5). Os demais eventos são ready, focus, blur e escape. Detalhes na referência do SDK.

4. Gere o token e envie ao seu servidorCopiar link da seção

Quando o comprador clicar em pagar, peça o token:

document.querySelector('#pagar').addEventListener('click', async () => {
  const result = await dm.createToken();

  if (result.error) {
    tratarErroDeTokenizacao(result.error.code); // tabela abaixo
    return;
  }

  // Só o token vai para o seu servidor.
  await fetch('/checkout/pagar', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ cardToken: result.token, pedidoId }),
  });
});

{
  "token": "tok_01M0FVG11PZK94T569VFYE4FY3",
  "expiresAt": "2026-11-02T20:10:00Z",
  "card": { "brand": "MASTERCARD", "bin": "55555555", "last4": "4444", "exp_month": 12, "exp_year": 2030 }
}

card serve para mostrar ao comprador e para o seu registro. Repare na grafia: expiresAt em camelCase, os campos de card em snake_case. O bin do resultado pode ter oito dígitos (cartões com 16 dígitos ou mais); o dos eventos tem seis.

Quando o comprador sair do checkout, libere os campos:

dm.destroy();

Erros ao gerar o tokenCopiar link da seção

createToken não lança exceção por erro de cartão ou de rede: o resultado traz error.code.

5. Mantenha o 3DS conectadoCopiar link da seção

O SDK de campos não autentica o comprador. A coleta do dispositivo continua com o DM3DS. Use o BIN do evento change para iniciar a coleta assim que o comprador digitar o começo do cartão:

let coleta;
numero.on('change', ({ bin }) => {
  if (bin && !coleta) {
    coleta = DM3DS.collectDeviceData(sessao3ds, {
      baseUrl: DM_HOOKS_BASE, // origem Hooks do ambiente, da sua configuração
      cardBin: bin,
    });
  }
});

No bloco único, registre o mesmo listener em cartao. Antes de enviar a cobrança, espere coleta resolver, como na integração sem SDK.

6. Cobre com o tokenCopiar link da seção

No servidor, crie a cobrança como de costume, trocando os dados do cartão por card.token:

{
  "amount": 10990,
  "currency": "BRL",
  "paymentMethods": [{
    "type": "CreditCard",
    "amount": 10990,
    "card": { "token": "tok_01M0FVG11PZK94T569VFYE4FY3" }
  }],
  "paymentMethodOptions": {
    "creditCard": {
      "installments": 1,
      "threeDSecure": "automatic",
      "threeDs": { "sessionToken": "3ds_sess_9J4W2C7X5N8QK2R4T6Y8V0H2M4P6A1B3" }
    }
  }
}

O resto da requisição (comprador, endereço, split, postbackUrl, metadata) segue Crie a cobrança com cartão, e os desfechos são os mesmos: Succeeded, Failed, Processing ou RequiresAction.

Regras do token na cobrança:

• Uma cobrança por token. Depois de usado, o token não serve para outra cobrança, nem se a primeira foi recusada. Para uma nova tentativa, gere um novo token (e abra nova sessão 3DS).
• Repetir a mesma cobrança é seguro. Em falha de rede, repita com a mesma Idempotency-Key e o mesmo corpo. Não crie outra cobrança por causa de um timeout: consulte a primeira.
• Validade de 1 hora. Gere o token perto do clique em pagar, não no carregamento da página.
• O token não é um cartão salvo. Para guardar cartão para compras futuras, veja Tokenize um cartão.

Se o problema com o token for detectado depois do início da autenticação 3DS, a cobrança volta 201 com status: "Failed" e o mesmo código em lastPaymentError.code.

Tokenizar com sucesso não garante a venda: a aprovação continua dependendo da conta, do 3DS e do emissor.

Erros ao abrir a sessãoCopiar link da seção

Segurança e PCICopiar link da seção

O SDK foi feito para que dados de cartão fiquem fora do seu ambiente. Para aproveitar isso:

• Mantenha a captura inteiramente nos campos do SDK. Nenhum input de cartão seu, nem cópia do valor por script.
• Envie ao seu backend apenas o token.
• Carregue o SDK da CDN da Accelerazione, com CSP restrita; nunca hospede os campos na origem do seu checkout.
• Não registre em log corpos de requisição do checkout.

A elegibilidade do seu checkout a um questionário PCI simplificado (como o SAQ A) depende da sua avaliação de conformidade e da documentação de compliance da Accelerazione. Peça essa documentação à equipe de integração. Usar o SDK, por si só, não é uma certificação.

Checklist antes de abrir para compradoresCopiar link da seção

• A chave de API fica só no servidor; a rota que abre a sessão exige comprador autenticado e proteção CSRF.
• Uma sessão por checkout; nova sessão em session_expired e session_exhausted.
• Botão de pagar desabilitado até os campos completos e durante a tokenização.
• Todos os códigos de createToken tratados com mensagem ao comprador.
• Coleta 3DS iniciada com o BIN do evento e concluída antes da cobrança.
• Cobrança com card.token, Idempotency-Key e os quatro desfechos tratados.
• Novo token a cada nova tentativa de pagamento.
• dm.destroy() ao sair do checkout.
• CSP liberando a origem do SDK do ambiente (https://payments-js.kirvano.com em produção) em script-src e frame-src.
• Testado em navegadores e celulares reais, inclusive com preenchimento automático.

Para opções de aparência, idioma, versões fixas e integração com React, Vue e Angular, veja a referência do SDK.