# Criar um Pagamento em Etapa Única com Cartão Este guia orienta você no processamento de uma transação completa de pagamento em etapa única usando a Global API da Getnet. O fluxo envolve a captura direta do pagamento sem uma autorização prévia. ## 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 Etapa Única Esta seção o orienta através do processo de criação de uma transação de pagamento em etapa única com a Global API da Getnet. Você aprenderá como capturar o pagamento diretamente em uma etapa e, opcionalmente, verificar o status da transação. ### 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: Capturar o Pagamento Um pagamento em etapa única envolve a captura de um pagamento usando o [endpoint de Create - Authorize](https://predocs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/payments/post/dpm/payments-gwproxy/v2/payments). Esta etapa valida os detalhes de pagamento do cliente e transfere os fundos diretamente. > **Requisitos específicos do país**: Alguns mercados podem exigir campos obrigatórios adicionais. No Uruguai, você deve incluir um array `rates`, fornecer um `regional_regulation_code` e definir `data.payment.transaction_type` como `FULL`. 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. Para o processo de etapa única, você deve definir o atributo `data.payment.payment_method` em sua solicitação como `CREDIT` ou `DEBIT`. Isso garante que os fundos sejam 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 (Prod) | | `data.payment.payment_method` | Deve ser `CREDIT` ou `DEBIT` para um fluxo de etapa única. | 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. | Sim (Prod) | Os objetos necessários para a validação antifraude devem 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. O bloco de código a seguir mostra uma solicitação de um pagamento em etapa única: ```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-ef762b62bfb9", "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3", "order_id": "ORDER-10187383", "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", "save_card_data": false, "transaction_type": "FULL", "number_installments": 1, "soft_descriptor": "LOJA*TESTE*COMPRA-123", "dynamic_mcc": 1799, "card": { "number": "5155901222260000", "expiration_month": "09", "expiration_year": "30", "cardholder_name": "Card Holder", "security_code": "517" } }, "additional_data": { "device": { "ip_address": "192.168.1.1", "device_id": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9", "finger_print": "1a2b3c4d5e6f7g8h9i0j" } } } }' ``` Exemplo de resposta com `status` como `APPROVED`: ```json { "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9", "seller_id": "e0ed6f00-fdc5-46d6-9557-6a2cac641b09", "payment_id": "053de7f9-3725-437b-bdfc-bbf3ed0acb75", "order_id": "ORDER-10187383", "amount": 118708, "currency": "BRL", "status": "APPROVED", "payment_method": "CREDIT", "received_at": "2025-10-31T13:40:47.382Z", "transaction_id": "MCC50205G1020", "original_transaction_id": "MCC50205G1020", "authorized_at": "2025-10-31T13:40:47.382Z", "reason_code": "00", "reason_message": "captured", "acquirer": "GETNET", "soft_descriptor": "LOJA*TESTE*COMPRA-123", "brand": "MASTERCARD", "authorization_code": "204050", "acquirer_transaction_id": "405030304060404030501060" } ``` ### Etapa 2: Verificar o Status do Pagamento (Opcional) A resposta do `Create - Authorize` mostrará o status como `APPROVED`. 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 etapa única, você pode explorar mais recursos da Global API da Getnet: * Saiba como criar um [Pagamento em Duas Etapas](https://predocs.globalgetnet.com/en/products/online-payments/regional-api?doc=create-pre-authorized-payment). * Leia sobre [Pagamentos com 3DS](https://predocs.globalgetnet.com/en/products/online-payments/regional-api?doc=api-ref-3ds-authentication-20).