Tokenization

This page is part of the REST API Guides. Card capture happens in the frontend through the Payments Library; see the 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. A card stored here can be charged through any Payment Gateway Account you connect, so you can add or change providers without asking customers to re-enter their cards. Compare with Gateway Tokenization, where the token stays with one gateway.

The example below shows a raw card number in the payload field for completeness. Sending raw card data means it passes through your systems and puts you in PCI DSS scope. The standard integration captures the card with the Payments Library, which returns a token directly, so your backend does not need to tokenize a raw PAN through this endpoint itself. If you do store card details here and later retrieve them, your system is exposed to raw card data and is in scope for PCI compliance; use tokens only for storage and reference 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'
    }
)

Cards Already Stored at a Payment Provider

If your cards are already tokenized and stored by a payment provider, Orchestra has no control over them. What you can do with them depends on that provider’s capabilities and restrictions, and most providers do not let you take cards out. You can keep charging those cards through the same provider. Send the provider’s token in the userToken field of a charge or authorize request on that provider’s gateway account, as shown in Using Gateway Tokens. Orchestra passes the token to the provider unchanged. Whether the provider accepts a token that was created outside Orchestra depends on the provider, and on the provider account that created it. This works only for payment providers whose integration supports gateway tokens. New cards you tokenize in Orchestra are stored in Orchestra’s vault and can be used with any payment provider you connect.

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: '@YOUR_TOKEN',  // 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

Gateway Tokenization

Tokens that stay with one gateway

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

Cards Already Stored at a Payment Provider

Using Tokens with Payment Gateway

Storing Full Card Details

Charge Payments

StringTokens API

Gateway Tokenization

​Why Tokenize

​Create a Token

StringTokens API Reference

​Retrieve Token Contents

​Retrieve Token Metadata

​Delete a Token

​Cards Already Stored at a Payment Provider

​Using Tokens with Payment Gateway

​Storing Full Card Details

​Related

Charge Payments

StringTokens API

Gateway Tokenization

Why Tokenize

Create a Token

Retrieve Token Contents

Retrieve Token Metadata

Delete a Token

Cards Already Stored at a Payment Provider

Using Tokens with Payment Gateway

Storing Full Card Details

Related