Store a card for future use

Prerequisites

A valid API key — see Obtain API credentials
The person's card details (PAN, expiry, cardholder name) and a customer_id

Step 1: Build the request

Field	Required	Description
`customer_id`	Yes	Your internal customer identifier
`is_default`	No	Set to `true` to make this the customer's default card
`nickname`	No	A friendly label (for example, "Personal Visa")
`card.pan`	Yes	Full card number
`card.expiry_month`	Yes	Two-digit expiry month
`card.expiry_year`	Yes	Four-digit expiry year
`card.cardholder_name`	Yes	Name on card
`card.address.line1`	Recommended	Billing street address (for AVS verification at tokenization)
`card.address.zip`	Recommended	Billing ZIP code

Step 2: Send the request

curl -X POST \
  https://api.dev.paradisegateway.net/v1/payment_tokens \
  -H "Content-Type: application/json" \
  -H "APIKEY: YOUR-API-KEY" \
  -d '{
    "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"
      }
    }
  }'

Step 3: Handle the response

A 201 Created response returns the token and masked card details.

{
  "payment_token": "PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB",
  "object": "payment_token",
  "type": "card",
  "status": "active",
  "customer_id": "CUSTOMER-01KFDKXMQ637EKEAY410MSQSXB",
  "is_default": true,
  "nickname": "My Business Visa",
  "card": {
    "brand": "visa",
    "last_four": "1111",
    "bin": "411111",
    "funding": "credit",
    "address_check": {
      "address_line1_match": "match",
      "address_zip_match": "match"
    }
  },
  "correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Save the payment_token value. Use it in future transactions with payment_method.type: payment_token.

AVS at tokenization

If you provide address data, Paradise Gateway verifies it with the card issuer at tokenization time. Check the address_check results to confirm the address matches before using the token.

Error responses

Status	Meaning
`400`	Invalid request (missing required fields)
`422`	Validation failed (invalid card number, expired card)

Next steps

Process a payment with a stored token
Update stored payment method — change expiry or nickname
About tokenization