Colete os dados do dispositivo
Carregue o SDK DM3DS no checkout e execute a coleta de dados do dispositivo do comprador antes de criar a cobrança.
O emissor do cartão decide se pede ou não um desafio ao comprador com base em dados do dispositivo: navegador, idioma, tela, fuso. O SDK DM3DS coleta esses dados no navegador e os registra na sessão que você abriu no servidor.
Execute a coleta sempre que o comprador pagar com crédito, mesmo com threeDSecure: "automatic". Uma cobrança pode exigir desafio durante o processamento, e sem a coleta a autenticação falha.
1. Carregue o SDK
<script src="https://efv0xy10tk.execute-api.us-east-1.amazonaws.com/sdk/3ds.js"></script>O script expõe um único objeto global, window.DM3DS, imutável.
2. Inicie a coleta
Chame collectDeviceData assim que o comprador escolher cartão, em paralelo ao preenchimento do formulário. A coleta leva de 1 a 20 segundos e não exige interação.
Guarde a origem Hooks do ambiente na configuração do checkout:
export const DM_HOOKS_BASE = 'https://dq3pq0toml.execute-api.us-east-1.amazonaws.com';import { DM_HOOKS_BASE } from './config.js';
// sessionToken veio do seu backend, que abriu a sessão em POST /v1/3ds/device-data-sessions
const collection = DM3DS.collectDeviceData(sessionToken, {
baseUrl: DM_HOOKS_BASE,
cardBin: '555555', // opcional: 6 a 8 primeiros dígitos, se você já os conhece
});
collection
.then(({ completed }) => {
recordCollectionResult(completed);
})
.catch(() => {
showCheckoutConfigurationError();
});recordCollectionResult e showCheckoutConfigurationError são funções da sua aplicação, não do SDK.
Parâmetros
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
sessionToken | Sim | O session_token da sessão aberta para esta tentativa. |
options.baseUrl | Sim | A origem Hooks do ambiente (DM_HOOKS_BASE). Não use a origem da API: as rotas de coleta só existem na Hooks. |
options.cardBin | Não | Os 6 a 8 primeiros dígitos do cartão. Qualquer outro formato é descartado em silêncio. Nunca envie o número completo. |
options.signal | Não | Um AbortSignal para cancelar a coleta. Veja o aviso em Cancelar a coleta. |
Resultado
A promessa resolve com { sessionToken, completed }.
| Situação | O que acontece | O que fazer |
|---|---|---|
completed: true | Os dados foram coletados e enviados. | Siga para a criação da cobrança. |
completed: false | A coleta não concluiu (bloqueio, tempo esgotado, rede). Não é recusa de pagamento. | Siga para a criação da cobrança e trate os estados normalmente. Se a compra exigir autenticação, a cobrança pode voltar Failed com lastPaymentError.code: "three_ds_device_data_required"; nesse caso, uma nova tentativa precisa de nova sessão e nova coleta. |
| Promessa rejeitada | Faltou sessionToken ou baseUrl. É erro de configuração do checkout. | Corrija a integração; não peça ao comprador para tentar de novo. |
Chamadas simultâneas com o mesmo sessionToken recebem a mesma promessa: a coleta acontece uma vez só.
Aguarde a coleta antes de criar a cobrança
Só envie a cobrança ao servidor depois que a promessa resolver. Uma cobrança criada com a coleta ainda em andamento pode falhar com three_ds_device_data_required. Como a coleta roda enquanto o comprador preenche o formulário, ela costuma terminar antes do clique em "Pagar"; se não terminou, mostre um indicador de carregamento por alguns segundos.
Cancelar a coleta
Abortar pelo signal resolve a promessa com completed: false, e consome a sessão: o resultado "abortado" é registrado e a mesma sessão não pode ser coletada de novo. Se o comprador voltar a pagar com cartão, abra uma sessão nova.
3. Libere as origens no navegador
Se o seu checkout usa Content Security Policy (CSP), libere as origens abaixo. Sem elas, a coleta falha em silêncio e retorna completed: false.
| Diretiva | Sandbox | Produção | Por quê |
|---|---|---|---|
script-src | https://efv0xy10tk.execute-api.us-east-1.amazonaws.com | https://payments-js.kirvano.com | Carregar o SDK. |
connect-src | https://dq3pq0toml.execute-api.us-east-1.amazonaws.com | https://payments-hooks.kirvano.com | O SDK conversa com a Hooks. |
frame-src | https://dq3pq0toml.execute-api.us-east-1.amazonaws.com e https://centinelapistag.cardinalcommerce.com | https://payments-hooks.kirvano.com e https://centinelapi.cardinalcommerce.com | Iframe da coleta e iframe do desafio. |
form-action | https://centinelapistag.cardinalcommerce.com | https://centinelapi.cardinalcommerce.com | O SDK envia o formulário de coleta a partir da sua página. |
Content-Security-Policy:
script-src 'self' https://efv0xy10tk.execute-api.us-east-1.amazonaws.com;
connect-src 'self' https://dq3pq0toml.execute-api.us-east-1.amazonaws.com;
frame-src https://dq3pq0toml.execute-api.us-east-1.amazonaws.com https://centinelapistag.cardinalcommerce.com;
form-action 'self' https://centinelapistag.cardinalcommerce.com4. Cadastre a origem do checkout
O desafio 3DS só abre dentro de iframes da origem cadastrada para a sua conta. Antes de testar, peça à equipe de integração o cadastro da origem HTTPS do checkout, no formato https://loja.example.com.
A conta tem uma origem cadastrada. Se o checkout roda em mais de uma (por exemplo www.loja.example.com e loja.example.com, ou um domínio por loja), o desafio aparece em branco e as mensagens do iframe não chegam nas origens não cadastradas. Concentre o checkout em uma origem ou fale com a equipe de integração.
Próximo passo
Com a coleta iniciada, crie a cobrança no servidor, enviando o mesmo session_token.