# Guia Rápido: Criar um Pagamento

Este guia ajuda você a criar sua primeira transação de pagamento bem-sucedida. Você vai se autenticar na API, enviar uma requisição de pagamento e verificar o status da transação.

## Passo 1: Obter uma credencial

Assim que sua conta for ativada, você receberá sua Test Account e as chaves da API que permitirão iniciar a integração.

<Callout type="warning">

O Passo 1 está disponível apenas para 
**Argentina**, **Chile** e **México**.

</Callout>

Para gerar a credencial, no Getnet Merchant Portal, siga as etapas abaixo:

<Callout type="warning">

Todos os produtos contratados serão exibidos nesta tela e a geração de credenciais será habilitada por solução.

</Callout>

![](https://static-devportal-ux.sensedia-eng.com/Pagonxt/staging/documentations/wbc-credentials-1770648262379-rrshzhvs.gif)

1. Selecione **Digital Products**.
2. No menu suspenso, selecione **Integrations**.
3. Clique em **Generate credentials**.
4. No aviso em pop-up, clique em **Generate credentials**.
5. Sua credencial foi criada. Salve sua credencial, pois não será possível exibi-la novamente.
6. Copie e cole o Client ID.
7. Copie e cole o Client Secret.
8. Clique em **Continue**.

<Callout type="info">

Se você perder as chaves, repita o passo a passo para gerar uma nova.

</Callout>

## Passo 2: Recuperando o Access token

Você deve primeiro obter um **access token**. Isso requer seu **Client ID** e **Client Secret**.
Para recuperar suas credenciais, acesse o documento [Credentials](https://docs.globalgetnet.com/pt/products/online-payments/web-checkout?doc=credential-wbc) e siga as etapas.

<Callout type="info">

Existem outras requisições que podem ser feitas para recuperar um access token. Consulte o documento [Authentication](/pt/web-checkout/first-steps-wbc/authentication-token-wbc) para saber mais sobre essas requisições.

</Callout>

Exemplo de requisição

```json
curl --location '{{host_getnet_api}}/authentication/oauth2/access_token' 
--header 'Content-Type: application/x-www-form-urlencoded' 
--header 'Accept: application/json' 
--data-urlencode 'grant_type=client_credentials' 
--data-urlencode 'client_id={{PUT_YOUR_CLIENT_ID_HERE}}' 
--data-urlencode 'client_secret={{PUT_YOUR_CLIENT_SECRET_HERE}}'
```

Exemplo de resposta

```json
{
    "access_token": "eyJ0eXAiOiJKV1QiLCJraWQiOiI1amhLMy9xK0ZpK0tTRkIrRUwwN3VhMFYwdGM9Ii...",
    "scope": "name-scope:r",
    "token_type": "Bearer",
    "expires_in": 3599
}
```

## Passo 3: Criar um Payment Intent

Assim que você obtiver um **access token**, crie um **payment intent** sempre que o cliente iniciar o processo de checkout ao clicar no botão de pagamento da sua loja virtual. 

O payment intent permite que o frontend carregue a interface do Checkout e prossiga com a transação de forma segura.

O uso de um payment intent garante que o valor cobrado do cliente seja exatamente o especificado durante sua criação. Como o payment intent é gerado no backend, o valor definido permanece consistente durante todo o fluxo de pagamento e não pode ser modificado — acidental ou maliciosamente — pelo frontend.

Para criar um payment intent, envie uma requisição **HTTP POST** incluindo o `access_token` obtido anteriormente no cabeçalho **Authorization**. Uma resposta bem-sucedida retorna o **payment intent ID** e a **redirect URL**, necessários para a implementação no frontend, dependendo do método de integração escolhido.

Para mais detalhes, consulte a [Referência da API](https://docs.globalgetnet.com/en/products/online-payments/web-checkout/swagger#tag/payment-intent/POST/payment-intent)

Endpoint|
---|
`POST /payment-intent`|

**Campos obrigatórios**
| Campo | Tipo | Descrição | Exemplo |
|---|---|---|---|
|`payment.currency`| String | Código da moeda. | `BRL`|
|`payment.amount`| Integer | Valor da compra em formato inteiro, em que os 2 últimos dígitos representam os centavos. Para países em que centavos não se aplicam, preencha o valor com 2 zeros à direita. |`92500`|
|`customer.customer_id`| String | Recomendamos usar o número do documento do cliente, apenas letras e números, sem caracteres especiais, separadores ou espaços.| `12345678912`  |
|`customer.first_name`| String | Primeiro nome do cliente.| `John`  |
|`customer.last_name`| String | Sobrenome do cliente.| `Doe Smith`  |
|`customer.name`| String | Nome completo do cliente.| `John Doe Smith`  |
|`customer.email`| String | Endereço de e-mail do cliente.| `customer@email.com.br`  |
|`customer.document_type`| String | Tipo de documento usado para identificar o cliente. Consulte a tabela **Valores dos Campos** para ver os valores aceitos. | `CPF`  |
|`customer.document_number`| String | Número do documento usado para identificar o cliente.| `12345678912`  |
|`customer.billing_address.street`| String | Nome de uma rua.| `Av. Brasil`  |
|`customer.billing_address.number`| String | Número que identifica a posição de um imóvel na rua.| `1000`  |
|`customer.billing_address.country`| String | Código do país. Consulte a tabela **Valores dos Campos** para ver os valores aceitos.| `BR` |
|`customer.billing_address.postal_code`| String | CEP ou código postal.| `90230060`  |

**Campos condicionais (apenas Uruguai)**
| Campo | Tipo | Descrição | Exemplo |
|---|---|---|---|
|`additional_data`| Object | Dados adicionais para regulamentações regionais e exigências fiscais. Obrigatório para o Uruguai. | --- |
|`additional_data.rates`| Array | Alíquotas de imposto aplicadas à transação.| --- |
|`additional_data.rates.key`| String | (Apenas Uruguai). Tipo de imposto ou alíquota aplicada. | `IVA`|
|`additional_data.rates.value`| Number | (Apenas Uruguai). Valor do imposto em formato inteiro (centavos)| `123`|
|`additional_data.regional_regulation_code`| String | (Apenas Uruguai). Código fiscal ou regulatório regional exigido pelas autoridades locais. Usado para envios ao SEP no Uruguai. | `17934`|

**Campos opcionais**
| Campo | Tipo | Descrição | Exemplo |
|---|---|---|---|
|`configurations`| Object | Configurações adicionais para o payment intent | --- |
|`configurations.3ds`| Boolean | Controla a autenticação 3D Secure. | `true` ou `false`|
|`configurations.preauthorization`| Boolean | Indica se o pagamento é uma pré-autorização. | `true` ou `false`|
|`configurations.card_verification`| Boolean | Indica se este é um fluxo de verificação de cartão. | `true` ou `false`|
|`configurations.success_url`| String | URL de redirecionamento em caso de pagamento bem-sucedido. |`https://www.mystore.com/checkout/success`|
|`configurations.error_url`| String | URL de redirecionamento em caso de erro durante o pagamento. |`https://www.mystore.com/checkout/error`|
|`expires_at`| String | Expiração do payment intent. | `3d4h15m`|

**Valores dos Campos**
| Campo         | Argentina |       Brasil                | Chile |       Espanha              | México | Uruguai         |
|:-------------:|:---------:|:---------------------------:|:-----:|:--------------------------:|:------:|:---------------:|
|`currency`     |   `ARS`   |               `BRL`         | `CLP` |  `EUR`                     |  `MXN` | `UYU` ou  `USD` |
|`document_type`|   `DNI`   | `CPF`, `CNPJ` ou `passport` | `RUT` | `DNI`, `INE` ou `passport` |  `RFC` |     `uyci`      |
|`country`      |    `AR`   |             `BR`            |  `CH` |             `ES`           |  `MX`  |      `UY`       |
|`key`          |    -      |             -               |   -   |             -              |    -   |       `IVA`     |

#### Regras de preenchimento dos campos:

* O campo `expires_at` aceita um valor de duração (por exemplo, 15m, 2h, 7d ou 1d12h30m). Essa duração é aplicada independentemente do fuso horário do estabelecimento. O timestamp de expiração retornado pela API é sempre formatado em GMT+0 (UTC). Se **nenhum valor** for informado, o payment intent **não expira**.
* Quando `success_url` e `error_url` são informados na requisição do payment intent, eles substituem o valor configurado na configuração técnica do estabelecimento.
* **Uruguai**: Estabelecimentos podem criar payment intents em UYU (peso uruguaio) ou USD. Ao pagar em UYU, o objeto `additional_data` é obrigatório e deve incluir `additional_data.rates.key` com a chave de alíquota **IVA** e o `regional_regulation_code` para conformidade com o SEP.
* **Argentina**: `card_verification` e `preauthorization` **não estão disponíveis** para a Argentina.

**Exemplo de requisição**

```json
{
  "mode": "instant",
  "order_id": "ORDER_UY_97531",
  "configurations": {
    "3ds": true,
    "preauthorization": false,
    "card_verification": false,
    "success_url": "https://www.mystore.com/checkout/success",
    "error_url": "https://www.mystore.com/checkout/error"
  },
  "payment": {
    "currency": "UYU",
    "amount": 120000
  },
  "product": [
    {
      "product_type": "service",
      "title": "Curso de inglés online",
      "description": "Curso completo de 6 meses",
      "value": 120000,
      "quantity": 1
    }
  ],
  "customer": {
    "customer_id": "customer_uy_005",
    "first_name": "Laura",
    "last_name": "Fernández Rodríguez",
    "name": "Laura Fernández Rodríguez",
    "email": "laura.fernandez@example.com.uy",
    "document_type": "ci",
    "document_number": "45678912",
    "phone_number": "59899123456",
    "gender": "Female",
    "checked_email": true,
    "billing_address": {
      "street": "Av. 18 de Julio",
      "number": "1234",
      "complement": "Apto 601",
      "district": "Centro",
      "city": "Montevideo",
      "state": "Montevideo",
      "country": "UY",
      "postal_code": "11200",
      "reference": "Entre Río Branco y Convención"
    }
  },
  "shipping": {
    "first_name": "Laura",
    "last_name": "Fernández Rodríguez",
    "name": "Laura Fernández Rodríguez",
    "phone_number": "59899123456",
    "shipping_amount": 0,
    "address": {
      "street": "Av. 18 de Julio",
      "number": "1234",
      "complement": "Apto 601",
      "district": "Centro",
      "city": "Montevideo",
      "state": "Montevideo",
      "country": "UY",
      "postal_code": "11200",
      "reference": "Entre Río Branco y Convención"
    }
  },
  "pickup_store": false,
  "shipping_method": "UES",
  "soft_descriptor": "Tienda UY",
  "additional_data": {
    "rates": [
      {
        "key": "Iva",
        "value": 22
      }
    ],
    "regional_regulation_code": ["17934"]
  },
  "expires_at": "1h"
}
```

Exemplo de resposta
```json
{
  "payment_intent_id": "f6ee8bc7-229d-4d9d-bced-7dd2371a1f57",
  "trade_name": "GetNet Store",
  "redirect_url": "https://www.globalgetnet.com/hosted-web-checkout/eyJraWQiOiJQQUdPTlhUL..."
}
```

## Passo 4: Integração do frontend

Assim que a integração do seu backend estiver concluída, a criação bem-sucedida de um **payment intent** retorna duas propriedades principais necessárias (`redirect_url` e `payment_intent_id`) para integrar o Web Checkout da Getnet ao seu frontend. 

A propriedade que você usa depende do formato de integração escolhido, que pode ser implementado em JavaScript ou React.

- Para o Web Checkout do tipo **Redirect** (hospedado pela Getnet), use a URL fornecida na propriedade `redirect_url` para abrir uma nova página para o comprador.  
- Para opções de Web Checkout que usam os formatos **Iframe** ou **Lightbox**, extraia o `payment_intent_id` da resposta e siga as etapas correspondentes para incorporar a interface do Checkout na página de pagamento da sua loja virtual.

### Importe o loader da Getnet

O loader é responsável por inicializar a aplicação segura do Checkout da Getnet. Ele deve ser chamado **depois que um payment intent for criado**, para permitir que o cliente insira os dados de pagamento com segurança e prossiga com a transação.

Para consumir as APIs, use os seguintes valores de DNS para `host_getnet_web`:

* [**https://www.pre.globalgetnet.com**](https://www.pre.globalgetnet.com) (ambiente de homologação)
* [**https://www.globalgetnet.com**](https://www.globalgetnet.com) (ambiente de produção)

Em seguida, adicione o seguinte código:

Para **JavaScript**:
```json
<script src="${host_getnet_web}/digital-checkout/loader.js" />
```

Para **React**:
```json
useEffect(() => {
const script = document.createElement("script");
script.src = "${host_getnet_web}/digital-checkout/loader.js";
script.async = true; 
script.setAttribute("data-testid", "digital-checkout");
script.setAttribute("id", "digital-checkout");
document.body.appendChild(script);
}, []);
```

### Adicione o script de checkout

O script de checkout conecta o loader ao usuário e também permite selecionar a opção de integração que melhor atende às suas necessidades.

Para isso, adicione o código a seguir e substitua o valor de `paymentIntentId` pelo `payment_intent_id` recebido anteriormente. Modifique o valor de `checkoutType` para `lightbox` ou `iframe`, dependendo da sua seleção:

Para **JavaScript**:
```json
<script> 
const config = { "paymentIntentId": ${payment_intent_id}, "checkoutType": "lightbox" }; 
const checkoutButton = () => { loader.init(config) }; 
</script>
```

Para **React**:
```json
useEffect(() => { ... 
const config = { paymentIntentId: ${payment_intent_id}, checkoutType: "lightbox" };
}, []);
```

### Adicione o botão de checkout

O botão é responsável por executar o script de checkout mostrado na etapa anterior. Adicione o seguinte código ao seu HTML:

Para **JavaScript**:
```json
<button onclick="checkoutButton()"> Go to Payment </button>
```

Se você estiver usando **React**, nesta etapa você precisa iniciar o loader da Getnet:

```json
useEffect(() => { ...
window.loader.init(config);
}, []);
```
Este será o código final para **React**:

```json
useEffect(() => { 
const script = document.createElement("script"); 
script.src = "${host_getnet_web}/digital-checkout/loader.js"; 
script.async = true; 
script.setAttribute("data-testid", "digital-checkout"); 
script.setAttribute("id", "digital-checkout"); 
document.body.appendChild(script);
const config = { paymentIntentId: ${payment_intent_id}, checkoutType: "lightbox" };
window.loader.init(config);
}, []);
```

## Altere a posição do iFrame

Se você escolher o formato **iFrame** para sua integração de checkout, o iFrame é inserido por padrão como o último elemento da página. Você pode ajustar sua posição manipulando o elemento no DOM para atender melhor ao seu layout e aos requisitos de design.

O exemplo abaixo mostra como criar o iFrame com um identificador e manipulá-lo no DOM.

JavaScript
```json
<div id="iframe-section"></div>

<script>
const config = {
    "paymentIntentId": "PAYMENT_INTENT_ID_HERE",
    "checkoutType": "iframe"
};
const checkoutButton = () => {
    loader.init(config);

    const iframeSection = document.getElementById("iframe-section");
    const iframe = document.querySelector("iframe");
    iframeSection.appendChild(iframe);
};
</script>
```

## Fluxo da Transação

Siga as etapas para processar um pagamento.

1. O processo de pagamento começa quando o comprador clica no botão de pagamento designado.
2. A tela de checkout exibe o valor da intenção de pagamento, além dos métodos de pagamento disponíveis, de acordo com a configuração do Merchant Portal ou da API.
3. Para pagamentos feitos com cartão de crédito ou débito, o comprador insere os dados do cartão. Se a bandeira e o tipo de cartão fornecidos oferecerem suporte a pagamentos parcelados, uma consulta transparente é enviada à API de Installments da Getnet para recuperar as opções de parcelamento disponíveis para esse checkout.
4. Os parcelamentos oferecidos se baseiam nos acordos contratados com a Getnet e nas pré-configurações feitas no portal do estabelecimento ou nas configurações da API, onde você determina se oferece parcelamento com ou sem juros e define um limite no número de parcelas.
5. Ao clicar no botão, o comprador inicia o processo de autorização do pagamento.

![](https://static-devportal-ux.sensedia-eng.com/Pagonxt/production/images/webcheckout-payment-1784580432558-3q7u6fh8.gif)

### Processo de Autorização de Pagamento – Web Checkout da Getnet

O processo de autorização de cada pagamento envolve diversas etapas críticas, desenvolvidas para garantir a **segurança, a integridade e a conformidade** de cada transação:

1. **Captura de Device Fingerprint**: Coleta informações do dispositivo para apoiar a análise de fraude.  
2. **Autenticação 3D Secure (3DS)**: Aplicada quando suportada pelo país de origem, pela bandeira, pelo emissor e pelo tipo do cartão.  
3. **Tokenização do Cartão**: Em conformidade com os padrões **PCI DSS**, dados sensíveis do cartão não são transmitidos nem armazenados durante o processo de autorização. Em vez disso, o cartão é tokenizado no início do fluxo, e apenas o token gerado é transmitido entre as APIs internas.  
4. **Validação do Método de Pagamento**: Verifica se o método de pagamento selecionado, a bandeira do cartão e o plano de parcelamento são compatíveis com os produtos e serviços contratados pelo estabelecimento.  
5. **Análise de Fraude**: Realizada por meio da API Antifraude da Getnet, com base em regras definidas pela equipe responsável da Getnet em cada país.  
6. **Autorização de Pagamento**: A etapa final, em que a transação é autorizada por meio da comunicação com as instituições financeiras apropriadas.  

Ao final desse processo, a aplicação cliente do Web Checkout recebe uma resposta indicando **Sucesso** ou **Falha**:

- **Falha**: Se o pagamento for recusado ou algum problema for detectado durante o processo, uma mensagem de erro é exibida ao comprador. Além disso, um **webhook ou notificação** é enviado contendo os detalhes do pagamento e o status da transação.  
- **Sucesso**: Se o pagamento for autorizado, uma mensagem de confirmação é exibida ao comprador. Um **webhook ou notificação** também é enviado com os dados de autorização e o status da transação. Nessa etapa, o **payment_id** é gerado, que pode ser usado em **operações de cancelamento ou reembolso** (consulte a documentação *Modifying Payments* para mais detalhes).

Exemplo de um payload de transação **AUTHORIZED**:

```json
    {
  "payment_intent_id": "1f9f47ed-65cc-4fbf-a407-0f17df9a2e2c",
  "checkout_id": "5ab15d1e-ea8b-4560-84d2-fb3d02179537",
  "order_id": "YOUR_ORDER_ID",
  "mode": "instant",
  "seller": {
    "id": "716d899e-9091-4577-a12f-8a77ec4d1e0b",
    "trade_name": "GetNet Shop",
    "merchant_document": "00000000000",
    "settings": {
      "notification_url_configured": true
    }
  },
  "customer": {
    "customer_id": "c129d793-d204-4610-8819-b8fb720a8552",
    "first_name": "John",
    "last_name": "Doe",
    "name": "John Doe",
    "email": "johndoe@emailtest.com",
    "document_type": "dni",
    "document_number": "1111111111111",
    "checked_email": false,
    "billing_address": {
      "street": "South Rockledge St",
      "number": "00",
      "complement": "Rockville",
      "country": "AR",
      "postal_code": "00000000"
    }
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "name": "John Doe",
    "address": {
      "street": "South Rockledge St",
      "number": "00",
      "complement": "Rockville",
      "country": "AR",
      "postal_code": "00000000"
    }
  },
  "payment": {
    "method": "credit",
    "amount": 14100,
    "currency": "ARS",
    "installment": {
      "quote_id": "f054ce63-0475-406f-8eca-25aea5dae6a8",
      "schema": "plan_name",
      "type": "with_interest",
      "number": 6
    },
    "payment_method": {
      "token_id": "e327bae6-286e-4920-addb-5f4b10315b4e"
    },
    "result": {
      "payment_id": "3a76acae-d9c0-421c-91e0-cf5ce8aca098",
      "status": "Authorized",
      "authorization_code": "999999",
      "transaction_datetime": "2024-01-01T12:00:00.000Z"
    }
  },
  "pickup_store": false,
  "product": [
    {
      "product_type": "cash_carry",
      "title": "Look Fashion Leather Boot",
      "value": 5300,
      "quantity": 1
    },
    {
      "product_type": "cash_carry",
      "title": "Look Fashion Blazer",
      "value": 8800,
      "quantity": 1
    }
  ],
  "frontend": {
    "link": "https://www.globalgetnet.com/",
    "time_page": 39,
    "sales_channel": "WEB",
    "application_version": "0.0.0",
    "card_pasted": true,
    "ip": "000.000.00.00",
    "timezone": "America/Sao_Paulo",
    "locale": "en-US"
  },
  "created_at": "2024-01-01T12:00:00.000Z",
  "updated_at": "2024-01-01T12:00:00.000Z"
}
```

Exemplo de um payload de transação **DENIED**:

```json
    {
  "payment_intent_id": "1f9f47ed-65cc-4fbf-a407-0f17df9a2e2c",
  "checkout_id": "5ab15d1e-ea8b-4560-84d2-fb3d02179537",
  "order_id": "YOUR_ORDER_ID",
  "mode": "instant",
  "seller": {
    "id": "716d899e-9091-4577-a12f-8a77ec4d1e0b",
    "trade_name": "GetNet Shop",
    "merchant_document": "00000000000",
    "settings": {
      "notification_url_configured": true
    }
  },
  "customer": {
    "customer_id": "c129d793-d204-4610-8819-b8fb720a8552",
    "first_name": "John",
    "last_name": "Doe",
    "name": "John Doe",
    "email": "johndoe@emailtest.com",
    "document_type": "dni",
    "document_number": "1111111111111",
    "checked_email": false,
    "billing_address": {
      "street": "South Rockledge St",
      "number": "00",
      "complement": "Rockville",
      "country": "AR",
      "postal_code": "00000000"
    }
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "name": "John Doe",
    "address": {
      "street": "South Rockledge St",
      "number": "00",
      "complement": "Rockville",
      "country": "AR",
      "postal_code": "00000000"
    }
  },
  "payment": {
    "method": "credit",
    "amount": 14100,
    "currency": "ARS",
    "installment": {
      "quote_id": "f054ce63-0475-406f-8eca-25aea5dae6a8",
      "schema": "plan_name",
      "type": "with_interest",
      "number": 6
    },
    "payment_method": {
      "token_id": "e327bae6-286e-4920-addb-5f4b10315b4e"
    },
    "result": {
      "payment_id": "3a76acae-d9c0-421c-91e0-cf5ce8aca098",
      "status": "Denied",
      "return_message": "Card not accepted for this operation",
      "transaction_datetime": "2024-01-01T12:00:00.000Z"
    }
  },
  "pickup_store": false,
  "product": [
    {
      "product_type": "cash_carry",
      "title": "Look Fashion Leather Boot",
      "value": 5300,
      "quantity": 1
    },
    {
      "product_type": "cash_carry",
      "title": "Look Fashion Blazer",
      "value": 8800,
      "quantity": 1
    }
  ],
  "frontend": {
    "link": "https://www.globalgetnet.com/",
    "time_page": 39,
    "sales_channel": "WEB",
    "application_version": "0.0.0",
    "card_pasted": true,
    "ip": "000.000.00.00",
    "timezone": "America/Sao_Paulo",
    "locale": "en-US"
  },
  "created_at": "2024-01-01T12:00:00.000Z",
  "updated_at": "2024-01-01T12:00:00.000Z"
}
```