About stored payment methods

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)

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

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

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

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.

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

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

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

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

POST /v1/payment_tokens/PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB

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

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

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.

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.

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.

For more information, see About data protection.

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

{
  "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.

• 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.

• About tokenization
• About PCI-DSS compliance
• About the transaction lifecycle