# 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](https://www.google.com/search?q=/developer-resources/taxes-regulations%23spain) 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:

1.  **Autenticação Direta**: A autenticação é concluída imediatamente (status: `Authenticated` ou `Attempt`).
2.  **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**.
3.  **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](https://www.google.com/search?q=%23step-4-create-the-payment).
  * **"Pending Challenge"**: Escolha entre `redirect_html_template` ou `acs_redirect_form`. Prossiga para a [Etapa 3B: Validar Autenticação](https://www.google.com/search?q=%23step-3b-validate-authentication) e, em seguida, para a [Etapa 4: Criar o Pagamento](https://www.google.com/search?q=%23step-4-create-the-payment).
  * **"Pending Enrollment Continue"**: Prossiga para a [Etapa 3C: Continuar Enrollment](https://www.google.com/search?q=%23step-3c-continue-enrollment).

## Etapas de Implementação

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

1.  Solicite um access token usando suas credenciais da API.
2.  Tokenize as informações do cartão usando o [endpoint de token](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/cards/POST/dpm/cofre-gw-proxy/v1/tokens/card).

### Etapa 2: Iniciar Enrollment

Chame o endpoint [3DS - Init Authentication](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/payments/post/dpm/security-gwproxy/v2/enrolments-initial).

```json
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):**

```json
{
  "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](https://www.google.com/search?q=%23step-4-create-the-payment).

#### 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:**

```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):

```javascript
// 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:**

```html
<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](https://www.google.com/search?q=%23step-3c-continue-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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/payments/post/dpm/security-gwproxy/v2/validations).

**Exemplo de requisição:**

```json
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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/payments/post/dpm/security-gwproxy/v2/enrolments-continue).

**Exemplo de resposta (status Pending Challenge):**

```json
{
  "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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/payments/post/dpm/payments-gwproxy/v2/payments). 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](https://predocs.globalgetnet.com/en/articles?article=taxes-and-regulations) para obter mais informações.

**Exemplo de requisição:**

```json
curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer '\
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --data '{
    "order_id": "123order",
    "data": {
      "amount": 118708,
      "currency": "CLP",
      "payment": {
        "payment_method": "CREDIT_AUTHORIZATION",
        "xid": "VDdnR0kyU1g4ZXlxMkhWTlp0VnA=",
        "eci": "24",
        "ds_trans_id": "f7e5f76e-6388-43e6-b8cd-49b251a1f89c",
        "card": { ... }
      }
    }
  }'
```

## Próximos Passos

  * [Cancelamentos e Reembolsos](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/payments/post/dpm/payments-gwproxy/v2/payments)
  * [Capturar uma Transação Pré-Autorizada](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/payments/post/dpm/payments-gwproxy/v2/payments)