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

​
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'

​
Request

ParameterTypeRequiredDescription
payloadstringYesThe string to tokenize (1-16,384 characters)

​
Response

{
  "token": "nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO",
  "createTime": "2024-01-15T10:30:00Z"
}
FieldTypeDescription
tokenstringToken ID to reference this stored string
createTimedatetimeWhen the token was created
HTTP Status: 201 Created

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

​
Response Codes

CodeDescription
201Created - token stored successfully
400Bad request - invalid payload
401Not authenticated
404Token not found

Charge Payments

Use tokens in payment requests

StringTokens API

Full endpoint documentation