Referência do SDK de campos

Referência do objeto global DMCard, versão 1.0.0. Para o passo a passo da integração, veja Capture o cartão com o SDK de campos.

Carregamento e versõesCopiar link da seção

Os arquivos ficam na base do SDK de cada ambiente:

Para fixar a versão, leia o valor sri de card-1.0.0.js no manifest.json e use-o em integrity:

<script
  src="https://efv0xy10tk.execute-api.us-east-1.amazonaws.com/card/v1/card-1.0.0.js"
  integrity="sha256-VALOR_DO_MANIFEST"
  crossorigin="anonymous"></script>

Use SRI apenas na URL versionada. Em card.js o conteúdo muda a cada atualização e o SRI quebraria o checkout.

O SDK precisa ser carregado pela tag <script> da CDN. Carregado de outra forma (copiado para o seu servidor, empacotado no bundle), ele lança DMCard must load from the CDN script.

DMCard(options)Copiar link da seção

Cria uma instância ligada a uma sessão.

const dm = DMCard({
  sessionToken,
  locale: 'pt-BR',
  appearance: {
    variables: { fontFamily: 'Inter, sans-serif', fontSize: '16px', colorText: '#0d0e11', colorDanger: '#d4313d' },
    rules: { '.Input::placeholder': { color: '#8a909c' } },
  },
  fonts: [{ family: 'Inter', src: 'url(https://fonts.example.com/inter.woff2)' }],
  classes: { invalid: 'campo--erro' },
});

DMCard lança erro, em vez de devolver uma instância, quando:

InstânciaCopiar link da seção

Tipos de campo em create:

Cada tipo pode ser criado uma vez por instância, e card não se combina com os demais. Violar essas regras lança Duplicate or incompatible card field.

Com campos separados, o nome do titular vem de cardHolder ou de createToken({ holderName }). É obrigatório e tem até 120 caracteres.

CampoCopiar link da seção

Opções de campo (em create e update): placeholder (texto), showIcon (mostra a bandeira, em cardNumber e card) e disabled.

Nenhum método devolve o valor digitado. Essa é a garantia do SDK: a sua página nunca lê número ou código de segurança.

EventosCopiar link da seção

Todos os eventos entregam o mesmo estado:

{
  empty: boolean;      // campo vazio
  complete: boolean;   // conteúdo completo e válido
  error?: { code: string; message?: string }; // presente quando inválido
  brand?: string;      // bandeira detectada (em cardNumber e card)
  bin?: string;        // 6 primeiros dígitos (em cardNumber e card)
}

Códigos de error no estado do campo:

message vem no idioma de locale, pronta para exibir.

Resultado de createTokenCopiar link da seção

Sucesso:

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

Erro: { "error": { "code": "..." } }, com code entre validation_error, session_expired, session_exhausted, rate_limited, network_error, tokenization_in_progress e destroyed. O que fazer em cada caso está em Erros ao gerar o token.

createToken espera até 10 segundos pelo carregamento dos campos e até 15 segundos pela resposta; depois disso devolve network_error.

AparênciaCopiar link da seção

A moldura do campo (borda, fundo, raio, espaçamento, altura) é o seu container: estilize-o com o seu CSS. O iframe tem fundo transparente. appearance estiliza só o texto dentro do campo.

appearance.variables:

appearance.rules aceita três seletores: .Input, .Input--invalid e .Input::placeholder. Dentro deles, só estas propriedades: color, fontFamily, fontSize, fontWeight, fontStyle, letterSpacing, lineHeight, textAlign e textDecoration. Outros seletores, outras propriedades e URLs são ignorados.

Classes do containerCopiar link da seção

O SDK aplica classes ao elemento em que o campo foi montado, para você estilizar os estados:

.DMCardField { border: 1px solid #cfd3da; border-radius: 10px; padding: 12px; height: 44px; }
.DMCardField--focus { border-color: #2563eb; box-shadow: 0 0 0 3px rgba(37, 99, 235, 0.2); }
.DMCardField--invalid { border-color: #d4313d; }

Acessibilidade e preenchimento automáticoCopiar link da seção

Os campos trazem rótulos, anúncio de erros para leitores de tela e autocomplete de cartão. Alguns navegadores não preenchem automaticamente campos de cartão divididos em iframes diferentes; se o preenchimento automático é importante para o seu público, prefira o bloco único (card). Teste em celulares reais antes de liberar.

Integração com frameworksCopiar link da seção

O SDK é carregado da CDN, não de um pacote npm. Em qualquer framework, o padrão é o mesmo: carregar o script uma vez, criar a instância quando o container existir e destruí-la quando o componente sair.

Guarde o endereço do SDK na configuração da aplicação, por ambiente:

export const DM_CARD_SDK_URL = 'https://efv0xy10tk.execute-api.us-east-1.amazonaws.com/card/v1/card.js';

import { DM_CARD_SDK_URL } from './config.js';

let carregando;
export function carregarDMCard() {
  if (window.DMCard) return Promise.resolve(window.DMCard);
  carregando ??= new Promise((resolve, reject) => {
    const s = document.createElement('script');
    s.src = DM_CARD_SDK_URL;
    s.onload = () => resolve(window.DMCard);
    s.onerror = () => reject(new Error('Falha ao carregar o SDK de campos'));
    document.head.appendChild(s);
  });
  return carregando;
}

'use client';
import { useEffect, useRef } from 'react';
import { carregarDMCard } from './carregar-dmcard';

export function CampoCartao({ sessionToken, onToken }: { sessionToken: string; onToken: (t: string) => void }) {
  const container = useRef<HTMLDivElement>(null);
  const dm = useRef<any>(null);

  useEffect(() => {
    let ativo = true;
    carregarDMCard().then((DMCard) => {
      if (!ativo || !container.current) return;
      dm.current = DMCard({ sessionToken, locale: 'pt-BR' });
      dm.current.create('card').mount(container.current);
    });
    return () => {
      ativo = false;
      dm.current?.destroy();
      dm.current = null;
    };
  }, [sessionToken]);

  async function pagar() {
    const result = await dm.current?.createToken();
    if (result?.token) onToken(result.token);
  }

  return (
    <>
      <div ref={container} />
      <button onClick={pagar}>Pagar</button>
    </>
  );
}

Ao trocar de sessão (por exemplo, depois de session_expired), destrua a instância e crie outra com o novo sessionToken. Os campos antigos são removidos e o que foi digitado se perde: avise o comprador.

LimitesCopiar link da seção