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

# Store Card Tokens for Future Payments

> Tokenize one or more cards without charging them. Each token is scoped to your merchant account and reusable for future payments.

`POST /token` lets you store card details as reusable tokens without processing a payment. Use it to pre-vault cards during account setup flows, or to migrate stored cards from another provider. Each token is scoped to your merchant account and stored with BIN data (brand, type, issuer).

<Note>
  To tokenize a card during a payment, add `card.cardData.tokenize: true` to your payment request instead — see [Tokenization concepts](/concepts/tokenization).
</Note>

Each entry in `tokens[]` must carry a `card` with either `cardData` (raw fields — server-side/PCI-compliant environments only) or `nonceData` (an SDK-generated nonce, for browser flows). A successful request returns `200 OK` with the merchant code, the echoed `shopper`, and one created token object per entry (`id` prefixed `vt_`, masked `cardData`, `expirationDate`, `tokenCreationReference`) — same order as the request.

<RequestExample>
  ```bash cURL theme={"dark"}
  curl -X POST https://api.therius.io/v1/token \
    -H "Authorization: Bearer prv_production_your_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "merchantCode": "MERCHANT_001",
      "shopper": { "id": "customer-42", "email": "ada@example.com" },
      "tokens": [{
        "card": {
          "cardData": {
            "cardNumber": "4111111111111111",
            "cardholderName": "Ada Lovelace",
            "expiryMonth": "12",
            "expiryYear": "2030",
            "cvv": "123"
          }
        }
      }]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={"dark"}
  {
    "merchantCode": "MERCHANT_001",
    "shopper": { "id": "customer-42", "email": "ada@example.com" },
    "tokens": [{
      "id": "vt_abc123xyz",
      "card": {
        "cardData": { "brand": "visa", "cardNumber": "411111****1111", "type": "credit" }
      },
      "expirationDate": "2030-12"
    }]
  }
  ```
</ResponseExample>


## OpenAPI

````yaml POST /token
openapi: 3.1.0
info:
  title: Therius API
  description: REST API for payments, subscriptions, and billing plans.
  version: 1.0.0
servers:
  - url: https://api.therius.io/v1
    description: Production
  - url: https://api-sandbox.therius.io/v1
    description: Sandbox
security:
  - bearerAuth: []
paths:
  /token:
    post:
      tags:
        - Tokens
      summary: Store card tokens for future payments
      operationId: storeTokens
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - merchantCode
                - tokens
              properties:
                merchantCode:
                  type: string
                  description: Your merchant account identifier.
                shopper:
                  $ref: '#/components/schemas/Shopper'
                tokens:
                  type: array
                  description: >-
                    Cards to tokenize. Each entry carries a card instrument
                    (`cardData` or `nonceData`) and an optional
                    `expirationDate`.
                  items:
                    type: object
      responses:
        '200':
          description: Tokens created
          content:
            application/json:
              schema:
                type: object
                properties:
                  merchantCode:
                    type: string
                  shopper:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      email:
                        type: string
                  tokens:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: >-
                            Token ID - pass as `card.tokenData.token` on a
                            future charge.
                        expirationDate:
                          type: string
                          description: Token expiry.
                        tokenCreationReference:
                          type: string
                          description: Idempotency reference for this tokenization.
                        card:
                          type: object
                          description: >-
                            Masked card details: `cardData` with `brand`,
                            `type`, `cardNumber`, `issuingCountry`,
                            `issuerName`.
components:
  schemas:
    Shopper:
      type: object
      description: >-
        Shopper information. Required when tokenizing a card
        (`card.<instrument>.tokenize: true`).
      properties:
        id:
          type: string
          description: >-
            Your internal shopper ID. Used to associate saved tokens with a
            customer.
        email:
          type: string
          format: email
          description: Shopper's email address.
        name:
          type: string
          description: Shopper's full name.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your secret API key: `Bearer prv_production_xxx` (production) or `Bearer
        prv_sandbox_xxx` (sandbox).

````