# 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](https://predocs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/authentication). > A Getnet fornece uma [Postman Collection](https://predocs.globalgetnet.com/en/products/online-payments/regional-api?doc=api-ref-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: - [Códigos de moeda](https://predocs.globalgetnet.com/en/articles?article=currency-codes) - [Tipos de documento](https://predocs.globalgetnet.com/en/articles?article=document-types) - [Impostos e regulamentações locais](https://predocs.globalgetnet.com/en/articles?article=taxes-and-regulations) Você também pode usar [cartões de teste](https://predocs.globalgetnet.com/en/articles?article=test-cards) 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](https://predocs.globalgetnet.com/en/articles?article=currency-codes) 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](https://predocs.globalgetnet.com/en/products/online-payments/regional-api?doc=create-single-step-payment). ### 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: 1. Tokenize o cartão chamando o [endpoint de Card Tokenization](https://predocs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/cards/post/dpm/cofre-gw-proxy/v1/tokens/card) com o `card_number` e o `customer_id`. 2. 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](https://predocs.globalgetnet.com/en/products/online-payments/regional-api?doc=api-ref-tokenization-and-vault). ### 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](https://predocs.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 de pré-autorização específicos, regras de ajuste e janelas de captura. Revise a [referência de pré-autorização](https://predocs.globalgetnet.com/en/products/online-payments/regional-api?doc=pre-authorization) 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. > **Requisitos específicos do país**: Alguns mercados podem exigir campos obrigatórios adicionais. No Uruguai, você deve incluir um array `rates` e fornecer um `regional_regulation_code`. O `regional_regulation_code` é um array em que cada entrada tem um `code` e um `invoice`. O `invoice` aceita até 9 caracteres alfanuméricos. Recomendamos usar apenas números. Revise a referência de [Taxes and Regulations](https://predocs.globalgetnet.com/en/articles?article=taxes-and-regulations) para obter mais informações. 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](https://predocs.globalgetnet.com/en/products/online-payments/regional-api?doc=risk-security-antifraud) 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" } } } }' ``` 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" } ``` > A Getnet fornece uma lista de [cartões de teste](https://predocs.globalgetnet.com/en/products/online-payments/regional-api?doc=api-ref-test-cards) 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](https://predocs.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 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" }' ``` 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" } ``` ### 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](https://www.google.com/search?q=https://predocs.globalgetnet.com/en/products/online-payments/regional-api/swagger%23tag/payment-record-management/get/dpm/hub-payment-info/v1/payments/info/%7Bpayment_id%7D). 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](https://predocs.globalgetnet.com/en/products/online-payments/regional-api?doc=create-single-step-payment). * Saiba mais sobre [Pagamentos com 3DS](https://predocs.globalgetnet.com/en/products/online-payments/regional-api?doc=api-ref-3ds-authentication-20).