Criar um Pagamento Tokenizado

Este guia orienta você na configuração de pagamentos tokenizados usando a Global API da Getnet. Pagamentos tokenizados permitem que você armazene com segurança as informações do cartão e processe cobranças recorrentes sem exigir que os clientes digitem novamente os detalhes do cartão a cada transação.

Pagamentos tokenizados podem ser iniciados pelo portador do cartão (Cardholder-Initiated Transaction, ou CIT) ou pelo lojista (Merchant-Initiated Transaction, ou MIT). A principal diferença é quem inicia o pagamento e os valores de credentials_on_file_type usados nas requisições da API.

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 da API client_id e client_secret.
Gerar seu token com suas credenciais usando o endpoint de Access Token.
Comprar o pacote Recurrence (Subscriptions) e o pacote Vault, ou o pacote Modular com recorrência e vault.

A Getnet fornece uma Postman Collection para ajudar você a replicar esses casos de uso localmente. Você também pode testar a API no 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:

Você também pode usar cartões de teste para simular cenários específicos. Mais informações sobre os requisitos específicos de cada país podem ser encontradas na seção Developer Resources da documentação da Getnet.

Entendendo Card on File (COF) e Tipos de Transação

Pagamentos tokenizados suportam dois tipos de transação com base em quem inicia o pagamento:

Cardholder-Initiated Transaction (CIT) - One Click: O cliente autoriza o pagamento durante uma transação inicial. Use credentials_on_file_type: "ONE_CLICK" para o primeiro pagamento e "ONE_CLICK_PAYMENT" para os pagamentos subsequentes.
Merchant-Initiated Transaction (MIT) - Recorrente: O lojista aciona os pagamentos em um cronograma regular sem exigir a interação do cliente. Use credentials_on_file_type: "RECURRING" para o primeiro pagamento e "RECURRING_PAYMENT" para os pagamentos subsequentes.

Para informações detalhadas sobre os valores de credentials_on_file_type, consulte Pagamentos Recorrentes.

Nota para a Argentina: A Argentina usa uma estrutura diferente para marcar transações recorrentes. Para a Argentina, você deve incluir o objeto additional_data.recurring em vez de credentials_on_file_type. O objeto deve conter:

payments_identification (String): Uma descrição da transação recorrente

sequence (String): Definido como "FIRST" para a primeira transação recorrente, ou "SUBSEQUENT" para as transações subsequentes

billing_period (String): Mês e ano em que a transação será lançada (formato: MM/YYYY ou MMYYYY)

transaction_identifier (String): Para transações subsequentes, inclua o identificador de transação do primeiro pagamento

Para informações gerais sobre pagamentos recorrentes, incluindo tipos de pagamentos recorrentes e disponibilidade regional, consulte Pagamentos Recorrentes.

Abordagens de tokenização

Você pode implementar pagamentos tokenizados usando duas abordagens diferentes de tokenização:

Fluxo 1: Tokenizar antes do pagamento - Tokenize o cartão primeiro usando o endpoint de tokenização e, em seguida, salve-o no cofre antes de processar o pagamento. Este método permite que você trate a tokenização e o armazenamento no cofre separadamente do processamento do pagamento.
Fluxo 2: Tokenizar durante o pagamento - Envie o número do cartão no formato original (raw) na requisição de pagamento com save_card_data: true. A Getnet tokeniza automaticamente o cartão e o salva no cofre durante o processamento do pagamento, simplificando a integração.

Escolha a abordagem que melhor se adapta às suas necessidades de integração. Ambas as abordagens funcionam tanto para tipos de transação CIT quanto MIT.

Uma vez que um cartão está armazenado no cofre, a forma recomendada de reutilizá-lo em pagamentos subsequentes é enviar apenas o seu card_id no bloco card. A Getnet localiza o cartão armazenado e preenche os demais campos do cartão de forma transparente.

