# 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](https://docs.globalgetnet.com/pt/products/online-payments/regional-api?doc=api-ref-authentication).
* Comprar o pacote **Recurrence (Subscriptions)** e o pacote **Vault**, ou o pacote Modular com recorrência e vault.

> A Getnet fornece uma [Postman Collection](/en/global-api/sep-api/first-steps-api/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:

* [Códigos de moeda](https://docs.globalgetnet.com/en/articles?article=currency-codes)
* [Tipos de documento](https://docs.globalgetnet.com/en/articles?article=document-types)
* [Impostos e regulamentações locais](https://docs.globalgetnet.com/en/articles?article=taxes-and-regulations)

Você também pode usar [cartões de teste](https://docs.globalgetnet.com/en/articles?article=test-cards) 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](https://docs.globalgetnet.com/en/articles?article=currency-codes) 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](/pt/global-api/reference-global/recurring-payments).

> **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](/pt/global-api/reference-global/recurring-payments).

## 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](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/cards/get/dpm/cofre-gw-proxy/v1/cards/{card_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:

1. **Registrar um cliente**: Crie um registro de cliente no sistema.
2. **Tokenizar o cartão**: Use o endpoint de tokenização para converter o número original (raw) do cartão em um token seguro.
3. **Salvar o cartão no cofre**: Armazene o cartão tokenizado no cofre da Getnet.
4. **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.
5. **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:

![](https://static-devportal-ux.sensedia-eng.com/Pagonxt/production/documentations/diagram-create-a-tokenized-payment-1-1772647386838-6zizof1x.png)

### 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](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/customers/post/dpm/customers-gwproxy/v1/customers) para registrar os detalhes do cliente:

```bash
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": "john.doe@example.com",
  "document_type": "CPF",
  "document_number": "12345678900",
  "phone_number": "+5511999999999"
}'
```

Exemplo de resposta:

```json
{
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "customer_id": "customer-123",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "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.

<Callout type="note">

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.

</Callout>

<Callout type="warning">

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

</Callout>

Use o [endpoint de Card Tokenization](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/cards/post/dpm/cofre-gw-proxy/v1/tokens/card) para tokenizar o cartão:

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

```json
{
  "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](https://docs.globalgetnet.com/pt/products/online-payments/regional-api?doc=api-ref-tokenization-and-vault).

### 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](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/cards/post/dpm/cofre-gw-proxy/v1/cards).

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 |

<Callout type="note">

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.

</Callout>

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

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

```json
{
  "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"
}
```

<Callout type="warning">

Salve o `card_id` da resposta para seus registros.

</Callout>

<Callout type="note">

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.

</Callout>

### 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](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/payments/post/dpm/payments-gwproxy/v2/payments):

**Exemplo para CIT (One Click):**

```bash
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):**

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

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

<Callout type="note">

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.

</Callout>

<Callout type="warning">

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.

</Callout>

<Callout type="warning">

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.

</Callout>

> **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](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/payments/post/dpm/payments-gwproxy/v2/payments):

**Exemplo para CIT (One Click):**

```bash
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):**

```bash
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](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/cards/get/dpm/cofre-gw-proxy/v1/cards/{card_id}) necessária para atualizar o `number_token` renovado. Mantenha o `transaction_id` do primeiro pagamento na requisição.

```bash
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"`.

<Callout type="warning">

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.

</Callout>

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

1. **Registrar um cliente**: Crie um registro de cliente no sistema.
2. **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.
3. **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.

&lt;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](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/customers/post/dpm/customers-gwproxy/v1/customers) para registrar os detalhes do cliente:

```bash
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": "john.doe@example.com",
  "document_type": "CPF",
  "document_number": "12345678900",
  "phone_number": "+5511999999999"
}'
```

Exemplo de resposta:

```json
{
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "customer_id": "customer-123",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "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](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/payments/post/dpm/payments-gwproxy/v2/payments):

**Exemplo para CIT (One Click):**

```bash
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):**

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

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

<Callout type="warning">

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.

</Callout>

<Callout type="warning">

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.

</Callout>

> **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](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/payments/post/dpm/payments-gwproxy/v2/payments):

**Exemplo para CIT (One Click):**

```bash
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):**

```bash
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](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/cards/get/dpm/cofre-gw-proxy/v1/cards/{card_id}) necessária para atualizar o `number_token` renovado. Mantenha o `transaction_id` do primeiro pagamento na requisição.

```bash
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"`.

<Callout type="warning">

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.

</Callout>

> **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](/pt/global-api/sep-api/payment-guides-api/card-payments/recurring-payment)
* Leia mais sobre [Pagamentos Recorrentes](/pt/global-api/reference-global/recurring-payments)
* Explore a documentação de [Tokenização e Cofre](https://docs.globalgetnet.com/pt/products/online-payments/regional-api?doc=api-ref-tokenization-and-vault)