Criar um Pagamento Cartão Presente Pré-autorizado

Processe uma transação de pagamento completa em dois passos em um ambiente Cartão Presente, primeiro autorizando-a para reservar fundos no cartão físico e, posteriormente, capturando-a para finalizar a cobrança. Este guia orienta você no uso da Getnet Regional API para fluxos comuns integrados ao hardware, como hospitalidade ou aluguéis, onde o valor final da transação pode ser ajustado após a leitura inicial do cartão.

Requisitos

Antes de seguir os passos, você precisa:

• Credenciais da API: Entre em contato com a equipe de Suporte à Integração para obter seu client_id e client_secret.
• Bearer Token: Gere seu token com suas credenciais usando o endpoint de Autenticação.
• ID do Hardware: Certifique-se de ter um terminal_number válido do seu dispositivo físico registrado.

A Getnet fornece uma Coleção Bruno/Postman para ajudar você a replicar esses casos de uso de hardware localmente. Você também pode testar a API em sandbox usando as referências específicas de Cartão Presente disponíveis na documentação.

Especificidades do Caso de Uso: Métodos de Verificação de Cartão

As transações Cartão Presente exigem um Método de Verificação do Portador (CVM) e um Modo de Entrada (Entry Mode) definidos no objeto card.

• Chip + PIN: Exige que o hardware capture um pin_block criptografado e um ksn (Key Serial Number).
• Chip (Sem CVM): Usado para transações de baixo valor ou aproximações que não exigem PIN.
• Tarja Magnética: O cartão é passado no leitor (swipe) e os dados completos do track_2 são transmitidos.

Processo Cartão Presente em Dois Passos

O processo de pagamento em dois passos envolve uma autorização inicial para reservar fundos, seguida de uma captura subsequente para finalizar a liquidação. O diagrama de sequência a seguir ilustra as interações entre seu sistema integrado ao hardware e a Getnet Regional API, cobrindo a autorização inicial com o cartão físico, a captura subsequente via API e a verificação do status.

A Getnet também suporta a captura de pagamentos Cartão Presente em um único passo. Para mais detalhes, consulte o guia Criar Pagamentos Cartão Presente de Passo Único.

Passo 1: Autorize o Pagamento

Um pagamento em dois passos começa com a leitura física do cartão. Defina o data.payment.payment_method como DIRECT_CREDIT_AUTHORIZATION. Use o endpoint Create – Authorize com o cabeçalho x-transaction-channel-entry: XX.

Atributos de Autorização Específicos para

Para campos básicos (valor, moeda, etc.) e regras de negócio regionais, consulte a Referência de Pré-autorização.

As seções a seguir fornecem exemplos de payloads baseados em diferentes métodos de entrada e verificação de cartão:

Exemplo 1: Pré-autorização com Chip + PIN Online

Usado quando o cliente insere o cartão e digita o PIN no terminal físico.

{
  "idempotency_key": "5e019fb3-ebf8-4fab-b826-ece982236440",
  "request_id": "f0612285-9493-4c2c-a05a-00268a51ea3a",
  "order_id": "64af4497-864e-430c-9271-826601427a1d",
  "data": {
    "amount": 30960,
    "currency": "CLP",
    "customer_id": "ed2da8dd-1ba9-46e9-8501-f7987dcd9964",
    "payment": {
      "payment_method": "DIRECT_CREDIT_AUTHORIZATION",
      "transaction_type": "FULL",
      "number_installments": 1,
      "soft_descriptor": "MINHA*LOJA",
      "terminal": { "terminal_number": "21000334" },
      "card": {
        "entry_mode": "chip",
        "cardholder_verification_method": "online_pin",
        "seq_number": "000",
        "pin_block": "A0B6BA8D53C8D3C3",
        "ksn": "BC756011020000400001",
        "emv": "9f2701809f3303e0f8c8950580000080009f37045d21705a9f100706010a03a0b8089f2608819ba36f3f7934149f360205b782021c009c01009f1a0204849a032002279f02060000000309605F2A0200325f3401019f34031e03009f120c56495341204352454449544f5f201a2f435249535449414E2047414C494E444F2043484156455A2020",
        "aid": "A0000000031010",
        "track_2": "4508830000001759=281028102800006930"
      }
    }
  }
}

Exemplo 2: Pré-autorização com Chip (Sem PIN)

Usado para transações com chip onde não é exigido o PIN.