Isso importa porque o number_token armazenado é renovado ao longo do tempo. Para reutilizar um cartão por number_token, você deve primeiro chamar Get Card by ID para recuperar o token atual antes de cada pagamento. Enviar o card_id evita essa chamada extra—a Getnet resolve o token atual para você. Consulte os passos de pagamento subsequente abaixo para ver exemplos.

Fluxo 1: Tokenizar antes do pagamento

Esta abordagem envolve tokenizar o cartão primeiro usando o endpoint de tokenização, em seguida, salvá-lo no cofre e, por fim, usá-lo em requisições de pagamento. Este método permite que você trate a tokenização e o armazenamento no cofre separadamente do processamento de pagamento.

Visão geral do processo

Para este fluxo, o processo funciona da seguinte forma:

Registrar um cliente: Crie um registro de cliente no sistema.
Tokenizar o cartão: Use o endpoint de tokenização para converter o número original (raw) do cartão em um token seguro.
Salvar o cartão no cofre: Armazene o cartão tokenizado no cofre da Getnet.
Processar o primeiro pagamento: Faça o primeiro pagamento usando o número do cartão tokenizado e salve o transaction_id da resposta. Use credentials_on_file_type: "ONE_CLICK" para CIT ou "RECURRING" para MIT.
Processar pagamentos subsequentes: Para todos os pagamentos futuros, use credentials_on_file_type: "ONE_CLICK_PAYMENT" (CIT) ou "RECURRING_PAYMENT" (MIT) e inclua o transaction_id do primeiro pagamento junto com o número do cartão tokenizado.

O diagrama a seguir fornece uma visão geral deste processo:

Etapa 1: Registrar um cliente

Para que os pagamentos tokenizados funcionem, é necessário registrar um cliente. O cliente é o consumidor do produto ou serviço.

Use o endpoint de Create Customer para registrar os detalhes do cliente:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/customers-gwproxy/v1/customers \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --data '{
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "customer_id": "customer-123",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "document_type": "CPF",
  "document_number": "12345678900",
  "phone_number": "+5511999999999"
}'

Exemplo de resposta:

{
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "customer_id": "customer-123",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "document_type": "CPF",
  "document_number": "12345678900",
  "phone_number": "+5511999999999",
  "created_at": "2025-11-06T10:30:00.000Z"
}

Etapa 2 (Opcional): Tokenizar os dados do cartão

Tokenize o cartão antes de processar os pagamentos. A tokenização aumenta a segurança e reduz o escopo de conformidade do PCI DSS ao substituir o número original (raw) do cartão por um token seguro que pode ser usado para cobranças recorrentes.

Esta etapa é opcional. O cofre aceita tanto um number_token tokenizado quanto o number original (raw) do cartão, então você pode pular a tokenização e enviar o number original (raw) do cartão diretamente na Etapa 3. Tokenize o cartão primeiro quando você quiser tratar a tokenização separadamente do armazenamento no cofre.

O processo de tokenização requer o customer_id da Etapa 1.

Use o endpoint de Card Tokenization para tokenizar o cartão:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/cofre-gw-proxy/v1/tokens/card \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --data '{
  "card_number": "5155901222280001",
  "customer_id": "customer-123"
}'

Exemplo de resposta:

{
  "number_token": "dfe05208b105578c070f806c80abd3af09e246827d29b866cf4ce16c205849977c9496cbf0d0234f42339937f327747075f68763537b90b31389e01231d4d13c"
}

Salve o number_token da resposta. Você precisará deste token na Etapa 3 para salvar o cartão no cofre. O token substitui o número original (raw) do cartão em todas as requisições de API subsequentes, aumentando a segurança e reduzindo o escopo de conformidade do PCI DSS.

Para detalhes completos sobre a tokenização, consulte a documentação de Tokenização e Cofre.

Etapa 3: Salvar o cartão no cofre

Para pagamentos tokenizados, você deve salvar o cartão no cofre da Getnet. Use o endpoint de Store Card in Vault.

