> ## Documentation Index
> Fetch the complete documentation index at: https://developers.orchestrasolutions.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateway Tokenization

> Create payment gateway-native tokens for recurring payments.

<Info>
  This page is part of the **REST API Guides**. Using the JavaScript library instead? See [Payments Library Guides](/guides/library/setup).
</Info>

**Prerequisites:** [API key](/getting-started/generate-api-key) and [Payment Gateway Account](/getting-started/add-payment-provider) 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](/guides/rest-api/tokenization), which stores data in Orchestra's vault.

<Note>
  Not all payment gateways support tokenization. For a complete list of integrations that support gateway tokenization, see [Gateway Token Integrations](https://orchestrasolutions.com/integ-type/gateway-token/). You can also check your gateway's capabilities programmatically using the [List Gateways](/guides/rest-api/utilities/list-gateways) endpoint.
</Note>

## 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](/guides/rest-api/tokenization) |
| PCI scope reduction (any data)       | [String Tokenization](/guides/rest-api/tokenization) |

## Create a Gateway Token

**Endpoint**: `POST /PaymentGateway/tokenize`

<CodeGroup>
  ```javascript Node.js theme={null}
  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
  ```

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

  ```python Python theme={null}
  import requests

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

<Card title="Tokenize API Reference" icon="code" href="/api-reference/paymentgateway/perform-a-payment-gateway-tokenization-operation">
  Complete parameter reference for tokenization requests
</Card>

### Response

```json theme={null}
{
  "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:

```javascript theme={null}
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

| 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) |

## Related

<CardGroup cols={2}>
  <Card title="String Tokenization" icon="vault" href="/guides/rest-api/tokenization">
    Store any data in Orchestra's vault
  </Card>

  <Card title="Charge Payments" icon="credit-card" href="/guides/rest-api/charge">
    Use tokens in payment requests
  </Card>
</CardGroup>