Criar um Pagamento Autenticado com 3DS

Adicione uma camada extra de segurança às suas transações e reduza o risco de fraude implementando a autenticação 3D Secure (3DS). Este guia demonstra como usar a GetNet Global API para verificar a identidade de um portador do cartão antes de processar o seu pagamento.

Requisitos

Antes de iniciar a integração, conclua o seguinte:

Credenciais da API: Entre em contato com a Equipe de Suporte à Integração para obter o seu client_id e client_secret.
Access Token: Gere um token Bearer usando suas credenciais por meio do endpoint de Access Token.
Suporte à Bandeira do Cartão: Verifique se a bandeira do cartão é Mastercard ou Visa. Atualmente, elas são suportadas para 3DS na Argentina, Chile, México, Espanha, Brasil e Uruguai.

Obrigatório para a Europa: As transações dentro do Espaço Econômico Europeu (EEE) exigem autenticação 3DS para cumprir a PSD2 e a Autenticação Forte do Cliente (SCA). Consulte a documentação de Taxes and Regulations para obter detalhes sobre isenções.

Entendendo o Processo de Autenticação 3DS

O emissor do cartão determina dinamicamente o fluxo do 3DS com base na avaliação de risco, na bandeira do cartão e nas capacidades do emissor. Após você iniciar o Enrollment, a API retorna um campo status que dita o seu próximo passo.

Lide com os três cenários possíveis:

Autenticação Direta: A autenticação é concluída imediatamente (status: Authenticated ou Attempt).
Challenge Exigido: A verificação do cliente é necessária (status: Pending Challenge). Escolha entre renderizar um template HTML ou executar um POST manual usando os dados do ACS Direct Form.
Pending Enrollment Continue: Processamento adicional é necessário (status: Pending Enrollment Continue), o que pode eventualmente resultar em autenticação ou em um Challenge.

Referência Rápida: Fluxo de Decisão

Siga esta lógica de decisão com base no status retornado pela API:

Após a Etapa 2 (Iniciar Enrollment):

“Authenticated” ou “Attempt”: Prossiga para a Etapa 4: Criar o Pagamento.
“Pending Challenge”: Escolha entre redirect_html_template ou acs_redirect_form. Prossiga para a Etapa 3B: Validar Autenticação e, em seguida, para a Etapa 4: Criar o Pagamento.
“Pending Enrollment Continue”: Prossiga para a Etapa 3C: Continuar Enrollment.

Etapas de Implementação

Etapa 1: Obter Access Token e Tokenizar o Cartão

Solicite um access token usando suas credenciais da API.
Tokenize as informações do cartão usando o endpoint de token.

Etapa 2: Iniciar Enrollment

Chame o endpoint 3DS - Init Authentication.

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/security-gwproxy/v2/enrolments-initial \
  --header 'authorization: Bearer ' \
  --header 'content-type: application/json' \
  --data '{
  "currency": "CLP",
  "md": "NmQyZTQzODAtZDhhMy00Y2NiLTkxMzgtYzI4OTE4MjgxOGE0",
  "term_url": "123",
  "amount": 1,
  "payment_method": {
    "expiration_month": "05",
    "expiration_year": "25",
    "security_code": "282",
    "number_token": "4292b573ea94b257dcb132afe242b4a15c9866d16e2d4d64d8e571c877af0540c3946b8bddaf37c2c75a1810863fc6b0fe0e841ebbc752c1d23ccfb5fdaac3d1"
  },
  "description": "TEST",
  "operation": "CREDIT",
  "extra_fields": {
    "billing_address": {
      "street": "Av. Brasil",
      "number": "1000",
      "complement": "Sala 1",
      "district": "São Geraldo",
      "city": "Porto Alegre",
      "state": "RS",
      "country": "BR",
      "postal_code": "90230060",
      "reference": "Near the hospital"
    },
    "shipping_address": {
      "street": "Av. Brasil",
      "number": "1000",
      "complement": "Sala 1",
      "district": "São Geraldo",
      "city": "Porto Alegre",
      "state": "RS",
      "country": "BR",
      "postal_code": "90230060",
      "reference": "Near the hospital"
    }
  }
}'