Ao armazenar o cartão no cofre, inclua os seguintes campos:

Campo	Descrição	Obrigatório
`number_token`	Número do cartão tokenizado da Etapa 2. Envie `number_token` ou `number`.	Condicional
`number`	Número original (raw) do cartão (PAN). Envie `number` ou `number_token`.	Condicional
`brand`	Bandeira do cartão (ex: `"VISA"`, `"MASTERCARD"`)	Sim
`cardholder_name`	Nome do portador do cartão	Sim
`expiration_month`	Mês de validade do cartão	Sim
`expiration_year`	Ano de validade do cartão	Sim
`customer_id`	ID do cliente da Etapa 1	Sim
`verify_card`	Defina como `true` para verificar o cartão	Recomendado
`security_code`	Código de segurança do cartão (CVV) - obrigatório se `verify_card` for `true`	Condicional

Envie number_token ou number, não ambos. Use number_token se você tokenizou o cartão na Etapa 2, ou envie o number original (raw) do cartão para armazenar o cartão sem tokenizá-lo primeiro.

Este é um exemplo de uma requisição para armazenar o cartão no cofre:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/cofre-gw-proxy/v1/cards \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --data '{
  "number_token": "dfe05208b105578c070f806c80abd3af09e246827d29b866cf4ce16c205849977c9496cbf0d0234f42339937f327747075f68763537b90b31389e01231d4d13c",
  "brand": "MASTERCARD",
  "cardholder_name": "John Doe",
  "expiration_month": "12",
  "expiration_year": "30",
  "customer_id": "customer-123",
  "verify_card": true,
  "security_code": "123"
}'

A resposta incluirá um card_id que você pode usar para referência futura.

Exemplo de resposta:

{
  "card_id": "e8ad2ae4-9e3e-4532-998f-1a5a11e56e58",
  "last_four_digits": "0001",
  "bin": "515590",
  "expiration_month": 12,
  "expiration_year": 30,
  "brand": "MASTERCARD",
  "cardholder_name": "JOHN DOE",
  "customer_id": "customer-123",
  "number_token": "dfe05208b105578c070f806c80abd3af09e246827d29b866cf4ce16c205849977c9496cbf0d0234f42339937f327747075f68763537b90b31389e01231d4d13c",
  "used_at": "2025-11-06T10:38:00.000Z",
  "created_at": "2025-11-06T10:38:00.000Z",
  "updated_at": "2025-11-06T10:38:00.000Z",
  "status": "active",
  "transaction_id": "123456"
}

Salve o card_id da resposta para seus registros.

O transaction_id nesta resposta do cofre é a transação de verificação do cartão. Ele não é o valor que você reutiliza em pagamentos subsequentes—esse transaction_id vem da resposta do primeiro pagamento na Etapa 4.

Etapa 4: Processar o primeiro pagamento

Para a primeira transação de pagamento, você deve usar o valor de credentials_on_file_type apropriado com base no seu tipo de transação:

CIT (One Click): Use credentials_on_file_type: "ONE_CLICK"
MIT (Recorrente): Use credentials_on_file_type: "RECURRING"

Use o endpoint de Create Payment:

Exemplo para CIT (One Click):

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer <your-token>' \
  --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": 9900,
    "currency": "BRL",
    "customer_id": "customer-123",
    "payment": {
      "payment_method": "CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "credentials_on_file_type": "ONE_CLICK",
      "card": {
        "number_token": "dfe05208b105578c070f806c80abd3af09e246827d29b866cf4ce16c205849977c9496cbf0d0234f42339937f327747075f68763537b90b31389e01231d4d13c",
        "brand": "MASTERCARD",
        "expiration_month": "12",
        "expiration_year": "30",
        "cardholder_name": "John Doe",
        "security_code": "123"
      }
    }
  }
}'

