Tokenization

Tokenization allows you to securely store customer payment information for future use. Rather than storing sensitive payment details, you store a token that represents those details, enhancing security and simplifying recurring payments.

How Tokenization Works

  1. A customer provides their payment information (through Pay Portal, Pay Session, or Pay API)
  2. Prahsys Payments securely captures the payment details
  3. The information is tokenized and stored in our secure vault
  4. A token is returned to your system to reference the payment method
  5. You use this token for future transactions, without handling sensitive payment data

Token Management Operations

The Tokenization API provides several endpoints for creating, retrieving, updating, and deleting tokens.

Creating a Token

There are multiple ways to create a token, depending on your integration method:

Session-Based Tokenization

When using Pay Portal or Pay Session, you can generate tokens from session data:

Server-side JavaScript - Using a session
const response = await fetch("https://api.prahsys.com/payments/n1/merchant/{merchantId}/token", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    session: {
      id: "SESSION0002742481646J67219140J7",
    },
  }),
});

NOTE: The session must have processed a transaction to tokenize the payment information.

Pay API Tokenization (Higher PCI Scope)

When using Pay API, you can tokenize card details directly (requires higher PCI compliance):

Server-side JavaScript - Using card details
const response = await fetch("https://api.prahsys.com/payments/n1/merchant/{merchantId}/token", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    sourceOfFunds: {
      card: {
        number: "4111111111111111",
        expiry: {
          month: "12",
          year: "25",
        },
        securityCode: "123",
      },
    },
  }),
});

Retrieving a Token

You can retrieve details about a token:

Server-side JavaScript
const response = await fetch(`https://api.prahsys.com/payments/n1/merchant/{merchantId}/token/${tokenId}`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
});

Updating a Token

You can update certain token attributes:

Server-side JavaScript
const response = await fetch(`https://api.prahsys.com/payments/n1/merchant/{merchantId}/token/${tokenId}`, {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    // Update card expiry date
    sourceOfFunds: {
      card: {
        expiry: {
          month: "12",
          year: "26",
        },
      },
    },
  }),
});

Deleting a Token

You can delete a token when it’s no longer needed:

Server-side JavaScript
const response = await fetch(`https://api.prahsys.com/payments/n1/merchant/{merchantId}/token/${tokenId}`, {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
});

Searching for Tokens

You can search for tokens associated with a customer:

Server-side JavaScript
const response = await fetch(
  "https://api.prahsys.com/payments/n1/merchant/{merchantId}/tokens?customerReference=CUST-456",
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  },
);
 
const tokens = await response.json();