Exemplo de resposta (Pending Challenge):

{
  "transaction_id": "84c05897-fbf1-4a91-90e8-d292a0fda1c8",
  "status": "Pending Challenge",
  "protocol": "3DS2.3.1",
  "redirect_html_template": "<html>...</html>",
  "acs_redirect_form": {
    "action_url": "https://3ds-acs.test.modirum.com/mdpayacs/creq;token=368800071.1773147207.lksz3Q5MLGPuP5RsNmoU_8831PDCBLY_ABFB5xq0wtc",
    "method": "POST",
    "creq": "ewogICAgImFjc1RyYW5zSUQiOiAiNjVhMWUxN2MtZWVmYS00NGU1LTgyMDEtMDI4MjM5ZTVmOTA3IiwKICAgICJjaGFsbGVuZ2VXaW5kb3dTaXplIjogIjAzIiwKICAgICJtZXNzYWdlVHlwZSI6ICJDUmVxIiwKICAgICJtZXNzYWdlVmVyc2lvbiI6ICIyLjMuMSIsCiAgICAidGhyZWVEU1NlcnZlclRyYW5zSUQiOiAiZjI0ZmZhMWItMWY5MC01ZjMxLTgwMDAtMDAwMDAyYmY4Yjc3Igp9",
    "threeDSSessionData": "NmQyZTQzODAtZDhhMy00Y2NiLTkxMzgtYzI4OTE4MjgxOGE0"
  }
}

Etapa 3: Verificar o Status e Seguir o Cenário Apropriado

Status: `Authenticated` ou `Attempt`

Extraia os dados de autenticação (xid, eci, cavv, ds_trans_id) e prossiga para a Etapa 4: Criar o Pagamento.

Status: `Pending Challenge`

Redirecione o cliente para o seu banco para autenticação. Selecione um dos seguintes métodos de redirecionamento:

Opção A: Template HTML Extraia e renderize o redirect_html_template diretamente em sua aplicação.

Exemplo de renderização do template HTML:

<div id="challenge-container"></div>
<script>
// Receive the redirect_html_template from your backend
const redirectHtmlTemplate = response.redirect_html_template;
// Inject the HTML into your page
document.getElementById('challenge-container').innerHTML = redirectHtmlTemplate;
// The template contains a form that will automatically submit and redirect
// the customer to their bank's authentication page
</script>

Alternativamente, você pode renderizá-lo no lado do servidor (server-side):

// Node.js/Express example
app.post('/initiate-3ds', async (req, res) => {
  const enrollmentResponse = await fetch('https://api-sbx.globalgetnet.com/dpm/security-gwproxy/v2/enrolments-initial', {
    // ... request configuration
  });
  const data = await enrollmentResponse.json();
  if (data.status === 'Pending Challenge') {
    // Send the HTML template directly to the browser
    res.send(data.redirect_html_template);
  }
});

Opção B: ACS Direct Form Use o objeto acs_redirect_form para executar uma solicitação POST manual no navegador do cliente. Este método é preferível, pois evita scripts de terceiros e permite uma interface de usuário de “Carregamento” personalizada.

Detalhes do POST Obrigatórios:

URL: Use a action_url fornecida na resposta.
Método: POST
Content-Type: application/x-www-form-urlencoded
Corpo (Body): Inclua creq e threeDSSessionData.

Exemplo de redirecionamento POST manual:

<div id="loader">Redirecting to secure bank authentication...</div>

