Tokenization

This page is part of the REST API Guides. Using the JavaScript library instead? See Payments Library Guides.

Prerequisites: API key configured. The StringTokens service lets you tokenize and store any sensitive string: card numbers, full card details as JSON, addresses, or any data up to 16,384 characters. The token can then be used in place of the raw data in subsequent API calls.

PCI Compliance: If you store card details and later retrieve them, your system is exposed to raw card data and is in scope for PCI compliance. Consider using tokens only for storage and referencing them in payment requests without retrieval.

Why Tokenize

Security: Sensitive data stays in Orchestra’s vault, not your systems
Compliance: Reduces PCI scope when storing card numbers
Flexibility: Store any string data (card numbers, JSON, addresses)

Security Best Practice: Store each piece of sensitive data in its own individual token rather than combining multiple values into a single token. For example, create separate tokens for the card PAN, CVV, and cardholder ID. This approach limits exposure if a token is compromised and provides more granular control over data access and lifecycle management.

Create a Token

Store a string and receive a token reference. Endpoint: POST /StringTokens

const response = await fetch('https://api.orchestrasolutions.com/StringTokens', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    payload: '4111111111111111'
  })
});

const result = await response.json();
// result.token = 'nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO'

curl -X POST https://api.orchestrasolutions.com/StringTokens \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "payload": "4111111111111111"
  }'

import requests

response = requests.post(
    'https://api.orchestrasolutions.com/StringTokens',
    headers={
        'Content-Type': 'application/json',
        'X-Api-Key': 'YOUR_API_KEY'
    },
    json={
        'payload': '4111111111111111'
    }
)

StringTokens API Reference

Complete parameter reference and response fields

Retrieve Token Contents

Retrieve the original string stored behind a token. Endpoint: GET /StringTokens/{token}

Retrieving token contents exposes your system to the raw data. If you stored card details, this puts you in scope for PCI compliance.

const response = await fetch('https://api.orchestrasolutions.com/StringTokens/nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY'
  }
});

const result = await response.json();
// result.clearPayload = '4111111111111111'

curl https://api.orchestrasolutions.com/StringTokens/nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO \
  -H "X-Api-Key: YOUR_API_KEY"

response = requests.get(
    'https://api.orchestrasolutions.com/StringTokens/nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO',
    headers={
        'X-Api-Key': 'YOUR_API_KEY'
    }
)

Retrieve Token Metadata

Get metadata about a token without retrieving the actual contents. Endpoint: GET /StringTokens/{token}/meta

const response = await fetch('https://api.orchestrasolutions.com/StringTokens/nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO/meta', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY'
  }
});

Delete a Token

Permanently delete a stored token. Endpoint: DELETE /StringTokens/{token}

Deletion cannot be undone. Once deleted, the token and its contents are permanently removed.

const response = await fetch('https://api.orchestrasolutions.com/StringTokens/nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO', {
  method: 'DELETE',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY'
  }
});

curl -X DELETE https://api.orchestrasolutions.com/StringTokens/nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO \
  -H "X-Api-Key: YOUR_API_KEY"

response = requests.delete(
    'https://api.orchestrasolutions.com/StringTokens/nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO',
    headers={
        'X-Api-Key': 'YOUR_API_KEY'
    }
)

Using Tokens with Payment Gateway

Reference a token in the cardNumber field with an @ prefix when making payment requests:

const response = await fetch('https://api.orchestrasolutions.com/PaymentGateway/charge', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    amount: 25.00,
    currency: 'USD',
    paymentGatewayAccountName: 'stripeProduction',
    card: {
      cardNumber: '@nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO',  // Token with @ prefix
      cardHolderName: 'Jane Smith',
      expirationMonth: 12,
      expirationYear: 2027,
      cvv: '123'
    }
  })
});

The payment gateway retrieves the card number from the token automatically. Your system never sees the raw card number.

The @ prefix tells Orchestra to look up the token value. Without it, the string is treated as a literal card number.

Storing Full Card Details

You can store any string, including JSON-stringified card details:

const cardDetails = JSON.stringify({
  cardNumber: '4111111111111111',
  cardHolderName: 'Jane Smith',
  expirationMonth: 12,
  expirationYear: 2027
});

const response = await fetch('https://api.orchestrasolutions.com/StringTokens', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    payload: cardDetails
  })
});

Charge Payments

Use tokens in payment requests

StringTokens API

Full endpoint documentation

Start Here

Beyond the Quickstart

Concepts

Orchestra Payments Library Guides

Orchestra REST API Guides

Utilities

Merchant Account Setup

Support

Changelog

Why Tokenize

Create a Token

StringTokens API Reference

Retrieve Token Contents

Retrieve Token Metadata

Delete a Token

Using Tokens with Payment Gateway

Storing Full Card Details

Charge Payments

StringTokens API

​Why Tokenize

​Create a Token

StringTokens API Reference

​Retrieve Token Contents

​Retrieve Token Metadata

​Delete a Token

​Using Tokens with Payment Gateway

​Storing Full Card Details

​Related

Charge Payments

StringTokens API

Why Tokenize

Create a Token

Retrieve Token Contents

Retrieve Token Metadata

Delete a Token

Using Tokens with Payment Gateway

Storing Full Card Details

Related