Exemplo para MIT (Recorrente):

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer <your-token>' \
  --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": 9900,
    "currency": "BRL",
    "customer_id": "customer-123",
    "payment": {
      "payment_method": "CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "credentials_on_file_type": "RECURRING",
      "card": {
        "number_token": "dfe05208b105578c070f806c80abd3af09e246827d29b866cf4ce16c205849977c9496cbf0d0234f42339937f327747075f68763537b90b31389e01231d4d13c",
        "brand": "MASTERCARD",
        "expiration_month": "12",
        "expiration_year": "30",
        "cardholder_name": "John Doe",
        "security_code": "123"
      }
    }
  }
}'

A resposta incluirá um transaction_id. Salve este valor—você precisará dele para todas as transações de pagamento subsequentes:

{
  "payment_id": "053de7f9-3725-437b-bdfc-bbf3ed0acb75",
  "order_id": "ORDER-10187383",
  "status": "APPROVED",
  "transaction_id": "MCC50205G1020",
  ...
}

Esta resposta do primeiro pagamento não retorna um card_id. Se você usar a opção simplificada de card_id na Etapa 5, esse card_id vem da resposta do cofre da Etapa 3—não desta resposta.

O number_token usado no pagamento deve ser o token obtido na Etapa 2. Ao usar o number_token, você também deve fornecer a brand, cardholder_name, security_code, expiration_month e expiration_year do cartão na requisição de pagamento. Esses detalhes são obrigatórios mesmo que o próprio número do cartão seja tokenizado. O cartão deve ser salvo no cofre (Etapa 3) antes de processar o primeiro pagamento.

O transaction_id deste primeiro pagamento deve ser salvo e usado em todas as transações de pagamento subsequentes para identificar o cliente e o seu método de pagamento.

Nota para a Argentina: Para a Argentina, use o objeto additional_data.recurring em vez de credentials_on_file_type. Para a primeira transação, defina sequence: "FIRST" e inclua billing_period com o mês e o ano (formato: MM/YYYY ou MMYYYY).

Etapa 5: Processar pagamentos subsequentes

Para todas as transações de pagamento subsequentes, você deve usar o valor de credentials_on_file_type apropriado e incluir o transaction_id do primeiro pagamento na sua requisição:

CIT (One Click): Use credentials_on_file_type: "ONE_CLICK_PAYMENT"
MIT (Recorrente): Use credentials_on_file_type: "RECURRING_PAYMENT"

Use o endpoint de Create Payment:

Exemplo para CIT (One Click):

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer <your-token>' \
  --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-10187384",
  "data": {
    "amount": 9900,
    "currency": "BRL",
    "customer_id": "customer-123",
    "payment": {
      "payment_method": "CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "credentials_on_file_type": "ONE_CLICK_PAYMENT",
      "transaction_id": "MCC50205G1020",
      "card": {
        "number_token": "dfe05208b105578c070f806c80abd3af09e246827d29b866cf4ce16c205849977c9496cbf0d0234f42339937f327747075f68763537b90b31389e01231d4d13c",
        "brand": "MASTERCARD",
        "expiration_month": "12",
        "expiration_year": "30",
        "cardholder_name": "John Doe",
        "security_code": "123"
      }
    }
  }
}'

Exemplo para MIT (Recorrente):

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer <your-token>' \
  --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-10187384",
  "data": {
    "amount": 9900,
    "currency": "BRL",
    "customer_id": "customer-123",
    "payment": {
      "payment_method": "CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "credentials_on_file_type": "RECURRING_PAYMENT",
      "transaction_id": "MCC50205G1020",
      "card": {
        "number_token": "dfe05208b105578c070f806c80abd3af09e246827d29b866cf4ce16c205849977c9496cbf0d0234f42339937f327747075f68763537b90b31389e01231d4d13c",
        "brand": "MASTERCARD",
        "expiration_month": "12",
        "expiration_year": "30",
        "cardholder_name": "John Doe",
        "security_code": "123"
      }
    }
  }
}'

