Gateway Tokenization

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 Case	Solution
Recurring subscriptions	Gateway tokenization
Stored cards for returning customers	Gateway tokenization
Temporary storage during checkout	String 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: 'stripeProduction',
    card: {
      cardNumber: '4111111111111111',
      cardHolderName: 'Jane Smith',
      expirationMonth: 12,
      expirationYear: 2027,
      cvv: '123'
    }
  })
});

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

curl -X POST https://api.orchestrasolutions.com/PaymentGateway/tokenize \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "paymentGatewayAccountName": "stripeProduction",
    "card": {
      "cardNumber": "4111111111111111",
      "cardHolderName": "Jane Smith",
      "expirationMonth": 12,
      "expirationYear": 2027,
      "cvv": "123"
    }
  }'

import requests

response = requests.post(
    'https://api.orchestrasolutions.com/PaymentGateway/tokenize',
    headers={
        'Content-Type': 'application/json',
        'X-Api-Key': 'YOUR_API_KEY'
    },
    json={
        'paymentGatewayAccountName': 'stripeProduction',
        'card': {
            'cardNumber': '4111111111111111',
            'cardHolderName': 'Jane Smith',
            'expirationMonth': 12,
            'expirationYear': 2027,
            'cvv': '123'
        }
    }
)

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: 'stripeProduction',
    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

Feature	Gateway Token	String Token
Storage location	Payment processor	Orchestra vault
Use case	Recurring billing	PCI scope reduction
Portability	Tied to one gateway	Works across gateways
Data type	Card details only	Any string (up to 16KB)

String Tokenization

Store any data in Orchestra’s vault

Charge Payments

Use tokens in payment requests

Start Here

Beyond the Quickstart

Concepts

Orchestra Payments Library Guides

Orchestra REST API Guides

Utilities

Merchant Account Setup

Support

Changelog

When to Use Gateway Tokens

Create a Gateway Token

Tokenize API Reference

Response

Using Gateway Tokens

Gateway Token vs String Token

String Tokenization

Charge Payments

​When to Use Gateway Tokens

​Create a Gateway Token

Tokenize API Reference

​Response

​Using Gateway Tokens

​Gateway Token vs String Token

​Related

String Tokenization

Charge Payments

When to Use Gateway Tokens

Create a Gateway Token

Response

Using Gateway Tokens

Gateway Token vs String Token

Related