{
  "idempotency_key": "c07372cf-6d11-4980-801f-a365840a0386",
  "request_id": "f01db451-fe50-42d3-82d1-d64cedfdc7e8",
  "order_id": "d14c1129-964f-4fc7-b284-87d890820660",
  "data": {
    "amount": 15000,
    "currency": "CLP",
    "payment": {
      "payment_method": "DIRECT_CREDIT_AUTHORIZATION",
      "terminal": { "terminal_number": "123456" },
      "card": {
        "entry_mode": "chip",
        "cardholder_verification_method": "no_cvm",
        "emv": "9f2701809f3303e0f8c8950580000080009f37045d21705a9f100706010a03a0b8089f2608819ba36f3f7934149f360205b782021c009c01009f1a0204849a032002279f02060000000309605F2A0200325f3401019f34031e03009f120c56495341204352454449544f5f201a2f435249535449414E2047414C494E444F2043484156455A2020",
        "aid": "A0000000031010",
        "track_2": "4508830000001759=281028102800006930"
      }
    }
  }
}

Exemplo 3: Pré-autorização com Tarja Magnética

Usado para cartões passados na tarja magnética do leitor de hardware.

{
  "idempotency_key": "a61a2391-1372-46d9-9b8b-e3e265036367",
  "request_id": "140214fa-ff1d-4ecb-a6c8-2e1c828a944c",
  "data": {
    "amount": 10500,
    "currency": "CLP",
    "payment": {
      "payment_method": "DIRECT_CREDIT_AUTHORIZATION",
      "terminal": { "terminal_number": "21000335" },
      "card": {
        "number": "5213120418132948",
        "expiration_month": "08",
        "expiration_year": "28",
        "entry_mode": "magnetic_stripe",
        "track_2": "5213120418132948=301220111379456001"
      }
    }
  }
}

Ao final de uma autorização bem-sucedida, você receberá um payment_id, que é usado para identificar esta transação no próximo passo.

Passo 2: Capture o Pagamento

Após a interação com o cartão físico ser autorizada e o valor final ser determinado, você deve capturar os fundos para finalizar a transação. Use o endpoint Capture para liquidar a cobrança.

Ao chamar o endpoint de captura, você deve fornecer o payment_id do passo de autorização e a idempotency_key. Se você fornecer um valor (amount), este deve ser igual ou inferior ao valor originalmente autorizado.

curl --request POST \
  --url https://api.pre.globalgetnet.com/dpm/payments/capture \
  --header 'authorization: Bearer <YOUR_TOKEN>' \
  --header 'content-type: application/json' \
  --data '{
  "idempotency_key": "capture-key-001",
  "payment_id": "d36887d0-53ec-4c36-b731-9bbeca18fcd2",
  "amount": 50000
}'

Exemplo de Resposta Bem-sucedida:

{
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "payment_id": "d36887d0-53ec-4c36-b731-9bbeca18fcd2",
  "status": "CAPTURED",
  "reason_message": "captured",
  "captured_at": "2026-02-12T20:47:52.166Z"
}

Passo 3: Verifique o Status do Pagamento (Opcional)

A resposta inicial da autorização mostrará o status como AUTHORIZED. Após você completar o passo de captura, este status mudará para CAPTURED. Você pode verificar o estado final da transação a qualquer momento usando o endpoint Get Transaction.

Re-autorização (Ajustando um Valor Autorizado)

Após uma autorização bem-sucedida, mas antes da captura, você pode modificar o valor reservado usando o endpoint de Ajuste. Isso é comum em cenários de hospitalidade e aluguel, onde a cobrança final difere do valor originalmente pré-autorizado.

Requisição de Ajuste

curl --request PATCH \
  --url https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'Authorization: Bearer <YOUR_TOKEN>' \
  --header 'Content-Type: application/json' \
  --header 'x-transaction-channel-entry: XX' \
  --data '{
  "idempotency_key": "adjust-key-001",
  "request_id": "b9c1d2e3-f4a5-6789-b012-c3d4e5f60718",
  "data": {
    "amount": 65000,
    "payment": {
      "payment_id": "d36887d0-53ec-4c36-b731-9bbeca18fcd2",
      "payment_method": "CREDIT_PRE_AUTHORIZATION"
    }
  }
}'

Resposta de Ajuste

Um ajuste bem-sucedido retorna HTTP 200 com os detalhes da autorização atualizados, incluindo o novo amount. Após o ajuste, prossiga para o Passo 2 (Captura) usando o mesmo payment_id.

{
  "payment_id": "d36887d0-53ec-4c36-b731-9bbeca18fcd2",
  "status": "AUTHORIZED",
  "amount": 65000,
  "reason_code": "00",
  "reason_message": "TRANSACTION EXECUTED SUCCESSFULLY"
}

Próximos Passos

Agora que você criou com sucesso um pagamento Cartão Presente em dois passos, explore mais recursos da Getnet Regional API:

• Obter Status da Transação: Consulte o estado atual de qualquer transação autorizada ou capturada.
• Pagamentos via QR Code: Ofereça pagamentos alternativos no terminal físico.
• Pagamentos de Passo Único: Processe vendas padrão com chip e tarja magnética.