Skip to main content
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'

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.payload = '4111111111111111'

​
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'
  }
});

​
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: 'stripe-production',
    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