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.

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

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

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

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

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

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 e siga as etapas.

Existem outras requisições que podem ser feitas para recuperar um access token. Consulte o documento Authentication para saber mais sobre essas requisições.

Exemplo de requisição

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

{
    "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

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

{
  "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

{
  "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 (ambiente de homologação)
https://www.globalgetnet.com (ambiente de produção)

Em seguida, adicione o seguinte código:

Para JavaScript:

<script src="${host_getnet_web}/digital-checkout/loader.js" />

Para React:

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:

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

Para React:

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:

<button onclick="checkoutButton()"> Go to Payment </button>

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

useEffect(() => { ...
window.loader.init(config);
}, []);

Este será o código final para React:

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

<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.

O processo de pagamento começa quando o comprador clica no botão de pagamento designado.
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.
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.
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.
Ao clicar no botão, o comprador inicia o processo de autorização do pagamento.

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:

Captura de Device Fingerprint: Coleta informações do dispositivo para apoiar a análise de fraude.
Autenticação 3D Secure (3DS): Aplicada quando suportada pelo país de origem, pela bandeira, pelo emissor e pelo tipo do cartão.
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.
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.
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.
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:

    {
  "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:

    {
  "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"
}