Criar um Pagamento Pré-autorizado com Cartão

Processe uma transação completa de pagamento em duas etapas autorizando-a primeiro para reservar fundos e, em seguida, capturando-a para finalizar a cobrança. Este guia orienta você em cada etapa do uso da Global API da Getnet para esse fluxo comum de e-commerce.

Requisitos

Antes de seguir os passos, você precisa:

Criar sua conta entrando em contato com a equipe de Suporte à Integração para obter suas credenciais de API client_id e client_secret.
Gerar seu token com suas credenciais usando o endpoint de Authentication.

A Getnet fornece uma Postman Collection para ajudá-lo a replicar esses casos de uso localmente. Você também pode testar a API no ambiente sandbox usando a API Reference disponível na documentação.

Especificidades dos Casos de Uso

Ao integrar qualquer solução da Getnet, aplicam-se requisitos específicos do mercado. Certifique-se de revisar os recursos abaixo antes de entrar em produção:

Você também pode usar cartões de teste para simular cenários específicos. Mais informações sobre os requisitos específicos para cada país podem ser encontradas na seção Developer Resources da documentação da 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 o seu sistema e a Global API 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 a captura de pagamentos em uma única etapa. Para mais detalhes, consulte o guia Criar Pagamentos em Etapa Única.

Tokenizar Dados do Cartão (Opcional)

Em vez de enviar o número do cartão no formato original (raw) na sua solicitação de pagamento, você pode usar a tokenização para aumentar a segurança e reduzir o escopo de conformidade do PCI DSS. Para usar um cartão tokenizado:

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

Ao usar number_token, você deve excluir a propriedade card.number da solicitação. Para detalhes completos sobre tokenização, consulte a documentação de Tokenização e Cofre.

Etapa 1: Autorizar o Pagamento

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

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

Para o processo de duas etapas, você deve definir o atributo data.payment.payment_method em sua solicitação como CREDIT_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:

Atributo	Descrição	Obrigatório
`idempotency_key`	Identificador exclusivo para evitar cobranças duplicadas.	Sim
`order_id`	ID de referência do lojista usado para conciliaçã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 da 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 em produção para evitar bloqueios do antifraude.	Sim
`data.payment.payment_method`	Deve ser `CREDIT_AUTHORIZATION` para um fluxo de 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 (use `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 fingerprint do dispositivo (`ip_address`, `device_id`, `finger_print`) para análise antifraude.	Exigido em produção

O payload de 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 (ex., 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`	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 de IP do cliente
`additional_data.device.device_id`	ID da sessão de fingerprint do dispositivo (UUIDv4)
`additional_data.device.finger_print`	Hash de fingerprint gerado pelo script antifraude

Dados do antifraude são obrigatórios para ambientes de produção. Transações sem o fingerprint do dispositivo ou informações do cliente serão automaticamente bloqueadas pelas equipes de antifraude para prevenir fraudes. Consulte a documentação de Antifraude para obter os detalhes completos da implementação.

Ao final de uma autorização bem-sucedida, você receberá um payment_id, que é usado para identificar esta 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"
}

A Getnet fornece uma lista de cartões de teste que podem ser usados no ambiente de Homologação (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 endpoint de Capture para transferir os fundos previamente autorizados para a sua conta.

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

Para confirmar que a captura foi bem-sucedida, verifique se a resposta da API retorna um 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 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 da autorização inicial mostrará o status como AUTHORIZED. Após você 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 endpoint de Get Transaction.

Para atualizações em tempo real sem a necessidade de polling, é recomendável usar Webhooks para receber notificações de cada mudança de status.

Próximos Passos

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

Criar um Pagamento em Etapa Única.
Saiba mais sobre Pagamentos com 3DS.

Nesta página

Criar um Pagamento Pré-autorizado com Cartão

Começando

Core Concepts

Guias de Pagamentos

Alternative Payment Methods

Reference

Webhooks

Métodos de pagamento

Criar um Pagamento Pré-autorizado com Cartão

Requisitos

Especificidades dos Casos de Uso

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óximos Passos