Opção simplificada — referenciar o cartão armazenado com card_id:

Esta é a forma recomendada de reutilizar um cartão armazenado. Envie apenas o card_id do cartão armazenado (retornado na Etapa 3) no bloco card, e a Getnet preenche os demais campos de forma transparente — você não precisa enviar number_token, brand, cardholder_name, expiration_month, expiration_year ou security_code. Como a Getnet resolve o token atual para você, você também evita a chamada extra ao Get Card by ID necessária para atualizar o number_token renovado. Mantenha o transaction_id do primeiro pagamento na requisição.

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer <your-token>' \
  --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-10187384",
  "data": {
    "amount": 9900,
    "currency": "BRL",
    "customer_id": "customer-123",
    "payment": {
      "payment_method": "CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "credentials_on_file_type": "ONE_CLICK_PAYMENT",
      "transaction_id": "MCC50205G1020",
      "card": {
        "card_id": "e8ad2ae4-9e3e-4532-998f-1a5a11e56e58"
      }
    }
  }
}'

Este exemplo usa ONE_CLICK_PAYMENT (CIT). Para MIT, use credentials_on_file_type: "RECURRING_PAYMENT".

O transaction_id na requisição de pagamento deve corresponder ao transaction_id da primeira transação de pagamento (Etapa 4). Isso permite que a Getnet identifique o cliente e o seu método de pagamento.

Nota para a Argentina: Para a Argentina, use o objeto additional_data.recurring em vez de credentials_on_file_type. Para transações subsequentes, defina sequence: "SUBSEQUENT" e inclua transaction_identifier com o identificador de transação do primeiro pagamento, junto com o billing_period para o período de faturamento atual.

Fluxo 2: Tokenizar durante o pagamento

Esta abordagem envolve o envio do número do cartão no formato original (raw) na requisição de pagamento com save_card_data: true. A Getnet tokeniza automaticamente o cartão e o salva no cofre durante o processamento do pagamento. Este método simplifica a integração combinando tokenização, armazenamento no cofre e pagamento em uma única etapa.

Visão geral do processo

Para este fluxo, o processo funciona da seguinte forma:

Registrar um cliente: Crie um registro de cliente no sistema.
Processar o primeiro pagamento: Envie o número do cartão no formato original (raw) na requisição de pagamento com save_card_data: true e o valor de credentials_on_file_type apropriado (ONE_CLICK para CIT ou RECURRING para MIT). A Getnet tokeniza automaticamente o cartão e o salva no cofre durante o processamento do pagamento. Salve o transaction_id da resposta.
Processar pagamentos subsequentes: Para todos os pagamentos futuros, use credentials_on_file_type: "ONE_CLICK_PAYMENT" (CIT) ou "RECURRING_PAYMENT" (MIT) e inclua o transaction_id do primeiro pagamento junto com o número do cartão tokenizado.

<Diagram: resources/diagrams/tokenized-payment-flow-2.mermaid>

Etapa 1: Registrar um cliente

Para que os pagamentos tokenizados funcionem, é necessário registrar um cliente. O cliente é o consumidor do produto ou serviço.

Use o endpoint de Create Customer para registrar os detalhes do cliente:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/customers-gwproxy/v1/customers \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --data '{
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "customer_id": "customer-123",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "document_type": "CPF",
  "document_number": "12345678900",
  "phone_number": "+5511999999999"
}'

Exemplo de resposta:

{
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "customer_id": "customer-123",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "document_type": "CPF",
  "document_number": "12345678900",
  "phone_number": "+5511999999999",
  "created_at": "2025-11-06T10:30:00.000Z"
}

Etapa 2: Processar o primeiro pagamento com tokenização do cartão

Para a primeira transação de pagamento, envie o número do cartão no formato original (raw) na requisição de pagamento juntamente com save_card_data: true e o valor de credentials_on_file_type apropriado. A Getnet tokeniza automaticamente o cartão e o salva no cofre durante o processamento do pagamento.

