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 and Payment Gateway Account with a gateway that supports tokenization. Gateway tokenization creates a token stored directly with your payment processor (Stripe, Adyen, etc.) for recurring billing. This is different from String Tokenization, which stores data in Orchestra’s vault.
Not all payment gateways support tokenization. For a complete list of integrations that support gateway tokenization, see Gateway Token Integrations. You can also check your gateway’s capabilities programmatically using the List Gateways endpoint.

​
When to Use Gateway Tokens

Use CaseSolution
Recurring subscriptionsGateway tokenization
Stored cards for returning customersGateway tokenization
Temporary storage during checkoutString Tokenization
PCI scope reduction (any data)String Tokenization

​
Create a Gateway Token

Endpoint: POST /PaymentGateway/tokenize 
const response = await fetch('https://api.orchestrasolutions.com/PaymentGateway/tokenize', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    paymentGatewayAccountName: 'stripe-production',
    card: {
      cardNumber: '4111111111111111',
      cardHolderName: 'Jane Smith',
      expirationMonth: 12,
      expirationYear: 2027,
      cvv: '123'
    }
  })
});

const result = await response.json();
// result.gatewayToken contains the processor-specific token

Tokenize API Reference

Complete parameter reference for tokenization requests

​
Response

{
  "operationType": "Tokenize",
  "operationResultCode": "Success",
  "operationResultDescription": "Token created",
  "gatewayName": "Stripe",
  "gatewayToken": "tok_1abc123...",
  "gatewayResultCode": "approved",
  "gatewayResultDescription": "Token created successfully"
}
The gatewayToken value is the processor-specific token you’ll use for future charges.

​
Using Gateway Tokens

Once you have a gateway token, use it with the userToken parameter in charge or authorize 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: 29.99,
    currency: 'USD',
    paymentGatewayAccountName: 'stripe-production',
    userToken: 'tok_1abc123...',  // Gateway token from tokenize
    card: {
      cardNumber: '4111111111111111',  // Can be masked/placeholder
      cardHolderName: 'Jane Smith',
      expirationMonth: 12,
      expirationYear: 2027
    }
  })
});

​
Gateway Token vs String Token

FeatureGateway TokenString Token
Storage locationPayment processorOrchestra vault
Use caseRecurring billingPCI scope reduction
PortabilityTied to one gatewayWorks across gateways
Data typeCard details onlyAny string (up to 16KB)

String Tokenization

Store any data in Orchestra’s vault

Charge Payments

Use tokens in payment requests