Crie um pagamento com cartão em uma única etapa

Este guia orienta você no processamento de uma transação de pagamento completa em uma única etapa usando a API regional da Getnet. O fluxo envolve a captura direta do pagamento sem uma autorização prévia.

Requisitos

Antes de seguir as etapas, você precisa:

Crie sua conta entrando em contato com a equipe de suporte de integração para obter suas credenciais de API client_id e client_secret.
Gere seu token com suas credenciais usando o Authentication endpoint.

O Getnet fornece um Postman Collection para ajudar você a replicar esses casos de uso localmente. Você também pode testar a API no sandbox usando a Referência da API disponível na documentação.

Casos de uso e especificidades

Ao integrar qualquer solução Getnet, os requisitos específicos do mercado se aplicam. Não deixe de conferir os recursos abaixo antes de publicar:

Você também pode usar test cards para simular cenários específicos. Mais informações sobre requisitos específicos para cada país podem ser encontradas no Developer Resources section da documentação do Getnet.

Processo de pagamento em uma única etapa

Esta seção orienta você no processo de criação de uma transação de pagamento em uma única etapa com a API Regional da Getnet. Você aprenderá como capturar o pagamento diretamente em uma única etapa e, opcionalmente, verificar o status da transação.

O diagrama a seguir fornece uma visão geral do processo de pagamento em uma única etapa:

Tokenizar dados do cartão (opcional)

Em vez de enviar o número bruto do cartão em sua solicitação de pagamento, você pode usar a tokenização para aprimorar a segurança e reduzir o escopo de conformidade com o PCI DSS. Para usar um cartão tokenizado:

Tokenize o cartão ligando para o Card Tokenization endpoint com o card_number e customer_id.
Em sua solicitação de pagamento, substitua o card.number campo com card.number_token usando o valor do token recebido do endpoint de tokenização.

Ao usar number_token, você deve excluir o card.number propriedade da solicitação. Para obter detalhes completos sobre tokenização, consulte o Tokenization and Vault documentation.

Etapa 1: capturar o pagamento

Um pagamento em uma única etapa envolve a captura de um pagamento usando o Create - Authorize endpoint. Essa etapa valida os detalhes de pagamento do cliente e transfere diretamente os fundos.

Requisitos específicos de cada país: Alguns mercados podem exigir campos obrigatórios adicionais. No Uruguai, você deve incluir um rates matriz, forneça um regional_regulation_code, e defina data.payment.transaction_type para FULL. Revise o Taxes and Regulations referência para obter mais informações.

Para o processo de uma única etapa, você deve definir o data.payment.payment_method atributo em sua solicitação para 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 comerciante usada para reconciliaçã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 de 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 na produção para evitar bloqueios antifraude.	Sim (Prod)
`data.payment.payment_method`	Deve ser `CREDIT` ou `DEBIT` para um fluxo de uma única etapa.	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 (uso) `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 impressão digital 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 (por exemplo, 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`	Distrito ou 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 IP do cliente
`additional_data.device.device_id`	ID da sessão de impressão digital do dispositivo (UUIDv4)
`additional_data.device.finger_print`	Hash de impressão digital gerado pelo script antifraude

Os dados antifraude são obrigatório para ambientes de produção. As transações sem impressão digital do dispositivo ou informações do cliente serão automaticamente bloqueadas pelas equipes antifraude para evitar fraudes. Veja o Antifraud documentation para obter detalhes completos da implementação.

Ao final de uma autorização bem-sucedida, você receberá um payment_id, que é usado para identificar essa transação.

O bloco de código a seguir mostra uma solicitação de pagamento em uma única etapa:

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"
      }
    }
  }
}'

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"
}

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)

O Create - Authorize a resposta 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 Get Transaction endpoint.

Para atualizações em tempo real sem pesquisas, é recomendável usar Webhooks para receber notificações de cada alteração de status.

Próximas etapas

Agora que você criou com sucesso um pagamento em uma única etapa, você pode explorar mais recursos da API regional da Getnet:

Saiba como criar um Two-Step Payment.
Leia sobre 3DS Payments.

Nesta página

Crie um pagamento com cartão em uma única etapa

Primeiros Passos

Card Present

Reference

Webhooks

Crie um pagamento com cartão em uma única etapa

Requisitos

Casos de uso e especificidades

Processo de pagamento em uma única etapa

Tokenizar dados do cartão (opcional)

Etapa 1: capturar o pagamento

Etapa 2: verificar o status do pagamento (opcional)

Próximas etapas