Gateway 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 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.

These examples show raw card details 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 send a raw cardNumber to this 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.

Tokenize While Charging

You do not need a separate call to get a token. Add generateToken: true to a charge or authorize request and the response carries the gatewayToken alongside the payment result:

{
  "paymentGatewayAccountName": "stripeProduction",
  "amount": 29.00,
  "currency": "EUR",
  "myRef": "order-88421",
  "generateToken": true,
  "card": {
    "cardNumber": "@your-card-token",
    "cardHolderName": "Jane Smith",
    "expirationMonth": 12,
    "expirationYear": 2027
  }
}

This is the usual choice when the first payment and the saved card happen together, for example a subscription whose first month is charged at signup. It saves a round trip and avoids a second authorization against the card.

Use the standalone POST /PaymentGateway/tokenize call when you need a token without taking a payment, and generateToken when you are charging anyway. See Scheduled Payments for how the resulting token is used for recurring billing.

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: '@nQGywsQE9gbURtrXEjTZwtWqeMdK9nsO',  // Can be masked/placeholder, or a String Token
      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

Tokenize While Charging

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

​Tokenize While Charging

​Using Gateway Tokens

​Gateway Token vs String Token

​Related

String Tokenization

Charge Payments

When to Use Gateway Tokens

Create a Gateway Token

Response

Tokenize While Charging

Using Gateway Tokens

Gateway Token vs String Token

Related