# 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](https://api.pre.globalgetnet.com/authentication/oauth2/access_token). - **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](https://predocs.globalgetnet.com/en/products/online-payments/regional-api). ### 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](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/payments/post/dpm/payments-gwproxy/v2/payments) 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. | Objeto | Atributo | Descrição | Obrigatório | | --- | --- | --- | --- | | `terminal` | `terminal_number` | O ID exclusivo do dispositivo de hardware físico. | **Sim** | | `card` | `entry_mode` | Identifica como o cartão foi lido (`chip` ou `magnetic_stripe`). | **Sim** | | `card` | `cardholder_verification_method` | Lógica para verificação do portador (`online_pin` ou `no_cvm`). | **Sim (Chip)** | | `card` | `emv` | A string de dados TLV criptografada do chip. | **Sim (Chip)** | | `card` | `track_2` | Os dados de trilha do cartão capturados durante o swipe ou leitura do chip. | **Sim** | 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. ```json { "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. ```json { "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. ```json { "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](https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments/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. ```bash curl --request POST \ --url https://api.pre.globalgetnet.com/dpm/payments/capture \ --header 'authorization: Bearer ' \ --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: ```json { "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](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/payments/patch/dpm/payments-gwproxy/v2/payments). Isso é comum em cenários de hospitalidade e aluguel, onde a cobrança final difere do valor originalmente pré-autorizado. O `payment_method` em uma requisição de ajuste deve ser sempre `CREDIT_PRE_AUTHORIZATION`. Somente o valor (`amount`) pode ser modificado nesta fase — a interação com o cartão já está concluída. ### Requisição de Ajuste | Campo | Tipo | Descrição | Obrigatório | | --- | --- | --- | --- | | `idempotency_key` | String | Chave exclusiva para esta requisição de ajuste. Deve ser diferente da chave de autorização original. | **Sim** | | `request_id` | String (UUID) | Identificador exclusivo para esta operação de ajuste. | **Sim** | | `data.amount` | Inteiro | O novo valor autorizado em centavos. Pode ser maior ou menor que o original. | **Sim** | | `data.payment.payment_id` | String (UUID) | O `payment_id` da resposta da autorização original. | **Sim** | | `data.payment.payment_method` | Enum | Deve ser `CREDIT_PRE_AUTHORIZATION`. | **Sim** | ```bash curl --request PATCH \ --url https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments \ --header 'Authorization: Bearer ' \ --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`. ```json { "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](/pt/global-api/sep-card-present/payment-guides-cp/qr-code-cp)**: Ofereça pagamentos alternativos no terminal físico. - **[Pagamentos de Passo Único](/pt/global-api/sep-card-present/payment-guides-cp/single-step-payment-cp)**: Processe vendas padrão com chip e tarja magnética.