Use o endpoint de Create Payment:

Exemplo para CIT (One Click):

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer <your-token>' \
  --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": 9900,
    "currency": "BRL",
    "customer_id": "customer-123",
    "payment": {
      "payment_method": "CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "credentials_on_file_type": "ONE_CLICK",
      "save_card_data": true,
      "card": {
        "number": "5155901222280001",
        "brand": "MASTERCARD",
        "expiration_month": "12",
        "expiration_year": "30",
        "cardholder_name": "John Doe",
        "security_code": "123"
      }
    }
  }
}'

Exemplo para MIT (Recorrente):

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer <your-token>' \
  --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": 9900,
    "currency": "BRL",
    "customer_id": "customer-123",
    "payment": {
      "payment_method": "CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "credentials_on_file_type": "RECURRING",
      "save_card_data": true,
      "card": {
        "number": "5155901222280001",
        "brand": "MASTERCARD",
        "expiration_month": "12",
        "expiration_year": "30",
        "cardholder_name": "John Doe",
        "security_code": "123"
      }
    }
  }
}'

A resposta incluirá um transaction_id e um card_id para o cartão armazenado. Salve ambos os valores—você precisará do transaction_id para todas as transações de pagamento subsequentes, e pode usar o card_id para referenciar o cartão armazenado em pagamentos posteriores:

{
  "payment_id": "053de7f9-3725-437b-bdfc-bbf3ed0acb75",
  "order_id": "ORDER-10187383",
  "status": "APPROVED",
  "transaction_id": "MCC50205G1020",
  "card_id": "e8ad2ae4-9e3e-4532-998f-1a5a11e56e58",
  ...
}

Ao enviar o number original (raw) do cartão na requisição de pagamento com save_card_data: true, você também deve fornecer a brand, cardholder_name, security_code, expiration_month e expiration_year do cartão. O cartão será automaticamente tokenizado e salvo no cofre durante o processamento do pagamento.

O transaction_id deste primeiro pagamento deve ser salvo e usado em todas as transações de pagamento subsequentes para identificar o cliente e o seu método de pagamento.

Nota para a Argentina: Para a Argentina, use o objeto additional_data.recurring em vez de credentials_on_file_type. Para a primeira transação, defina sequence: "FIRST" e inclua billing_period com o mês e o ano (formato: MM/YYYY ou MMYYYY).

Etapa 3: Processar pagamentos subsequentes

Para todas as transações de pagamento subsequentes, você deve usar o valor de credentials_on_file_type apropriado e incluir o transaction_id do primeiro pagamento na sua requisição. Use o token do número do cartão tokenizado obtido da resposta do primeiro pagamento:

CIT (One Click): Use credentials_on_file_type: "ONE_CLICK_PAYMENT"
MIT (Recorrente): Use credentials_on_file_type: "RECURRING_PAYMENT"

Use o endpoint de Create Payment:

Exemplo para CIT (One Click):

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer <your-token>' \
  --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-10187384",
  "data": {
    "amount": 9900,
    "currency": "BRL",
    "customer_id": "customer-123",
    "payment": {
      "payment_method": "CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "credentials_on_file_type": "ONE_CLICK_PAYMENT",
      "transaction_id": "MCC50205G1020",
      "card": {
        "number_token": "dfe05208b105578c070f806c80abd3af09e246827d29b866cf4ce16c205849977c9496cbf0d0234f42339937f327747075f68763537b90b31389e01231d4d13c",
        "brand": "MASTERCARD",
        "expiration_month": "12",
        "expiration_year": "30",
        "cardholder_name": "John Doe",
        "security_code": "123"
      }
    }
  }
}'

