Criar um pagamento pré-autorizado

Este documento se aplica aos seguintes países:

No Web Checkout da Getnet, a pré-autorização permite que o estabelecimento reserve temporariamente um valor no cartão de crédito do cliente durante o processo de pagamento. A transação permanece pendente até que o estabelecimento confirme (capture) o pagamento, momento em que o valor é efetivamente cobrado. Esse mecanismo é útil em cenários em que o valor final da compra pode variar ou precisa ser confirmado posteriormente.

Para entender as regras de cada país, consulte o documento Pré-autorização e disponibilidade.

Como funciona

Use a pré-autorização quando quiser reservar um valor no cartão de crédito do cliente durante o processo de pagamento e confirmá-lo (capturá-lo) depois — útil quando o valor final da compra pode variar ou precisa ser confirmado posteriormente. Características principais:

• Fluxo em duas etapas: a transação é dividida em uma autorização que reserva os fundos e uma captura que os cobra. O valor não é capturado imediatamente.
• Mesma página de Checkout: a experiência do comprador é idêntica à do fluxo de pagamento padrão; apenas o momento da captura é diferente.
• Reservar e depois cobrar: a autorização valida os dados do cartão do cliente e reserva os fundos junto ao emissor do cartão, mas ainda não os transfere.
• Captura ajustável: na captura, o valor pode ser igual ou menor que o valor autorizado.
• Vinculado por payment_id: o payment_id retornado pela autorização identifica a transação em todas as etapas seguintes. Ele é obtido via webhook após a autorização do pagamento.

O fluxo completo envolve o comprador, a página de Checkout e o Getnet WebCheckout / Regional API:

Antes de começar

Antes de seguir as etapas, você precisa:

• Configurar seu Web Checkout via Portal ou via API (dependendo da sua localização).
• Gerar seu token seguindo o documento de Authentication.

Payment intent com pré-autorização

A página de Checkout é a mesma do fluxo de pagamento padrão, porém o valor não é capturado imediatamente, já que a transação é realizada como uma pré-autorização.

Para concluir a cobrança, o estabelecimento deve obter o payment_id enviado via webhook, após a autorização do pagamento, e usar os endpoints de captura e ajuste de pré-autorização da Regional API para capturar ou modificar o valor previamente autorizado.

Para passar pela pré-autorização, estes parâmetros devem ser enviados no payment intent.

Campos obrigatórios

O bloco de código a seguir mostra os campos que devem ser enviados no endpoint de payment intent.

"configurations": {
        "preauthorization": true,
        "card_verification": false,
        "3ds": false
    }

Argentina: card_verification e preauthorization não estão disponíveis para a Argentina.

Passo 1: Autorizar o pagamento

Um pagamento em duas etapas começa com a autorização. Essa etapa valida os dados de pagamento do cliente e reserva os fundos junto ao emissor do cartão, mas ainda não os transfere. Use o endpoint Create - Authorize para iniciar a transação.

Alguns países e bandeiras de cartão impõem limites específicos de pré-autorização, regras de ajuste e janelas de captura. Consulte a referência de pré-autorização para os requisitos de cada país.

Para o processo em duas etapas, você deve definir o atributo data.payment.payment_method na sua requisição como CREDIT_PRE_AUTHORIZATION. Isso garante que os fundos sejam apenas reservados, e não capturados imediatamente. A tabela abaixo lista os campos mínimos que você precisa enviar:

Ao final de uma autorização bem-sucedida, você recebe um payment_id, usado para identificar essa transação na próxima etapa.

O bloco de código a seguir mostra um exemplo de requisição e resposta para autorizar um pagamento:

