Card Tokenizer Service API Integration Guide

This document provides detailed instructions for integrating with the publicly accessible endpoints of the Card Tokenizer Service API. These endpoints allow merchants to tokenize card data and manage tokenized cards securely, with support for iFrame integration for card input.

Base URL

The base URL for all API endpoints depends on the environment:

Sandbox: https://test-tokenizer.paymaster24.com
Production: https://tokenizer.paymaster24.com

Use the appropriate base URL for your environment in all requests described below.

Authentication

Some endpoints require authentication using an auth_token, which must be obtained via the /api/get-iframe-key endpoint. The auth_token is then passed in the Authorization header as a Bearer token for subsequent requests.

Step 1: Obtain an `auth_token`

Use the /api/get-iframe-key endpoint to generate an auth_token.

Request

Method: POST
Endpoint: /api/get-iframe-key
Content-Type: application/json
Body:
```
{
"login": "test@example.com",
"plain_text": "2025-04-25-12:00:00-550e8400-e29b-41d4-a716-446655440000",
"secret": "base64_encoded_sha256"
}
```
- login: A valid email address (e.g., test@example.com).
- plain_text: A unique string in the format YYYY-MM-DD-HH:mm:ss-<uuid> (e.g., 2025-04-25-12:00:00-550e8400-e29b-41d4-a716-446655440000).
- secret: A SHA256 hash in Base64 format, calculated as SHA256(login;plain_text;secret_code).

Example Secret Calculation:

const login = "test@example.com";
const plainText = "2025-04-25-12:00:00-550e8400-e29b-41d4-a716-446655440000";
const secretCode = "your_secret_code"; // Provided by the service
const hashInput = `${login};${plainText};${secretCode}`;
const secret = CryptoJS.SHA256(hashInput).toString(CryptoJS.enc.Base64);

Response

Status: 200 OK
Body:
```
{
"auth_token": "base64_encoded_sha256"
}
```
- auth_token: Use this value as the Bearer token in the Authorization header for other endpoints.

Error Responses:

400 Bad Request: Invalid input data.

{
"error": "plain_text must be unique"
}

401 Unauthorized: Invalid secret.
```
{
"error": "Authorization failed"
}
```

Example

curl -X POST https://test-tokenizer.paymaster24.com/api/get-iframe-key \
-H "Content-Type: application/json" \
-d '{
"login": "test@example.com",
"plain_text": "2025-04-25-12:00:00-550e8400-e29b-41d4-a716-446655440000",
"secret": "base64_encoded_sha256"
}'

Step 2: Set Up Authorization Header

Use the obtained auth_token in the Authorization header for all subsequent requests that require it:

Authorization: Bearer <auth_token>

Public Endpoints

1. Display Card Tokenizer iFrame (`GET /card-tokenizer`)

This endpoint renders an iFrame form for securely collecting card details.

Request

Method: GET
Endpoint: /card-tokenizer
Query Parameters:
- login (required): A valid email address (e.g., test@example.com).
- plain_text (required): A unique string in the format YYYY-MM-DD-HH:mm:ss-<uuid> (e.g., 2025-04-25-12:00:00-550e8400-e29b-41d4-a716-446655440000).
- secret (required): A SHA256 hash in Base64 format, calculated as SHA256(login;plain_text;secret_code).
- customer_id (required): The external customer ID (e.g., 1745915011).
- lang (optional): Language for the form (e.g., en, ru, de, fr, he, ar, es, it; defaults to en).
- post_url (optional): A URL to which a POST request will be sent with the tokenization result.
- cardholder_name (optional): The cardholder's name for verification purposes. If this field is empty or omitted, no cardholder name verification will be performed.

Response

Status: 200 OK
Content-Type: text/html
Body: An HTML page containing the card tokenizer form within an iFrame, along with the auth_token for use in subsequent requests.

Error Responses:

400 Bad Request: Invalid input parameters.
```
{
"error": "plain_text must be unique"
}
```
401 Unauthorized: Authorization failed.
```
{
"error": "Authorization failed"
}
```

Example

curl -X GET "https://test-tokenizer.paymaster24.com/card-tokenizer?login=test@example.com&plain_text=2025-04-25-12:00:00-550e8400-e29b-41d4-a716-446655440000&secret=base64_encoded_sha256&customer_id=1234597&lang=en&post_url=https://merchant.com/123"

2. Generate Authentication Token (`POST /api/get-iframe-key`)

This endpoint generates an auth_token for iFrame authorization and subsequent API requests.

Request

Method: POST
Endpoint: /api/get-iframe-key
Content-Type: application/json
Body:
```
{
"login": "test@example.com",
"plain_text": "2025-04-25-12:00:00-550e8400-e29b-41d4-a716-446655440000",
"secret": "base64_encoded_sha256"
}
```
- login: A valid email address (e.g., test@example.com).
- plain_text: A unique string in the format YYYY-MM-DD-HH:mm:ss-<uuid> (e.g., 2025-04-25-12:00:00-550e8400-e29b-41d4-a716-446655440000).
- secret: A SHA256 hash in Base64 format, calculated as SHA256(login;plain_text;secret_code).

