Create a Tokenized Payment

With tokenized payments, you store a customer’s card once and charge it again later, so the customer never has to re-enter their card details. This guide shows you two ways to set that up with the Getnet Global API.

A tokenized payment starts with either the cardholder (a Cardholder-Initiated Transaction, or CIT) or the merchant (a Merchant-Initiated Transaction, or MIT). What differs between them is who starts the payment and which credentials_on_file_type values you send.

Requirements

Before you start, you need to:

Contact the Integration Support team to create your account and get your API credentials, client_id and client_secret.
Generate a token from those credentials using the Access Token endpoint.
Purchase the Recurrence (Subscriptions) and Vault packages, or the Modular package with recurrence and vault.

Getnet provides a Postman Collection so you can replicate these use cases locally. You can also test the API in the sandbox using the API Reference available in the documentation.

Use Cases Specifics

When integrating any Getnet solution, market-specific requirements apply. Be sure to review the resources below before you go live:

You can also use test cards to simulate specific scenarios. More information about specific requirements for each country can be found in the Developer Resources section of the Getnet documentation.

Payment facilitators: When Getnet enables your credential as a payment facilitator, you must also send the data.sub_merchant object on this request. See Payment Facilitators.

Understanding Card on File (COF) and Transaction Types

Tokenized payments support two transaction types, based on who starts the payment:

Cardholder-Initiated Transaction (CIT) - One Click: The customer authorises the payment during an initial transaction. Use credentials_on_file_type: "ONE_CLICK" for the first payment and "ONE_CLICK_PAYMENT" for subsequent payments.
Merchant-Initiated Transaction (MIT) - Recurring: The merchant triggers payments on a regular schedule without customer interaction. Use credentials_on_file_type: "RECURRING" for the first payment and "RECURRING_PAYMENT" for subsequent payments.

For the full list of credentials_on_file_type values, along with the types of recurring payments and their regional availability, see Recurring Payments.

Note for Argentina: Argentina marks recurring transactions differently. Instead of credentials_on_file_type, include the additional_data.recurring object with:

payments_identification (String): A description of the recurring transaction

sequence (String): Set to "FIRST" for the first recurring transaction, or "SUBSEQUENT" for subsequent transactions

billing_period (String): Month and year when the transaction will be launched (format: MM/YYYY or MMYYYY)

transaction_identifier (String): For subsequent transactions, include the transaction identifier from the first payment

Tokenization approaches

You can tokenize the card in one of two ways:

Flow 1: Tokenize before payment - Tokenize the card with the tokenization endpoint and save it to the vault, then charge it in a separate payment request. Use this when you want to keep tokenization and vault storage separate from the payment.
Flow 2: Tokenize during payment - Send the raw card number in the payment request with save_card_data: true. Getnet tokenizes the card and stores it in the vault as part of processing the payment, so it all happens in one call.

Both flows work for CIT and MIT. Pick the one that fits your integration.

Once a card is in the vault, reuse it in later payments by sending only its card_id in the card block. Getnet looks up the stored card and fills in the remaining card fields for you.

This matters because the stored number_token changes over time. To reuse a card by number_token, you first have to call Get Card by ID before every payment to fetch the current token. Sending card_id skips that call, since Getnet resolves the current token for you. The subsequent-payment steps below show both.

Flow 1: Tokenize before payment

In this flow, you tokenize the card, save it to the vault, and then use it in your payment requests. Keeping these as separate steps lets you handle tokenization and vault storage apart from payment processing.

Process overview

The flow has four steps:

Tokenize the card (optional): Use the tokenization endpoint to convert the raw card number into a secure token.
Save card to vault: Store the tokenized card in the Getnet vault.
Process first payment: Make the first payment using the tokenized card number and save the transaction_id from the response. Use credentials_on_file_type: "ONE_CLICK" for CIT or "RECURRING" for MIT.
Process subsequent payments: For all future payments, use credentials_on_file_type: "ONE_CLICK_PAYMENT" (CIT) or "RECURRING_PAYMENT" (MIT) and include the transaction_id from the first payment along with the stored card.

