Learn how to securely store payment details as tokens for future payments, subscriptions, and card-on-file transactions

Create Tokens

Tokenization allows you to store your customer's payment details securely. When a customer pays for the first time, you can save their payment method as a token and use it for future transactions without requiring them to re-enter their card details.

Prerequisites

Before creating tokens, ensure you have:

A Plexy account with API keys from the Plexy Dashboard
A shopper_id to identify the customer whose payment method you're storing

The shopper_id is a unique identifier you create to link payment methods to a specific customer. This is required for all tokenization operations.

Token Types

Plexy supports three types of tokens based on how you intend to use them:

Token Type	Use Case	Shopper Present	Example
CardOnFile	Customer-initiated payments with saved card	Yes	One-click checkout
Subscription	Fixed-amount recurring charges	No	Monthly subscription
UnscheduledCardOnFile	Variable-amount merchant-initiated charges	No	Usage-based billing, account top-ups

CardOnFile

Use this when the customer will be present and actively initiating the payment, such as:

One-click checkout on your website
Reordering previous purchases
Express checkout in mobile apps

Subscription

Use this for predictable, scheduled recurring payments where:

The amount is fixed or known in advance
Payments occur on a regular schedule
The customer has agreed to automatic billing

UnscheduledCardOnFile

Use this for merchant-initiated transactions where:

The payment amount varies
The timing is irregular or triggered by events
Examples include: usage charges, account top-ups, pay-as-you-go services

Creating a Token During Payment

The most common way to create a token is during the initial payment. Set store_payment_method to true and specify the token type.

curl -X POST https://api.plexypay.com/v2/payments \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "KZT",
    "payment_method": {
      "type": "card",
      "card": {
        "number": "4111111111111111",
        "exp_month": 12,
        "exp_year": 2028,
        "cvc": "123"
      }
    },
    "shopper_id": "shopper_123456",
    "store_payment_method": true,
    "recurring_processing_model": "CardOnFile",
    "shopper_interaction": "Ecommerce",
    "return_url": "https://yoursite.com/checkout/complete",
    "metadata": {
      "order_id": "order_789"
    }
  }'

Response

{
  "id": "pay_abc123def456",
  "status": "authorized",
  "amount": 10000,
  "currency": "KZT",
  "token_id": "tok_card_visa_4242",
  "shopper_id": "shopper_123456",
  "payment_method": {
    "type": "card",
    "card": {
      "brand": "visa",
      "last4": "1111",
      "exp_month": 12,
      "exp_year": 2028,
      "funding": "credit"
    }
  },
  "recurring_processing_model": "CardOnFile",
  "created_at": "2026-03-25T10:30:00Z"
}

The token_id in the response is what you'll use for future payments. Store this securely along with the shopper_id in your database.

Creating a Token Without Payment

You can also create a token without processing a payment. This is useful for:

Saving a card for future use before the customer makes a purchase
Validating a card before a subscription starts
Setting up a backup payment method

curl -X POST https://api.plexypay.com/v2/tokens \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": {
      "type": "card",
      "card": {
        "number": "4111111111111111",
        "exp_month": 12,
        "exp_year": 2028,
        "cvc": "123"
      }
    },
    "shopper_id": "shopper_123456",
    "recurring_processing_model": "Subscription",
    "verify": true
  }'

Response

{
  "id": "tok_card_visa_5678",
  "type": "card",
  "shopper_id": "shopper_123456",
  "recurring_processing_model": "Subscription",
  "card": {
    "brand": "visa",
    "last4": "1111",
    "exp_month": 12,
    "exp_year": 2028,
    "funding": "credit"
  },
  "verified": true,
  "created_at": "2026-03-25T10:35:00Z"
}

Setting verify: true performs a zero-amount authorization to validate the card. This ensures the card is valid and can be charged, but some card issuers may show a temporary hold to the cardholder.

Using Plexy Checkout for Tokenization

For PCI compliance and a better user experience, use Plexy Checkout to collect card details securely.

Create a checkout session with tokenization enabled.

curl -X POST https://api.plexypay.com/v2/checkout/sessions \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mode": "setup",
"shopper_id": "shopper_123456",
"recurring_processing_model": "CardOnFile",
"success_url": "https://yoursite.com/setup/success",
"cancel_url": "https://yoursite.com/setup/cancel"
}'

Redirect the customer to the checkout URL returned in the response.

// On your frontend
window.location.href = session.url;

After the customer completes the checkout, Plexy sends a webhook with the token details.

curl -X POST https://your-app.example.com/webhooks/plexy \
  -H "Plexy-Signature: t=1716640000,v1=ab12cd34ef5678..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "checkout.session.completed",
    "data": {
      "session_id": "ses_abc123",
      "shopper_id": "shopper_123456",
      "token_id": "tok_xyz789"
    }
  }'

Verify the signature

Compute HMAC-SHA256(<raw request body>, <your webhook secret>), hex-encode the result, and compare against the v1= value in the Plexy-Signature header using a constant-time comparison. Reject the request if they differ. Then read data.token_id and data.shopper_id from the verified body to associate the new token with the customer in your records.

Request Parameters

Parameter	Type	Required	Description
`payment_method`	object	Yes	The payment method details to tokenize
`shopper_id`	string	Yes	Your unique identifier for the customer
`store_payment_method`	boolean	No	Set to `true` to create a token (default: `false`)
`recurring_processing_model`	string	Yes*	Token type: `CardOnFile`, `Subscription`, or `UnscheduledCardOnFile`
`shopper_interaction`	string	No	`Ecommerce` (online) or `ContractPresent` (in-person)
`verify`	boolean	No	Validate the card with a zero-amount auth

*Required when store_payment_method is true

Choosing the Right Token Type

Customer initiates: Use CardOnFile
Merchant initiates: Use Subscription or UnscheduledCardOnFile

Fixed amount, regular schedule: Use Subscription
Variable amount or irregular timing: Use UnscheduledCardOnFile

Error Handling

curl -X POST https://api.plexypay.com/v2/tokens \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": { },
    "shopper_id": "shopper_123456",
    "recurring_processing_model": "CardOnFile"
  }'

If the request fails, the API returns an error object with a code field. Common error codes include card_declined, invalid_card_number, and expired_card.

Testing

Use these test card numbers to verify your tokenization integration:

Card Number	Scenario
`4111 1111 1111 1111`	Successful tokenization
`4000 0000 0000 0002`	Card declined
`4000 0000 0000 0069`	Expired card
`4000 0000 0000 0127`	Invalid CVC

Next Steps

Now that you can create tokens, learn how to use them:

Make Token Payments - Process payments using saved tokens
Manage Tokens - List, update, and delete tokens

Create Tokens

On this page