Response

Status: 200 OK
Body:
```
{
"auth_token": "base64_encoded_sha256"
}
```
- auth_token: The token to be used in the Authorization header for authenticated requests.

Error Responses:

400 Bad Request: Invalid input data.

{
"error": "plain_text must be unique"
}

401 Unauthorized: Invalid secret.
```
{
"error": "Authorization failed"
}
```

Example

curl -X POST https://test-tokenizer.paymaster24.com/api/get-iframe-key \
-H "Content-Type: application/json" \
-d '{
"login": "test@example.com",
"plain_text": "2025-04-25-12:00:00-550e8400-e29b-41d4-a716-446655440000",
"secret": "base64_encoded_sha256"
}'

iFrame Integration

The /card-tokenizer endpoint provides an iFrame that can be embedded into a merchant's webpage to securely collect card details from customers. The iFrame handles card input and tokenization, ensuring that sensitive card data does not touch the merchant's servers.

Steps for iFrame Integration

Obtain Required Parameters:
- Generate a unique plain_text in the format YYYY-MM-DD-HH:mm:ss-<uuid>.
- Calculate the secret using the formula SHA256(login;plain_text;secret_code) with your provided secret_code.
- Use the merchant's email as the login.
- Optionally, provide a post_url for receiving tokenization results.
- cardholder_name (optional): The cardholder's name for verification purposes. If this field is empty or omitted, no cardholder name verification will be performed.
Embed the iFrame:
- Use the /card-tokenizer endpoint URL with the required query parameters.
- Embed the URL in an <iframe> tag on your webpage.
Handle Tokenization:
- After successful tokenization, the iFrame will display the result directly within itself. If a post_url is provided, the tokenization result will also be sent to that URL via a POST request.

Example iFrame Integration

Below is an example of how to integrate the card tokenizer iFrame into a merchant's webpage:

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Merchant Card Payment Page</title>
<style>
    iframe {
        width: 100%;
        height: 400px;
        border: none;
    }
</style>
</head>
<body>
<h1>Enter Your Card Details</h1>
<iframe
    src="https://test-tokenizer.paymaster24.com/card-tokenizer?login=test@example.com&plain_text=2025-04-25-12:00:00-550e8400-e29b-41d4-a716-446655440000&secret=base64_encoded_sha256&lang=en&post_url=https://webhook-test.com/f25df8b4cc57d32a49c2cb6940118339"
    title="Card Tokenizer iFrame"
></iframe>
</body>
</html>

Notes on iFrame Integration

Security: Ensure the iFrame URL uses HTTPS to secure communication.
Localization: Use the lang parameter to display the form in the desired language (e.g., lang=en for English).

Webhook: If a post_url is provided, the tokenization result will be sent to that URL as a POST request with the following structure:

{
"token": "fd7355715eda4d8d80c1334435d79dcf",
"metadata": {
    "masked_pan": "456162******9706",
    "cardholder_name": "Maxine Lind",
    "issuer_platform": "VISA",
    "customer_id": "1745915011",
    "expiry_month": 9,
    "expiry_year": 2025
},
"merchant_id": "merchant_test@example.com",
"timestamp": "2025-04-25T12:00:00Z"
}

Additional Endpoints (Authentication Required)

The following endpoints require authentication via the Authorization header. They are accessible to authorized users who have obtained an auth_token.

1. Retrieve Card Metadata (`GET /api/card-metadata`)

This endpoint retrieves metadata for a tokenized card.

Request

Method: GET
Endpoint: /api/card-metadata
Headers:
- Authorization: Bearer <auth_token>
Query Parameters:
- token (required): The token of the card (e.g., fd7355715eda4d8d80c1334435d79dcf).
- merchant_id (required): The merchant ID (e.g., merchant_test@example.com).

Response

Status: 200 OK

Body:

{
"metadata": {
    "token": "fd7355715eda4d8d80c1334435d79dcf",
    "masked_pan": "456162******9706",
    "cardholder_name": "Maxine Lind",
    "issuer_platform": "VISA",
    "customer_id": "1745915011",
    "expiry_month": 9,
    "expiry_year": 2025
}
}

token: The card token.
masked_pan: Masked card number.
cardholder_name: Cardholder's name.
issuer_platform: Card scheme (e.g., "VISA").
customer_id: The customer identifier associated with the card.
expiry_month: Expiry month.
expiry_year: Expiry year.

Error Responses:

400 Bad Request: Invalid input.

{
"error": "The token field is required."
}

401 Unauthorized: Invalid or missing Authorization header.
```
{
"error": "Invalid Auth Token"
}
```
404 Not Found: Card metadata not found.
```
{
"error": "Card metadata not found"
}
```

Example

curl -X GET "https://test-tokenizer.paymaster24.com/api/card-metadata?token=fd7355715eda4d8d80c1334435d79dcf&merchant_id=merchant_test@example.com" \
-H "Authorization: Bearer <auth_token>"

