# 

## How tokenization works

When a person provides a card number or bank account,Reefpay stores the sensitive data in a PCI-compliant vault and returns a token — an opaque identifier that maps back to the original data. You store the token instead of the raw payment credentials.

![image](https://files.modern-mermaid.live/images/1776270522624-mermaid-diagram-1776270522770.png)

The token format is `PAYMENT_TOKEN-` followed by a 26-character alphanumeric string (for example, `PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB`). Tokens are not reversible — you cannot derive the original payment data from a token.

## Why tokenize

### Reduce PCI scope

PCI-DSS requires any system that stores, processes, or transmits cardholder data to meet strict security controls. By sending raw card data directly toReefpay and storing only the returned token, your systems never hold sensitive data. This dramatically reduces your compliance burden.

| Without tokenization | With tokenization |
|  --- | --- |
| Your servers store PANs and CVVs | OnlyReefpay vault stores sensitive data |
| Full PCI-DSS SAQ D assessment | Reduced PCI-DSS SAQ A or SAQ A-EP |
| Encryption, key management, access controls required on your side | Token storage needs no special PCI controls |
| Risk of data breach exposing payment data | Breached tokens are useless to attackers |


### Enable recurring and returning-customer payments

Tokens let you charge a person again without asking them to re-enter payment details. Store the token at account creation and reference it for future transactions.

### Simplify refunds and adjustments

Refund a previous transaction or issue a credit using the original token — no need to collect payment details again.

## What gets tokenized

Paradise Pay tokenizes both card and bank account payment methods.

| Payment method | Sensitive fields stored in vault | Returned in token response |
|  --- | --- | --- |
| Card | PAN, expiry, CVV, cardholder name | `payment_token`, `last_four`, `brand`, `bin`, `funding` |
| Bank account | Account number, routing number | `payment_token`, `last_four`, `account_type` |


Sensitive fields are **write-only** — the API never echoes back a full PAN, CVV, account number, or routing number in any response.

## Creating a token

### Card token

```json
POST /v1/payment_tokens

{
  "customer_id": "CUSTOMER-01KFDKXMQ637EKEAY410MSQSXB",
  "is_default": true,
  "nickname": "My Business Visa",
  "card": {
    "pan": "4111111111111111",
    "expiry_month": "12",
    "expiry_year": "2027",
    "cardholder_name": "John A Doe",
    "address": {
      "line1": "123 Main St",
      "zip": "62704"
    }
  }
}
```

### Bank account token

```json
POST /v1/payment_tokens

{
  "customer_id": "CUSTOMER-01KFDKXMQ637EKEAY410MSQSXB",
  "nickname": "Business Checking",
  "bank_account": {
    "routing_number": "021000021",
    "account_number": "123456789012",
    "account_type": "checking",
    "name": "John Doe",
    "email": "john.doe@example.com"
  }
}
```

Both requests return a `201 Created` response with the `payment_token` and masked details.

## Automatic tokenization

When you process a transaction with raw card data (inline PAN),Reefpay automatically tokenizes the card and includes the `payment_token` in the response. You can use this token for subsequent transactions without a separate tokenization call.

```json
{
  "id": "TRANSACTION-01JMRSPCK7XVNP3KS8F2W4T6Y",
  "type": "sale",
  "transaction_state": "authorized",
  "payment_method": {
    "type": "card",
    "payment_token": "PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB",
    "brand": "visa",
    "last_four": "1234",
    "bin": "411111",
    "funding": "credit"
  }
}
```

## Using a token in a transaction

Reference the token instead of raw payment data.

```json
POST /v1/transactions

{
  "type": "card_sale",
  "amount": 1999,
  "payment_method": {
    "type": "token",
    "payment_token": "PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB"
  }
}
```

The gateway resolves the token to the stored card or bank account and processes the transaction.

## Token security properties

* **Opaque**: Tokens contain no encoded payment data; they are random identifiers.
* **Scoped**: Tokens are bound to a specific merchant (MID) and cannot be used across merchants.
* **Non-reversible**: There is no API to retrieve the original PAN or account number from a token.
* **Auditable**: Token creation, usage, and deletion events are logged for compliance.


## Further reading

* [About stored payment methods](/docs/concepts/tokenization/stored-payment-methods)
* [About PCI-DSS compliance](/docs/concepts/security-compliance/pci-dss-overview)
* [About data protection](/docs/concepts/security-compliance/data-protection)