Step 1 (Optional): Tokenize card data

Tokenize the card before you process any payments. Tokenization replaces the raw card number with a secure token you can reuse for recurring charges, which keeps the card number out of your later requests and narrows your PCI DSS compliance scope.

This step is optional. The vault accepts either a tokenized number_token or the raw card number, so you can skip tokenization and send the raw card number straight to Step 2. Tokenize first only when you want to handle that step separately from vault storage.

You choose the customer_id yourself, it’s your identifier for the buyer. Use the same customer_id across the tokenization, vault, and payment requests for that customer.

Use the Card Tokenization endpoint to tokenize the card:

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

Example of response:

{
  "number_token": "dfe05208b105578c070f806c80abd3af09e246827d29b866cf4ce16c205849977c9496cbf0d0234f42339937f327747075f68763537b90b31389e01231d4d13c"
}

Save the number_token from the response. You use it in Step 2 to save the card to the vault, and from there it replaces the raw card number in every request.

For complete details on tokenization, see the Tokenization and Vault documentation.

Step 2: Save card to vault

Save the card to the Getnet vault with the Store Card in Vault endpoint.

When storing the card in the vault, include the following fields:

Field	Description	Required
`number_token`	Tokenized card number from Step 1. Send `number_token` or `number`.	Conditional
`number`	Raw card number (PAN). Send `number` or `number_token`.	Conditional
`brand`	Card brand (e.g., `"VISA"`, `"MASTERCARD"`)	Yes
`cardholder_name`	Cardholder name	Yes
`expiration_month`	Card expiration month	Yes
`expiration_year`	Card expiration year	Yes
`customer_id`	Customer ID you provide	Yes
`verify_card`	Set to `true` to verify the card	Recommended
`security_code`	Card security code (CVV) - required if `verify_card` is `true`	Conditional

Send either number_token or number, not both. Use number_token if you tokenized the card in Step 1, or send the raw card number to store the card without tokenizing it first.

Here is an example request to store the card in the vault:

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

The response includes a card_id you can use to reference the stored card later.

Example of response:

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

Save the card_id from the response, you use it to reference this card in later payments.

Step 3: Process the first payment

For the first payment, set credentials_on_file_type to match your transaction type:

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

Use the Create Payment endpoint:

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

The response includes a transaction_id. Save it — every subsequent payment for this card must reference it:

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

Example for MIT (Recurring):

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

Save the transaction_id from this first payment. Every subsequent payment must send it so Getnet can tie the charges to the same customer and payment method.

Note for Argentina: For Argentina, use the additional_data.recurring object instead of credentials_on_file_type. For the first transaction, set sequence: "FIRST" and include billing_period with the month and year (format: MM/YYYY or MMYYYY).

Step 4: Process subsequent payments

For every payment after the first, set the matching credentials_on_file_type value and include the transaction_id from the first payment:

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

Reuse the stored card the recommended way: send only its card_id (returned in Step 2) in the card block, and Getnet fills in the rest. You do not need to send number, brand, cardholder_name, expiration_month, expiration_year, or security_code. Getnet also resolves the current token for you, so you skip the extra Get Card by ID call to refresh the renewed number. Keep the first payment’s transaction_id in the request.

Use the Create Payment endpoint:

Example for 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": {
        "card_id": "e8ad2ae4-9e3e-4532-998f-1a5a11e56e58"
      }
    }
  }
}'

Example for MIT (Recurring):

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": {
        "card_id": "e8ad2ae4-9e3e-4532-998f-1a5a11e56e58"
      }
    }
  }
}'

The transaction_id you send must match the one from the original payment. That is what lets card brands and issuers relate each subsequent payment back to the first.

Note for Argentina: For Argentina, use the additional_data.recurring object instead of credentials_on_file_type. For subsequent transactions, set sequence: "SUBSEQUENT" and include transaction_identifier with the transaction identifier from the first payment, along with billing_period for the current billing period.

