Integração de Transações com Cartão de Crédito utilizando 3DS
Ao realizar transações com cartão de crédito com autenticação 3DS, é necessário enviar algumas informações essenciais do comprador. Estas informações são capturadas automaticamente pelo nosso SDK JavaScript, que também gera o token, bin e bandeira do cartão.
Para gerar esses dados, é muito simples! Você só precisará importar nossa biblioteca javascript de tokenização em seu front-end e utilizar uma das duas maneiras de implementação:
Importar a biblioteca SDK:
Para todas as formas de implementação, importe nossa biblioteca no front-end:
Ambiente de Produção: https://apiv3.dompagamentos.com.br/js/sdk-3ds-dompagamentos.min.js
Ambiente Sandbox: https://hml-apiv3.dompagamentos.com.br/js/sdk-3ds-dompagamentos.min.js
<script type="text/javascript" src="https://apiv3.dompagamentos.com.br/js/sdk-3ds-dompagamentos.min.js"></script>
<script type="text/javascript" src="https://hml-apiv3.dompagamentos.com.br/js/sdk-3ds-dompagamentos.min.js"></script>
Opção 1: Implementar com Java Script:
Faça uma requisição ao método getTokenCard() para obter como resposta o token, bin e bandeira, exemplo:
Exemplo de uso:
<script type="text/javascript" src="https://apiv3.dompagamentos.com.br/js/sdk-3ds-dompagamentos.min.js"></script>
<form action="#" method="post">
<input type="hidden" id="deviceId" data-dompag="finger_print" />
<!-- Outros campos do seu formulário ... -->
<input type="hidden" name="token" id="token">
<input type="hidden" name="brand" id="brand">
<input type="hidden" name="bin" id="bin">
<input type="submit" value="Enviar" onclick="sendForm()">
</form>
<script>
function sendForm() {
//Sua chave pública:
let public_key = 'pk_6d05f363eb03512dd0960af902bacba18be7329dab32322d';
//Dados do cartão:
let data_card = {
name: 'João da Silva', //Nome do cartão
document: '11111111111', //CPF ou CNPJ
customer_id: '',//Id do consumidor caso queira gerar um token de carteira
number: '5147430374257642',//Número do cartão
cvv: '652', //Código de segurança
month: '01', //Mês que expira
year: '25', //Ano que expira
finger_print: document.getElementById('deviceId').value // A impressão digital do dispositivo do comprador
}
let installments = 1; //quantidade de parcelas
getTokenCard(public_key, data_card, installments, function (data) {
console.log('resposta: ', data);
if (data.token) {
document.getElementById('token').value = data.token;
document.getElementById('brand').value = data.brand;
document.getElementById('bin').value = data.bin;
// form.submit();
} else {
alert("ERRO: " + data.msgError);
}
});
}
</script>
// DomPagamentoForm.tsx
import React, { useState, useEffect, useRef } from 'react';
declare global {
interface Window {
getTokenCard: (
publicKey: string,
cardData: any,
installments: number,
callback: (data: any) => void
) => void;
module?: any;
}
}
const DomPagamentoForm: React.FC = () => {
const formRef = useRef<HTMLFormElement>(null);
const [formData] = useState({
name: 'João da Silva',
document: '11111111111',
number: '5147430374257642',
cvv: '652',
month: '01',
year: '25',
customer_id: '',
installments: 1,
});
const [tokenData, setTokenData] = useState({
token: '',
brand: '',
bin: '',
});
// Carrega o SDK no carregamento do componente
useEffect(() => {
(window as any).module = {};
const script = document.createElement('script');
script.src = 'https://apiv3.dompagamentos.com.br/js/sdk-dompagamentos.min.js';
script.async = true;
script.onload = () => {
delete (window as any).module;
console.log('SDK da Dom Pagamentos carregado com sucesso.');
};
document.body.appendChild(script);
}, []);
const handleSubmit = (e: React.FormEvent) => {
e.preventDefault();
const publicKey = 'pk_6d05f363eb03512dd0960af902bacba18be7329dab32322d';
if (typeof window.getTokenCard !== 'function') {
alert('SDK DomPagamentos ainda não carregada.');
return;
}
const dataCard = {
name: formData.name,
document: formData.document,
customer_id: formData.customer_id,
number: formData.number,
cvv: formData.cvv,
month: formData.month,
year: formData.year,
};
window.getTokenCard(publicKey, dataCard, formData.installments, (data: any) => {
console.log('resposta:', data);
if (data.token) {
setTokenData({
token: data.token,
brand: data.brand,
bin: data.bin,
});
alert('Token obtido com sucesso!');
} else {
alert(`ERRO: ${data.msgError}`);
}
});
};
return (
<form onSubmit={handleSubmit} ref={formRef}>
{
<input type="hidden" name="token" value={tokenData.token} />
<input type="hidden" name="brand" value={tokenData.brand} />
<input type="hidden" name="bin" value={tokenData.bin} />
<button type="submit">Enviar</button>
</form>
);
};
export default DomPagamentoForm;
Opção 2 - Implementar através de atributos nos campos do seu formulário:
Inclua nos campos do seu formulário nossos atributos data-dompag com seus respectivos valores:
| Atributo | Campo no formulário | Exemplo de valor do campo |
|---|---|---|
| data-dompag="number" | Número do cartão de crédito | 4871 2689 6999 1111 |
| data-dompag="verification_value" | Código de segurança (CVV) | 124 |
| data-dompag="full_name" | Nome do titular do cartão | João da Silva |
| data-dompag="expiration" | Data de expiração do cartão | 12/30 |
| data-dompag="document" | Documento do titular (CPF) | 111111111-11 |
| data-dompag="birthdate" | Data de nascimento do titular | 01/01/2000 |
| data-dompag="installments" | Quantidade de parcelas da compra | 12 |
| data-dompag="token-card" | Token retornado pelo SDK | lMIS2rqea7p+AB6n0LNfWAMO4CccY1FKxygShPSWCfl |
| data-dompag="brand-card" | Bandeira do cartão retornada pelo SDK (pode ser nula) | Visa |
| data-dompag="bin-card" | 6 primeiros e 4 últimos digitos do cartão retornados pelo SDK | 487126**1111 |
| data-dompag="customer_id" | Id do consumidor se desejar criar um token da carteira | 04a26aa2-e781-472e-88d0-6e958ed972g3 |
| data-dompag="finger_print" | Impressão digital do dispositivo do comprador | armor.1a145e9ff849dab2e15dfe02a2... |
Exemplo de uso:
<form id="payment-form" action="#" method="POST">
<div>
<div>
<input placeholder="Número do Cartão" type="text" data-dompag="number" />
</div>
<div>
<input placeholder="CVV" type="text" data-dompag="verification_value" />
</div>
<div>
<input placeholder="Titular do Cartão" type="text" data-dompag="full_name" />
</div>
<div>
<input placeholder="Expiração (MM/AA)" type="text" value="12/30" data-dompag="expiration" />
</div>
<div>
<input placeholder="CPF" type="text" value="" data-dompag="document" />
</div>
<div>
<input placeholder="Nascimento (DD/MM/YYYY)" type="text" value="01/01/2000" />
</div>
<div>
<input placeholder="Celular" type="text" value="" data-dompag="phone"/>
</div>
<div>
<input placeholder="Parcelas" type="number" value="1" data-dompag="installments" />
</div>
<div>
<input type="hidden" id="deviceId" data-dompag="finger_print" />
</div>
</div>
<div class="token-area">
<label for="token">Token do Cartão de Crédito - Enviar para seu Servidor</label>
<input type="text" name="token" id="token" placeholder="Token" size="50" data-dompag="token-card" />
<input type="text" name="brand" id="brand" placeholder="Bandeira" data-dompag="brand-card" />
<input type="text" name="bin" id="bin" placeholder="Bin" size="30" data-dompag="bin-card" />
</div>
<div>
<input type="hidden" value="" data-dompag="customer_id" />
<button type="button" onclick="sendForm()">Salvar</button>
</div>
</form>
<script type="text/javascript" src="https://apiv3.dompagamentos.com.br/js/sdk-3ds-dompagamentos.min.js"></script>
<script>
function sendForm() {
let public_key = '{sua_chave_publica}';
initTokenCard(public_key, 'payment-form', function (data) {
if (data.token) {
document.getElementById('token').value = data.token;
document.getElementById('brand').value = data.brand;
document.getElementById('bin').value = data.bin;
document.getElementById('payment-form').submit();
} else {
alert("ERRO: " + data.msgError);
}
});
}
</script>
Chave Pública
Para executar o script SDK, será necessário fornecer sua chave pública, ela fica disponível através do painel da conta, menu Segurança -> Token para checkout
🧾Etapa 2: Confirmação 3DS
Após a criação da transação com o token, o retorno da API poderá conter:
"three_ds": true – Transação utiliza autenticação 3DS.
"three_ds_challenge": true – O banco emissor exigirá um desafio (ex: confirmação via app ou SMS).
"three_ds_html" – HTML com o formulário do banco, que deve ser incorporado em um iframe.
Importante
Inclua em sua página de pagamento um script que atualize a interface após o desafio 3DS ser concluído.
window.addEventListener("message", (e) => {
if (e.data.status === "COMPLETE") {
window.open("congrats.html");
}
});
🔄 Etapa 3: Verificação do status da transação
Após o desafio 3DS (quando houver), consulte o status da transação para confirmar se foi aprovada ou reprovada.
Veja abaixo a tabela com os possíveis status e suas respectivas descrições.
| Status | Status_detail | Descrição |
|---|---|---|
| approved | accredited | Transação aprovada sem autenticação |
| rejected | cc_rejected_3ds_mandatory | Transação rejeitada sem autenticação. Para conferir os motivos, consulte a lista padrão de status detail |
| pending | pending_challenge | Transação pendente de autenticação ou timeout do Challenge |
| rejected | cc_rejected_3ds_challenge | Transação rejeitada devido a falha no Challenge |
| cancelled | expired | Transação com Challenge cancelada após 24h no status pending |
Teste de integração
Para que seja possível validar pagamentos com 3DS, disponibilizamos um ambiente de testes do tipo sandbox que retorna resultados falsos apenas para simulação e validação da implementação.
Para realizar testes de pagamento em um ambiente sandbox, é necessário utilizar cartões específicos que permitem testar a implementação do Challenge com os fluxos de sucesso e falha. A tabela a seguir apresenta os detalhes desses cartões:
| Cartão | Fluxo | Número | CVV | Vencimento |
|---|---|---|---|---|
| Mastercard | Challenge com sucesso | 5483 9281 6457 4623 | 123 | 11/25 |
| Mastercard | Challenge não autorizado | 5361 9568 0611 7557 | 123 | 11/25 |