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

# Tokens

> Tokenizing card and ACH payment data before sending it to your server.

## Overview

A token is a secure, single-use reference to raw payment data. Instead of passing card numbers or bank account details through your server, you tokenize them first using your **Public API key** from the browser or client. The resulting token is a UUID you can pass to any transaction endpoint.

Tokenization keeps sensitive payment data off your servers, reducing your PCI scope.

<Info>
  Tokens are created client-side using your **Public API key**. All transaction endpoints use your **Private API key** server-side.
</Info>

***

## Create a Token

<CodeGroup>
  ```bash Card theme={null} theme={null}
  curl -X POST https://api.ecrypt.com/v1/tokens \
    -H "X-Api-Key: {{public_api_key}}" \
    -H "Content-Type: application/json" \
    -d '{
      "credit_card": {
        "name_on_card": "Jane Smith",
        "account_number": "4111111111111111",
        "expires": "1235",
        "verification_value": "123",
        "postal_code": "90210"
      }
    }'
  ```

  ```bash ACH theme={null} theme={null}
  curl -X POST https://api.ecrypt.com/v1/tokens \
    -H "X-Api-Key: {{public_api_key}}" \
    -H "Content-Type: application/json" \
    -d '{
      "check": {
        "name": "Jane Smith",
        "account_number": "123456789",
        "routing_number": "021000021",
        "account_type": "Checking"
      }
    }'
  ```
</CodeGroup>

### Request Body

Submit either a `creditCard` or `check` object. Do not submit both.

#### Credit Card

| Field                | Type   | Required | Description                                                   |
| -------------------- | ------ | -------- | ------------------------------------------------------------- |
| `account_number`     | string | Yes      | Card PAN. 13-20 digits.                                       |
| `expires`            | string | Yes      | Expiration in `MMYY` format. Example: `1235` = December 2035. |
| `verification_value` | string | No       | CVV or CVC. 3 or 4 digits.                                    |
| `postal_code`        | string | No       | Billing postal code. Used for AVS.                            |
| `name_on_card`       | string | No       | Cardholder name as it appears on the card.                    |

#### ACH / Check

| Field            | Type    | Required | Description                       |
| ---------------- | ------- | -------- | --------------------------------- |
| `account_number` | string  | Yes      | Bank account number. 7-20 digits. |
| `routing_number` | string  | Yes      | ABA routing number. 8-20 digits.  |
| `account_type`   | integer | No       | `0` = Checking, `1` = Savings.    |
| `name`           | string  | No       | Name on the bank account.         |
| `check_number`   | string  | No       | Check number. Up to 8 digits.     |

***

## Response

```json theme={null} theme={null}
{
  "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "metadata": {
    "credit_card_number": "4***********1111",
    "credit_card_network": "visa",
    "credit_card_type": "credit"
  },
  "request_id": "abc123xyz"
}
```

| Field                 | Description                                                              |
| --------------------- | ------------------------------------------------------------------------ |
| `token`               | UUID to use in transaction or wallet requests.                           |
| `credit_card_number`  | Masked card number.                                                      |
| `credit_card_network` | Card network: `visa`, `mastercard`, `discover card`, `american express`. |
| `credit_card_type`    | Card type: `credit`, `debit`, or `pre-paid`.                             |
| `account_number`      | Masked ACH account number (ACH tokens only).                             |

***

## Using a Token

Pass the token in the `payment.token` field of any transaction request.

```json Sale with token theme={null} theme={null}
{
  "payment": {
    "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "amount": {
    "value": 49.99,
    "currency": 840
  }
}
```

Tokens are valid for a single transaction. If you need to charge the same payment method again, store it to a customer wallet instead.

***

## Storing a Token to a Wallet

To reuse a payment method, add the token to a customer's wallet. Wallet entries are stored securely in ECRYPT's vault and can be charged at any time.

```bash theme={null} theme={null}
curl -X POST https://api.ecrypt.com/v1/customers/{{customer_id}}/wallet \
  -H "X-Api-Key: {{private_api_key}}" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "default": true
  }'
```

Once stored, charge the customer by referencing the `customer` or `wallet` ID in `payment.stored` rather than a token.

<Card title="Customer Wallet" icon="wallet" href="/customers/customer-wallet">
  Learn how to manage stored payment methods and charge customers on file.
</Card>

***

## Integration Patterns

**Hosted Checkout**-- ECRYPT's hosted iframe and Dynamic Checkout Page tokenizes card data automatically and returns a token. You never handle raw card data.

**Terminal** -- Card-present transactions via ECRYPT terminals do not use the token endpoint. The terminal handles card data capture and communicates directly with the gateway. See the [Terminal Guide](/in-person-payments/terminal-overview) for details.

***

## Security Notes

* Always create tokens client-side. Never send raw card numbers to your server.
* Your Public API key can only be used to create tokens. It cannot initiate transactions or access account data.
* Tokens are single-use. A token that has already been used in a transaction cannot be used again.
* To meet PCI DSS requirements, do not log or store raw card numbers at any point in your integration.