Exemplo de requisição:

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' \
  --header 'x-transaction-channel-entry: XX' \
  --data '{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "order_id": "order123",
  "data": {
    "amount": 118708,
    "currency": "BRL",
    "customer_id": "test",
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "document_type": "CPF",
      "document_number": "12345678900",
      "phone_number": "+5511999999999",
      "billing_address": {
        "street": "Av. Paulista",
        "number": "1000",
        "complement": "Apto 101",
        "district": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR",
        "postal_code": "01310-100"
      }
    },
    "payment": {
      "payment_method": "CREDIT_PRE_AUTHORIZATION",
      "save_card_data": false,
      "transaction_type": "FULL",
      "number_installments": 1,
      "soft_descriptor": "LOJA*TESTE*COMPRA-123",
      "dynamic_mcc": 1799,
      "card": {
        "number": "5155901222260000",
        "expiration_month": "05",
        "expiration_year": "25",
        "cardholder_name": "CARD HOLDER",
        "security_code": "282"
      }
    },
    "additional_data": {
      "device": {
        "ip_address": "192.168.1.1",
        "device_id": "63c7f8ee-51a6-470d-bb76-ef762b62bfb7",
        "finger_print": "1a2b3c4d5e6f7g8h9i0j"
      }
    }
  }
}'

Exemplo de resposta

{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "payment_id": "d36887d0-53ec-4c36-b731-9bbeca18fcd2",
  "order_id": "order123",
  "amount": 118708,
  "currency": "BRL",
  "status": "AUTHORIZED",
  "payment_method": "CREDIT_PRE_AUTHORIZATION",
  "received_at": "2025-08-12T20:46:26.713Z",
  "transaction_id": "MCC30105G5020",
  "original_transaction_id": "MCC30105G5020",
  "authorized_at": "2025-08-12T20:46:26.713Z",
  "reason_code": "00",
  "reason_message": "authorized",
  "acquirer": "GETNET",
  "soft_descriptor": "LOJA*TESTE*COMPRA-123",
  "brand": "MASTERCARD",
  "authorization_code": "604020",
  "acquirer_transaction_id": "204050301040206020503010"
}

A Getnet disponibiliza uma lista de cartões de teste que podem ser usados no ambiente de Stage para simular diversos cenários de transação.

Passo 2: Capturar o pagamento

Após uma autorização bem-sucedida, você deve capturar os fundos para finalizar a transação. Use o endpoint de Capture para transferir os fundos previamente autorizados para sua conta.

Ao chamar o endpoint de captura, você deve informar o payment_id da etapa de autorização e o idempotency_key. Se você enviar o valor, ele deve ser igual ou menor que o valor autorizado.

Para confirmar que a captura foi bem-sucedida, verifique se a resposta da API retorna o status HTTP 200 OK e se o campo status no corpo da resposta é CAPTURED.

O bloco de código a seguir mostra um exemplo de requisição e resposta para capturar um pagamento:

Exemplo de requisição:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments/capture \
  --header 'authorization: Bearer ' \
  --header 'content-type: application/json' \
  --data '{
  "idempotency_key": "11c7f8ee-51a6-470d-bb76-ef762b62bfb1",
  "payment_id": "a36887d0-53ec-4c36-b731-9bbeca18fcd2"
}'

Exemplo de resposta

{
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "payment_id": "d36887d0-53ec-4c36-b731-9bbeca18fcd2",
  "idempotency_key": "11c7f8ee-51a6-470d-bb76-ef762b62bfb1",
  "order_id": "order123",
  "amount": 118708,
  "currency": "BRL",
  "status": "CAPTURED",
  "reason_code": "00",
  "reason_message": "captured",
  "captured_at": "2025-08-12T20:47:52.166Z"
}

Passo 3: Verificar o status do pagamento (opcional)

A resposta da autorização inicial mostra o status como AUTHORIZED. Após concluir a etapa de captura, esse status muda para CAPTURED.

Como alguns pagamentos são processados de forma assíncrona, o status pode mudar ao longo do tempo. Para obter o status mais recente de uma transação, use o endpoint Get Transaction.

Para receber atualizações em tempo real sem fazer polling, recomendamos usar Webhooks para receber notificações a cada mudança de status.

Veja também

Você pode explorar mais pagamentos da API Getnet Web Checkout:

• Saiba como criar um pagamento com verificação de cartão.
• Saiba como criar um pagamento com 3DS.