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.

A Getnet fornece uma 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
• Tipos de documento
• Impostos e regulamentações locais

Você também pode usar cartões de teste 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 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 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.

Etapa 1: Capturar o Pagamento

Um pagamento em etapa única envolve a captura de um pagamento usando o endpoint de Create - Authorize. 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 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:

Os objetos necessários para a validação antifraude devem incluir os seguintes campos:

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 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:

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:

{
  "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.

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.
• Leia sobre Pagamentos com 3DS.