# 

## Prerequisites

* A valid API key — see [Obtain API credentials](/docs/how-tos/setup/obtain-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
```shell
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"
      }
    }
  }'
```

Python
```python
import requests

resp = requests.post(
    "https://api.dev.paradisegateway.net/v1/payment_tokens",
    headers={"Content-Type": "application/json", "APIKEY": "YOUR-API-KEY"},
    json={
        "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"},
        },
    },
)
print(resp.json())
```

JavaScript
```javascript
const resp = await fetch(
  "https://api.dev.paradisegateway.net/v1/payment_tokens",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "APIKEY": "YOUR-API-KEY",
    },
    body: JSON.stringify({
      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" },
      },
    }),
  }
);
console.log(await resp.json());
```

C#
```csharp
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("APIKEY", "YOUR-API-KEY");

var payload = new
{
    customer_id = "CUSTOMER-01KFDKXMQ637EKEAY410MSQSXB",
    is_default = true,
    nickname = "My Business Visa",
    card = new
    {
        pan = "4111111111111111",
        expiry_month = "12",
        expiry_year = "2027",
        cardholder_name = "John A Doe",
        address = new { line1 = "123 Main St", zip = "62704" }
    }
};
var resp = await client.PostAsJsonAsync(
    "https://api.dev.paradisegateway.net/v1/payment_tokens", payload);
Console.WriteLine(await resp.Content.ReadAsStringAsync());
```

Java
```java
HttpClient client = HttpClient.newHttpClient();
String body = """
    {
      "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" }
      }
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dev.paradisegateway.net/v1/payment_tokens"))
    .header("Content-Type", "application/json")
    .header("APIKEY", "YOUR-API-KEY")
    .POST(HttpRequest.BodyPublishers.ofString(body)).build();
HttpResponse<String> resp = client.send(request,
    HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());
```

Go
```go
payload := strings.NewReader(`{
  "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" }
  }
}`)
req, _ := http.NewRequest("POST",
    "https://api.dev.paradisegateway.net/v1/payment_tokens", payload)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("APIKEY", "YOUR-API-KEY")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
```

PHP
```php
$ch = curl_init("https://api.dev.paradisegateway.net/v1/payment_tokens");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["Content-Type: application/json", "APIKEY: YOUR-API-KEY"],
    CURLOPT_POSTFIELDS => json_encode([
        "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"],
        ],
    ]),
]);
echo curl_exec($ch); curl_close($ch);
```

Ruby
```ruby
require "net/http"; require "json"
uri = URI("https://api.dev.paradisegateway.net/v1/payment_tokens")
req = Net::HTTP::Post.new(uri, {
  "Content-Type" => "application/json", "APIKEY" => "YOUR-API-KEY",
})
req.body = {
  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" },
  },
}.to_json
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts resp.body
```

## Step 3: Handle the response

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

```json
{
  "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](/docs/how-tos/process-payments/process-payment-with-token)
* [Update stored payment method](/docs/how-tos/tokenization-vaulting/update-payment-method) — change expiry or nickname
* [About tokenization](/docs/concepts/tokenization/what-is-tokenization)