Crie um pagamento com pré-autorização

Processe uma transação de pagamento completa em duas etapas autorizando-a primeiro a reservar fundos e depois capturando-a para finalizar a cobrança. Este guia mostra todas as etapas do uso da API regional da Getnet para esse fluxo comum de comércio eletrônico.

Requisitos

Antes de seguir as etapas, você precisa:

Crie sua conta entrando em contato com a equipe de suporte de integração para obter suas credenciais de API client_id e client_secret.
Gere seu token com suas credenciais usando o Authentication endpoint.

O Getnet fornece um Postman Collection para ajudar você a replicar esses casos de uso localmente. Você também pode testar a API em caixa de areia usando a referência de API disponível na documentação.

Casos de uso e especificidades

Ao integrar qualquer solução Getnet, os requisitos específicos do mercado se aplicam. Não deixe de conferir os recursos abaixo antes de publicar:

Você também pode usar test cards para simular cenários específicos. Mais informações sobre requisitos específicos para cada país podem ser encontradas no Developer Resources section da documentação do Getnet.

Processo de pagamento em duas etapas

Para ajudar a visualizar o processo de pagamento em duas etapas, o diagrama de sequência a seguir ilustra as interações entre seu sistema e a API regional da Getnet. Ele abrange a autorização inicial, a captura subsequente e os dois métodos para verificar o status final.

A Getnet também suporta a criação e captura de pagamentos em uma única etapa. Para obter mais detalhes, consulte o Create Single-Step Payments guide.

Tokenizar dados do cartão (opcional)

Em vez de enviar o número bruto do cartão em sua solicitação de pagamento, você pode usar a tokenização para aprimorar a segurança e reduzir o escopo de conformidade com o PCI DSS. Para usar um cartão tokenizado:

Tokenize o cartão ligando para o Card Tokenization endpoint com o card_number e customer_id.
Em sua solicitação de pagamento, substitua o card.number campo com card.number_token usando o valor do token recebido do endpoint de tokenização.

Ao usar number_token, você deve excluir o card.number propriedade da solicitação. Para obter detalhes completos sobre tokenização, consulte o Tokenization and Vault documentation.

Etapa 1: autorizar o pagamento

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

Alguns países e esquemas de cartões impõem limites específicos de pré-autorização, regras de ajuste e janelas de captura. Revise o pre-authorization reference para requisitos de país a país.

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

Atributo	Descrição	Obrigatório
`idempotency_key`	Identificador exclusivo para evitar cobranças duplicadas.	sim
`order_id`	ID de referência do comerciante usada para reconciliação.	sim
`request_id`	Identificador de rastreamento para auditorias de idempotência e acompanhamento de suporte.	Recomendado
`data.amount`	Valor da transação em centavos.	sim
`data.currency`	Código de moeda ISO usado na transação.	sim
`data.customer`	Detalhes do cliente (nome, e-mail, telefone, documento, endereço de cobrança completo). Obrigatório na produção para evitar bloqueios antifraude.	sim
`data.payment.payment_method`	Deve ser `CREDIT_AUTHORIZATION` para um fluxo em duas etapas.	sim
`data.payment.transaction_type`	Define como a transação é processada (`FULL`, `INSTALL_NO_INTEREST`, `INSTALL_WITH_INTEREST`).	sim
`data.payment.number_installments`	Número de parcelas (uso) `1` para um único pagamento).	sim
`data.payment.card`	Conjunto de dados do cartão (`number`, `brand`, `expiration_month`, `expiration_year`, `security_code`, `cardholder_name`).	sim
`data.additional_data.device`	Informações de impressão digital do dispositivo (`ip_address`, `device_id`, `finger_print`) para análise antifraude.	Produção necessária

A carga antifraude também deve incluir os seguintes campos:

Objeto/campo	Descrição
`customer.first_name`	Primeiro nome do cliente
`customer.last_name`	Sobrenome do cliente
`customer.email`	Endereço de e-mail do cliente
`customer.phone_number`	Número de telefone (formato internacional)
`customer.document_type`	Tipo de documento (por exemplo, CPF, DNI etc.)
`customer.document_number`	Número do documento (sem pontuação)
`customer.billing_address.street`	Nome da rua
`customer.billing_address.number`	Número do endereço
`customer.billing_address.district`	Distrito ou bairro
`customer.billing_address.city`	Cidade
`customer.billing_address.state`	Estado ou província
`customer.billing_address.country`	Código do país (ISO)
`customer.billing_address.postal_code`	Código postal ou CEP
`additional_data.device.ip_address`	Endereço IP do cliente
`additional_data.device.device_id`	ID da sessão de impressão digital do dispositivo (UUIDv4)
`additional_data.device.finger_print`	Hash de impressão digital gerado pelo script antifraude

Os dados antifraude são obrigatório para ambientes de produção. As transações sem impressão digital do dispositivo ou informações do cliente serão automaticamente bloqueadas pelas equipes antifraude para evitar fraudes. Veja o Antifraud documentation para obter detalhes completos da implementação.

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

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

bash

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": "john.doe@example.com",
      "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_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"
      }
    }
  }
}'

bash

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": "john.doe@example.com",
      "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_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:

json

{
  "idempotency_key": "13c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "payment_id": "d36887d0-53ec-4c36-b731-9bbeca18fcd2",
  "order_id": "123order2",
  "amount": 118708,
  "currency": "CLP",
  "status": "AUTHORIZED",
  "payment_method": "CREDIT_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"
}

json

{
  "idempotency_key": "13c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "payment_id": "d36887d0-53ec-4c36-b731-9bbeca18fcd2",
  "order_id": "123order2",
  "amount": 118708,
  "currency": "CLP",
  "status": "AUTHORIZED",
  "payment_method": "CREDIT_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"
}

O Getnet fornece uma lista de test cards que podem ser usados no ambiente Stage para simular vários cenários de transação.

Etapa 2: capturar o pagamento

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

Ao chamar o endpoint de captura, você deve fornecer a payment_id da etapa de autorização e do idempotency_key. Se você enviar o valor, ele deverá ser igual ou inferior ao valor autorizado.

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

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

bash

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

bash

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:

json

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

json

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

Etapa 3: verificar o status do pagamento (opcional)

A resposta de autorização inicial mostrará o status como AUTHORIZED. Depois de concluir a etapa de captura, esse status mudará para CAPTURED.

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

Para atualizações em tempo real sem pesquisas, é recomendável usar Webhooks para receber notificações de cada alteração de status.

Próximas etapas

Agora que você criou com sucesso um pagamento em duas etapas, você pode explorar mais recursos da API regional da Getnet:

Criar a Single-Step Payment.
Saiba mais sobre 3DS Payments.

Nesta página

Crie um pagamento com pré-autorização

Primeiros Passos

Card Present

Reference

Webhooks

Crie um pagamento com pré-autorização

Requisitos

Casos de uso e especificidades

Processo de pagamento em duas etapas

Tokenizar dados do cartão (opcional)

Etapa 1: autorizar o pagamento

Etapa 2: capturar o pagamento

Etapa 3: verificar o status do pagamento (opcional)

Próximas etapas