Skip to main content
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. Check your gateway’s capabilities 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

​
Request Parameters

ParameterTypeRequiredDescription
cardobjectYesCard details to tokenize
paymentGatewayAccountNamestringConditionalStored gateway account name
paymentGatewayAccountobjectConditionalInline gateway credentials
payerDetailsobjectNoBilling information
certificateNamestringNoClient certificate if required
networkTokenBrandstringNoFor network tokens: Visa, MasterCard, or Amex

​
Card Object

FieldTypeRequiredDescription
cardNumberstringYesCard number (PAN)
cardHolderNamestringYesCardholder name
expirationMonthintegerYesTwo-digit month (1-12)
expirationYearintegerYesFour-digit year
cvvstringNoCard verification code

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

​
Response Codes

CodeDescription
200Success - token created
400Bad request - invalid parameters
401Not authenticated
409Gateway doesn’t support tokenization or rejected
500Error with payment gateway
503Temporary failure with payment gateway

​
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