Add Card

Securely tokenize and store a customer's payment card for future use. This endpoint accepts an AES-256-CBC encrypted payload, and returns a hosted URL where the customer can enter their card details.

Overview

The Add Card endpoint lets you register a customer's payment card to the Datman vault for future transactions. You encrypt the registration payload client-side using AES-256-CBC with your merchant secret, then redirect the customer's browser to the returned URL where they'll enter their card details on a hosted page.

After the card is successfully added, the customer is redirected to your redirect_url and a webhook notification is sent to your webhook_url.

Environments

Environment	Base URL
Sandbox	`https://checkout-sandbox.datmanpay.com`
Production	`https://checkout.datmanpay.com`

Authentication

Authentication is handled through the encryption key (secret) and public key (pub_key) issued to your merchant account. The encrypted payload must be constructed using your merchant secret before being passed in the URL.

Request

URL Parameters

Parameter	Required	Description
data	Yes	AES-256-CBC encrypted payload, base64-encoded twice
base64Data	Yes	Base64-encoded JSON containing AVS and billing context
pub_key	Yes	Your merchant's public key identifier

Payload (before encryption)

The payload is a JSON object with the following fields. This gets encrypted before being passed in the data URL parameter.

{
    "reference": "5587687732",
    "customer_id": "4765876804",
    "country_code": "US",
    "redirect_url": "https://example.com",
    "webhook_url": "https://webhook.site/21c77815-6551-4a7e-9139-8ed94be56046"
}

Payload Fields

Field	Type	Required	Description
reference	string	Yes	Unique transaction reference. Numeric only, up to 16 digits
customer_id	string	Yes	Your internal customer identifier.
country_code	string	Yes	ISO 3166-1 alpha-2 country code (e.g., `GB`, `US`)
redirect_url	string	Yes	URL to redirect the customer to after card addition completes
webhook_url	string	Yes	URL to receive the webhook notification when card addition succeeds or fails

base64_data Object (before base64 encoding)

The base64Data URL parameter contains a base64-encoded JSON object with additional context:

{
    "backurl": "https://example.com",
    "country_code": "US"
}

Field	Type	Required	Description
backurl	string	Yes	URL to send the customer to if they cancel or go back
country_code	string	Yes	ISO 3166-1 alpha-2 country code — must match the payload

Encrypt Your Payload

Use AES-256-CBC encryption.

Node.js

php

Construct the URL

Use the following format:

https://<BASE_URL>/add-car?data=<ENCRYPTED_DATA>&base64Data=<base64Data>&pub_key=<public_key>

Example:

https://checkout-sandbox.datmanpay.com/add-card?data=U2FtcGxlRW5jcnlwdGVkRGF0YQ==&base64Data=eyJiYWNrdXJsIjoiaHR0cHM6Ly9leGFtcGxlLmNvbSIsImNvdW50cnlDb2RlIjoiR0IifQ==&pub_key=pk_bdhyudbhdbc

Redirect the User

Send the user's browser to the constructed URL. They'll see the hosted card entry form where they enter their card details.

After payment completion:

Success: User redirected to redirect_url

Final status: Available via webhook (always trust the webhook over redirects).

Error Handling

Always validate the webhook payload.

Common errors and suggestions:

Error Code	Reason	Suggested Action
Invalid configuration!	Wrong merchant config	Verify that merchant config keys are correct
Unable to process your request at the moment. Please try again later.	Missing required key	Verify that all required keys are present
Invalid secret	Invalid encryption or secret mismatch	Check your secret key length and initialization vector (IV)
Double-check your card details and try again.	Invalid card details	Verify that all card details are correct

Security Best Practices

Always keep the encryption secret secure and do not expose it on client-side code.

Use HTTPS for all URLs (redirect_url, webhook_url).

Validate all webhook payloads and signatures.

Final Recommendations

Always trust the webhook response as the final payment status.

Store encrypted payload logs for audit and debugging.

Overview#

Environments#

Authentication#

Request#

URL Parameters#

Payload (before encryption)#

Payload Fields#

base64_data Object (before base64 encoding)#

Encrypt Your Payload#

Construct the URL#

Redirect the User#

Error Handling#

Security Best Practices#

Final Recommendations#