2. Retrieve Tokens by Merchant and Customer (`GET /api/tokens`)

This endpoint retrieves a list of tokens associated with a specific merchant and customer.

Request

Method: GET
Endpoint: /api/tokens
Headers:
- Authorization: Bearer <auth_token>
Query Parameters:
- merchant_id (required): The merchant ID (e.g., merchant_test@example.com).
- ext_customer_id (required): The external customer ID (e.g., 1745915011).

Response

Status: 200 OK

Body:

{
"tokens": [
    {
        "token": "fd7355715eda4d8d80c1334435d79dcf",
        "merchant_id": "merchant_test@example.com",
        "last_four": "9706",
        "expiry_month": 9,
        "expiry_year": 2025,
        "cardholder_name": "Maxine Lind",
        "bin": "456162",
        "customer_id": "1745915011",
        "created_at": "2025-04-25T12:00:00Z"
    }
]
}

tokens: An array of token objects.
token: The card token.
merchant_id: The merchant ID.
last_four: Last four digits of the card number.
expiry_month: Expiry month.
expiry_year: Expiry year.
cardholder_name: Cardholder's name.
bin: First six digits of the card number (BIN).
customer_id: The customer identifier.
created_at: Timestamp when the token was created.

Error Responses:

400 Bad Request: Invalid input parameters.

{
"error": "merchant_id and ext_customer_id are required"
}

401 Unauthorized: Invalid or missing Authorization header.
```
{
"error": "Invalid Auth Token"
}
```

Example

curl -X GET "https://test-tokenizer.paymaster24.com/api/tokens?merchant_id=merchant_test@example.com&ext_customer_id=1745915011" \
-H "Authorization: Bearer <auth_token>"

3. Delete Token (`POST /api/token/delete`)

This endpoint deletes a tokenized card.

Request

Method: POST
Endpoint: /api/token/delete
Headers:
- Content-Type: application/json
- Authorization: Bearer <auth_token>

Body:

{
"token": "fd7355715eda4d8d80c1334435d79dcf",
"merchant_id": "merchant_test@example.com"
}

token: The token to delete.
merchant_id: The merchant ID.

Response

Status: 200 OK
Body:
```
{
"success": true
}
```
- success: Indicates the token was deleted.

Error Responses:

400 Bad Request: Invalid input.

{
"error": "The token field is required."
}

400 Bad Request: Invalid merchant_id.
```
{
"error": "Invalid merchant_id"
}
```
401 Unauthorized: Invalid or missing Authorization header.
```
{
"error": "Invalid Auth Token"
}
```
404 Not Found: Token not found.
```
{
"error": "Token not found"
}
```

Example

curl -X POST https://test-tokenizer.paymaster24.com/api/token/delete \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <auth_token>" \
-d '{
"token": "fd7355715eda4d8d80c1334435d79dcf",
"merchant_id": "merchant_test@example.com"
}'

Error Handling

400 Bad Request: Indicates invalid input data or validation errors. Check the error message for details.
401 Unauthorized: Occurs when the Authorization header is missing, invalid, or the token has expired.
404 Not Found: Indicates the requested resource (e.g., token or card) was not found.
500 Internal Server Error: Indicates a server-side error. Contact the service administrator if this occurs frequently.

Best Practices

Secure Communication: Always use HTTPS to ensure data security.
Token Lifetime: The auth_token may expire based on server configuration. Ensure you generate a new auth_token if the previous one expires.
Error Handling: Implement robust error handling in your application to gracefully handle API errors.
Rate Limiting: Be aware that the API may enforce rate limits. Avoid sending too many requests in a short period.

Contact Support

For further assistance or to report issues, contact the API support team at support@paymaster24.com.

Table of Contents

Card Tokenizer Service API Integration Guide

Base URL

Authentication

Step 1: Obtain an auth_token

Request

Response

Example

Step 2: Set Up Authorization Header

Public Endpoints

1. Display Card Tokenizer iFrame (GET /card-tokenizer)

Request

Response

Example

2. Generate Authentication Token (POST /api/get-iframe-key)

Request

Response

Example

iFrame Integration

Steps for iFrame Integration

Example iFrame Integration

Notes on iFrame Integration

Additional Endpoints (Authentication Required)

1. Retrieve Card Metadata (GET /api/card-metadata)

Request

Response

Example

2. Retrieve Tokens by Merchant and Customer (GET /api/tokens)

Request

Response

Example

3. Delete Token (POST /api/token/delete)

Request

Response

Example

Error Handling

Best Practices

Contact Support

Step 1: Obtain an `auth_token`

1. Display Card Tokenizer iFrame (`GET /card-tokenizer`)

2. Generate Authentication Token (`POST /api/get-iframe-key`)

1. Retrieve Card Metadata (`GET /api/card-metadata`)

2. Retrieve Tokens by Merchant and Customer (`GET /api/tokens`)

3. Delete Token (`POST /api/token/delete`)