# Criar um pagamento pré-autorizado Este documento se aplica aos seguintes países: Brasil | Chile | México | Espanha | Uruguai ---|---|---|---|---| 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: ![](https://static-devportal-ux.sensedia-eng.com/Pagonxt/production/documentations/flow-payment-preauth-wbc-1787834609409-ilxcgbzr.png) ## Antes de começar Antes de seguir as etapas, você precisa: * Configurar seu Web Checkout via [Portal](/pt/web-checkout/first-steps-wbc/configuration-by-portal) ou via [API](/pt/web-checkout/first-steps-wbc/configration-by-api) (dependendo da sua localização). * Gerar seu token seguindo o documento de [Authentication](/pt/web-checkout/first-steps-wbc/authentication-token-wbc). ## 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. Endpoint| ---| `POST /payment-intent`| **Campos obrigatórios** | Campo | Tipo | Descrição | Exemplo | |---|---|---|---| |`configurations`| Object | Conjunto de opções de pagamento. | -- | |`preauthorization`| Boolean | Indica se é um pagamento do tipo pré-autorizado. | `true`| |`card_verification`| Boolean | Indica se é um pagamento do tipo verificação de cartão. | `false` | |`3ds`| Boolean | Indica se é um pagamento do tipo 3DS. | `false`| O bloco de código a seguir mostra os campos que devem ser enviados no [endpoint de payment intent](https://docs.globalgetnet.com/en/products/online-payments/web-checkout/swagger#tag/payment-intent/post/payment-intent). ```json "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](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/payments/post/dpm/payments-gwproxy/v2/payments) 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](/pt/web-checkout/reference-wbc/pre-autorization-wbc) 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: | Campo | Descrição | Obrigatório | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------- | | `idempotency_key` | Identificador único para evitar cobranças duplicadas. | Sim | | `order_id` | ID de referência do estabelecimento usado para conciliação. | Sim | | `request_id` | Identificador de rastreamento para auditorias de idempotência e 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` | Dados do cliente (nome, e-mail, telefone, documento, endereço completo de cobrança). **Obrigatório em produção para evitar bloqueios antifraude.** | Sim | | `data.payment.payment_method` | Deve ser `CREDIT_PRE_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 (use `1` para pagamento à vista). | 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. | Obrigatório em produção | 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: ```json 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_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 ```json { "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](https://predocs.globalgetnet.com/en/articles?article=test-cards) 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](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/payments/post/dpm/payments-gwproxy/v2/payments/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: ```json 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": "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](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/payment-record-management/get/dpm/hub-payment-info/v1/payments/info/{payment_id}). 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](https://docs.globalgetnet.com/pt/products/online-payments/web-checkout-v2?doc=create-payment-with-card-verification-wbc). * Saiba como [criar um pagamento com 3DS](https://docs.globalgetnet.com/pt/products/online-payments/web-checkout-v2?doc=create-a-3ds-authenticated-payment-wbc).