Exemplo para MIT (Recorrente):

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer <your-token>' \
  --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-10187384",
  "data": {
    "amount": 9900,
    "currency": "BRL",
    "customer_id": "customer-123",
    "payment": {
      "payment_method": "CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "credentials_on_file_type": "RECURRING_PAYMENT",
      "transaction_id": "MCC50205G1020",
      "card": {
        "number_token": "dfe05208b105578c070f806c80abd3af09e246827d29b866cf4ce16c205849977c9496cbf0d0234f42339937f327747075f68763537b90b31389e01231d4d13c",
        "brand": "MASTERCARD",
        "expiration_month": "12",
        "expiration_year": "30",
        "cardholder_name": "John Doe",
        "security_code": "123"
      }
    }
  }
}'

Opção simplificada — referenciar o cartão armazenado com card_id:

Esta é a forma recomendada de reutilizar um cartão armazenado. Envie apenas o card_id retornado pelo primeiro pagamento (Etapa 2) no bloco card, e a Getnet preenche os demais campos de forma transparente — você não precisa enviar number_token, brand, cardholder_name, expiration_month, expiration_year ou security_code. Como a Getnet resolve o token atual para você, você também evita a chamada extra ao Get Card by ID necessária para atualizar o number_token renovado. Mantenha o transaction_id do primeiro pagamento na requisição.

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer <your-token>' \
  --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-10187384",
  "data": {
    "amount": 9900,
    "currency": "BRL",
    "customer_id": "customer-123",
    "payment": {
      "payment_method": "CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "credentials_on_file_type": "ONE_CLICK_PAYMENT",
      "transaction_id": "MCC50205G1020",
      "card": {
        "card_id": "e8ad2ae4-9e3e-4532-998f-1a5a11e56e58"
      }
    }
  }
}'

Este exemplo usa ONE_CLICK_PAYMENT (CIT). Para MIT, use credentials_on_file_type: "RECURRING_PAYMENT".

O transaction_id na requisição de pagamento deve corresponder ao transaction_id da primeira transação de pagamento (Etapa 2). Isso permite que a Getnet identifique o cliente e o seu método de pagamento.

Nota para a Argentina: Para a Argentina, use o objeto additional_data.recurring em vez de credentials_on_file_type. Para transações subsequentes, defina sequence: "SUBSEQUENT" e inclua transaction_identifier com o identificador de transação do primeiro pagamento, junto com o billing_period para o período de faturamento atual.

Considerações importantes

Ao gerenciar cronogramas de pagamento tokenizado, tenha em mente estes pontos importantes:

Para pagamentos tokenizados, o cartão deve ser tokenizado e salvo no cofre antes ou durante o primeiro pagamento.
A tokenização é obrigatória para pagamentos tokenizados. Você pode tokenizar o cartão antes de processar o pagamento (Fluxo 1) ou enviar os dados do cartão no formato original (raw) na requisição de pagamento com save_card_data: true (Fluxo 2), onde ele será tokenizado e salvo automaticamente.
Sempre use o transaction_id do primeiro pagamento (ONE_CLICK ou RECURRING) em todas as requisições de pagamento subsequentes (ONE_CLICK_PAYMENT ou RECURRING_PAYMENT).
Para reutilizar um cartão armazenado em pagamentos subsequentes, envie apenas o seu card_id no bloco card. A Getnet preenche os demais campos do cartão a partir do cofre automaticamente, então você não precisa reenviar o number_token ou os outros detalhes do cartão.
Você é responsável por acionar cada transação de pagamento de acordo com o seu cronograma de negócios.
Ao usar o Fluxo 2 (Tokenizar durante o pagamento), certifique-se de incluir save_card_data: true na sua requisição de pagamento para salvar automaticamente o cartão no cofre.

Próximos passos

Agora que você criou com sucesso um pagamento tokenizado, você pode explorar mais recursos da Global API da Getnet:

Saiba mais sobre o Getnet Recurring Payments Engine
Leia mais sobre Pagamentos Recorrentes
Explore a documentação de Tokenização e Cofre