# 

## What is a stored payment method

A stored payment method is a tokenized card or bank account associated with a customer. Once stored, it can be reused for future transactions without the person re-entering their payment details.

Each stored payment method has:

* A **payment token** — the unique identifier used in transactions
* A **customer association** — linked to a `customer_id`
* A **status** — tracks whether the method is usable
* **Masked details** — last four digits, brand, account type (never the full sensitive data)


## Token lifecycle

Stored payment methods move through a series of statuses over their lifetime.

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

| Status | Description | Can be used in transactions |
|  --- | --- | --- |
| `active` | Valid and ready for use | Yes |
| `verification_pending` | Awaiting bank account verification | No |
| `verification_failed` | Bank account verification did not pass | No |
| `expired` | Card expiry date has passed | No |
| `inactive` | Soft-deleted by the merchant | No |


## Managing stored payment methods

The Payment Tokens API (`/v1/payment_tokens`) provides full CRUD operations.

### Create

Store a new card or bank account with `POST /v1/payment_tokens`.

```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"
    }
  }
}
```

The response includes the `payment_token`, masked card details (`last_four`, `brand`, `bin`, `funding`), and AVS results if address data was provided.

### List

Retrieve all stored payment methods for a customer with `GET /v1/payment_tokens`.

| Parameter | Type | Description |
|  --- | --- | --- |
| `customer_id` | string | Filter by customer |
| `type` | string | `card` or `bank_account` |
| `status` | string | `active`, `expired`, `inactive`, `verification_pending`, `verification_failed` |
| `page` | integer | Page number |
| `per_page` | integer | Results per page |


```shell
curl -X GET \
  "https://api.dev.paradisegateway.net/v1/payment_tokens?customer_id=CUSTOMER-01KFDKXMQ637EKEAY410MSQSXB&type=card&status=active" \
  -H "APIKEY: YOUR-API-KEY"
```

### Retrieve

Get details for a single token with `GET /v1/payment_tokens/{token}`.

```shell
curl -X GET \
  https://api.dev.paradisegateway.net/v1/payment_tokens/PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB \
  -H "APIKEY: YOUR-API-KEY"
```

The response returns masked details only — raw sensitive data is never exposed.

### Update

Update metadata for a stored token with `POST /v1/payment_tokens/{token}`. Supported updates include:

* **Nickname** — a friendly label for the payment method
* **Default status** — mark as the customer's default method
* **Card expiry** — update `expiry_month` and `expiry_year` when a card is renewed


```json
POST /v1/payment_tokens/PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB

{
  "nickname": "Updated Business Visa",
  "is_default": true,
  "card": {
    "expiry_month": "06",
    "expiry_year": "2029"
  }
}
```

### Delete (soft)

Deactivate a stored payment method with `DELETE /v1/payment_tokens/{token}`.

```shell
curl -X DELETE \
  https://api.dev.paradisegateway.net/v1/payment_tokens/PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB \
  -H "APIKEY: YOUR-API-KEY"
```

The token is marked as `inactive` and retained for audit purposes. It cannot be used for new transactions. This operation is not reversible — once deleted, the token cannot be reactivated.

Soft delete only
Paradise Pay does not permanently purge token records. Deleted tokens remain in the system with `inactive` status for compliance and audit trail purposes.

## Default payment method

Each customer can have one default payment method per type (card, bank account). Set `is_default: true` when creating or updating a token. If another token of the same type was previously the default, it is automatically demoted.

## Vault storage

The token vault stores sensitive payment data using AES-256 encryption at rest. Data is encrypted before storage and decrypted only at transaction time within the PCI-compliant environment.

| Security layer | Implementation |
|  --- | --- |
| Encryption at rest | AES-256 CBC |
| Encryption in transit | TLS 1.2+ |
| Access control | Tokens scoped to merchant MID |
| Data isolation | Multi-tenant with per-merchant encryption keys |
| Audit logging | All create, read, update, delete events logged |


For more information, see [About data protection](/docs/concepts/security-compliance/data-protection).

## Using stored methods in transactions

Reference the token in the `payment_method` field of any transaction request.

```json
{
  "type": "sale",
  "amount": 2500,
  "payment_method": {
    "type": "token",
    "payment_token": "PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB"
  },
  "recurring": true
}
```

Set `recurring: true` for subsequent charges on a stored method to comply with card network rules for merchant-initiated transactions.

## Best practices

* **Tokenize early** — store the payment method at account creation or first purchase.
* **Use nicknames** — help persons identify their stored methods ("Personal Visa ending 1234").
* **Monitor expiry** — query for tokens with `status: expired` and prompt persons to update their card details.
* **Clean up** — delete tokens when a person removes a payment method or closes their account.
* **Set defaults** — use `is_default` to streamline repeat checkout flows.


## Further reading

* [About tokenization](/docs/concepts/tokenization/what-is-tokenization)
* [About PCI-DSS compliance](/docs/concepts/security-compliance/pci-dss-overview)
* [About the transaction lifecycle](/docs/concepts/transactions/transaction-lifecycle)