Flow 2: Tokenize during payment

In this flow, you send the raw card number in the payment request with save_card_data: true. Getnet tokenizes the card and stores it in the vault while it processes the payment, so tokenization, vault storage, and the charge happen in a single call.

Process overview

The flow has two steps:

Process first payment: Send the raw card number in the payment request with save_card_data: true and the right credentials_on_file_type value (ONE_CLICK for CIT or RECURRING for MIT). Getnet tokenizes the card and saves it to the vault as it processes the payment. Save the transaction_id from the response.
Process subsequent payments: For all future payments, use credentials_on_file_type: "ONE_CLICK_PAYMENT" (CIT) or "RECURRING_PAYMENT" (MIT) and include the transaction_id from the first payment along with the stored card.

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

Step 1: Process the first payment with card tokenization

For the first payment, send the raw card number along with save_card_data: true and the credentials_on_file_type value for your transaction type. Getnet tokenizes the card and saves it to the vault as it processes the payment.

The customer_id is your own identifier for the buyer. Use the same value for that customer across future payment requests.

Use the Create Payment endpoint:

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

The response includes a transaction_id and a card_id for the stored card. Save both: you send the transaction_id on every subsequent payment, and the card_id is how you reference the stored card later.

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

Example for MIT (Recurring):

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

When you send the raw card number with save_card_data: true, you must also send the card brand, cardholder_name, security_code, expiration_month, and expiration_year. Getnet tokenizes the card and saves it to the vault during payment processing.

Save the transaction_id from this first payment. Every subsequent payment must send it to identify the customer and their payment method.

Note for Argentina: For Argentina, use the additional_data.recurring object instead of credentials_on_file_type. For the first transaction, set sequence: "FIRST" and include billing_period with the month and year (format: MM/YYYY or MMYYYY).

Step 2: Process subsequent payments

For every payment after the first, set the matching credentials_on_file_type value and include the transaction_id from the first payment:

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

Reuse the stored card the recommended way: send only the card_id returned by the first payment (Step 1) in the card block, and Getnet fills in the rest. You do not need to send number, brand, cardholder_name, expiration_month, expiration_year, or security_code. Getnet also resolves the current token for you, so you skip the extra Get Card by ID call to refresh the renewed number. Keep the first payment’s transaction_id in the request.

Use the Create Payment endpoint:

Example for 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": {
        "card_id": "e8ad2ae4-9e3e-4532-998f-1a5a11e56e58"
      }
    }
  }
}'

Example for MIT (Recurring):

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": {
        "card_id": "e8ad2ae4-9e3e-4532-998f-1a5a11e56e58"
      }
    }
  }
}'

The transaction_id you send must match the one from the original payment. That is what lets card brands and issuers relate each subsequent payment back to the first.

Note for Argentina: For Argentina, use the additional_data.recurring object instead of credentials_on_file_type. For subsequent transactions, set sequence: "SUBSEQUENT" and include transaction_identifier with the transaction identifier from the first payment, along with billing_period for the current billing period.

Important considerations

A few things to keep in mind when working with tokenized payments:

The card must be stored in the Getnet vault before the first payment (Flow 1) or during it (Flow 2).
Tokenizing the card yourself is optional. In Flow 1 you can send the raw card number to the vault instead of a number_token; in Flow 2, save_card_data: true tokenizes and stores the card during the payment.
Always use the transaction_id from the first payment (ONE_CLICK or RECURRING) in all subsequent payment requests (ONE_CLICK_PAYMENT or RECURRING_PAYMENT).
To reuse a stored card in subsequent payments, send only its card_id in the card block. Getnet fills in the remaining card fields from the vault, so you do not need to resend the number_token or the other card details.
You are responsible for triggering each payment according to your business schedule.

Next steps

Now that you can create a tokenized payment, explore more of the Getnet Global API:

Learn about the Getnet Recurring Payments Engine
Read more about Recurring Payments
Explore the Tokenization and Vault documentation