<form id="acs-direct-form" method="POST" action="https://3ds-acs.test.modirum.com/mdpayacs/creq;token=368800071.1773147207.lksz3Q5MLGPuP5RsNmoU_8831PDCBLY_ABFB5xq0wtc">
  <input type="hidden" name="creq" value="ewogICAgImFjc1RyYW5zSUQiOiAiNjVhMWUxN2MtZWVmYS00NGU1LTgyMDEtMDI4MjM5ZTVmOTA3IiwKICAgICJjaGFsbGVuZ2VXaW5kb3dTaXplIjogIjAzIiwKICAgICJtZXNzYWdlVHlwZSI6ICJDUmVxIiwKICAgICJtZXNzYWdlVmVyc2lvbiI6ICIyLjMuMSIsCiAgICAidGhyZWVEU1NlcnZlclRyYW5zSUQiOiAiZjI0ZmZhMWItMWY5MC01ZjMxLTgwMDAtMDAwMDAyYmY4Yjc3Igp9" />
  <input type="hidden" name="threeDSSessionData" value="NmQyZTQzODAtZDhhMy00Y2NiLTkxMzgtYzI4OTE4MjgxOGE0" />
</form>

<script>
  // Programmatically submit the form
  document.getElementById('acs-direct-form').submit();
</script>

Status: `Pending Enrollment Continue`

Você deve chamar o endpoint da Etapa 3C: Continuar Enrollment.

Etapa 3B: Validar Autenticação

Após o cliente concluir o Challenge e retornar ao seu site, capture o token de resposta e chame o endpoint 3DS - Validate authentication.

Exemplo de requisição:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/security-gwproxy/v2/validations \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --data '{
  "transaction_id": "502040201060404060506040",
  "xid": "VDdnR0kyU1g4ZXlxMkhWTlp0VnA=",
  "token": "<cres-token-from-challenge-callback>"
}'

Etapa 3C: Continuar Enrollment

Se o status inicial for Pending Enrollment Continue, chame o endpoint 3DS - Banking Login Authentication Payload.

Exemplo de resposta (status Pending Challenge):

{
  "transaction_id": "84c05897-fbf1-4a91-90e8-d292a0fda1c8",
  "status": "Pending Challenge",
  "protocol": "3DS2.3.1",
  "acs_redirect_form": {
    "action_url": "https://3ds-acs.test.modirum.com/mdpayacs/creq;token=368800071.1773147207.lksz3Q5MLGPuP5RsNmoU_8831PDCBLY_ABFB5xq0wtc",
    "method": "POST",
    "creq": "ewogICAgImFjc1RyYW5zSUQiOiAiNjVhMWUxN2MtZWVmYS00NGU1LTgyMDEtMDI4MjM5ZTVmOTA3IiwKICAgICJjaGFsbGVuZ2VXaW5kb3dTaXplIjogIjAzIiwKICAgICJtZXNzYWdlVHlwZSI6ICJDUmVxIiwKICAgICJtZXNzYWdlVmVyc2lvbiI6ICIyLjMuMSIsCiAgICAidGhyZWVEU1NlcnZlclRyYW5zSUQiOiAiZjI0ZmZhMWItMWY5MC01ZjMxLTgwMDAtMDAwMDAyYmY4Yjc3Igp9",
    "threeDSSessionData": "NmQyZTQzODAtZDhhMy00Y2NiLTkxMzgtYzI4OTE4MjgxOGE0"
  }
}

Etapa 4: Criar o Pagamento

Uma vez que a autenticação for concluída (Authenticated ou Attempt), chame o endpoint Create - Authorize. Inclua os dados de autenticação (xid, eci, cavv, ds_trans_id) no objeto payment.

Requisitos específicos do país: Alguns mercados podem exigir campos obrigatórios adicionais. No Uruguai, você deve incluir um array rates e fornecer um regional_regulation_code. O regional_regulation_code é um array em que cada entrada tem um code e um invoice. O invoice aceita até 9 caracteres alfanuméricos. Recomendamos usar apenas números. Revise a referência de Taxes and Regulations para obter mais informações.