Token Sale

Hosted Payment Form (Token Sale)

This guide will help you integrate Datman’s Hosted Payment for Token sale Form smoothly and securely. Please read carefully; keys and values are case-sensitive, and small errors can cause transaction failures.

Prerequisites

Make sure you fully understand the Sale docs

Ensure you have the SECRET_KEY , WEBHOOK_SECRET_KEY provided by Datman.

This key is required for secure communication and authentication.

Process Flow Diagram

Environments

Environment	Base URL
Sandbox	`https://ws2-payments.datmanpay.com`
Production	`http://payments.datmanpay.com`

Step-by-Step Integration Guide

1. Prepare Your Payload

Prepare a JSON payload with the required and optional keys. Remember, all keys are case-sensitive.

This integration is the same as the Sale documentation, with a few additional keys.
Please review the keys below — they represent only the additional parameters required.

Key	Description	Status	Example
`token`	The host URL (usually your website or callback origin)	Required	https://sandbox.example.com
`token_avs`	Unique merchant identifier provided by Datman	Required	MID123456789
`last4_digits`	Last 4 digits of card	Required	9876
`customer_id`	Unique customer identifier	Required	98763455 or CUST98765

Example Payload

{
 ...same as <Sale> Payload
 
"token_avs": "a:1:{i:0;a:2:      {s:14:\"AvsHouseNumber\";s:6:\"London\";s:11:\"AvsPostcode\";s:8:\"ST66DX\";}}",
"token": "mxtoken_1Nxx1l2eZvKYlo2C5vdDXYZ",
"last4_digits": "9876",
"customer_id": "98763455"
}

2. Encrypt Your Payload

Use AES-256-CBC encryption. The secret key must be exactly 32 bytes long. If not, pad or trim as necessary. The IV will be the first 16 characters of the secret.

Node.js Encryption Example:

3. Construct the Hosted Payment URL

Use the following format:

https://<BASE_URL>/opto/card.php?data=<ENCRYPTED_DATA>

Example:

https://ws2-payments.datmanpay.com/opto/card.php?data=U2FtcGxlRW5jcnlwdGVkRGF0YQ==

4. Redirect the User

Once the URL is constructed, redirect the user to the hosted payment form. Users will complete their payment securely.

After payment completion:

Success: User redirected to redirect_url

Cancelled: User redirected to cancel_url

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

Error Handling

Always validate the webhook payload.

Use order_id and merchant_id for reconciliation.

Common errors and suggestions:

Error Code	Reason	Suggested Action
Unable to process this request!	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)

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, cancel_url, webhook_url).

If IP whitelisting is available, use it for your webhook endpoint.

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.

Hosted Payment Form (Token Sale)#

Prerequisites#

Process Flow Diagram#

Environments#

Step-by-Step Integration Guide#

1. Prepare Your Payload#

2. Encrypt Your Payload#

Node.js Encryption Example:#

3. Construct the Hosted Payment URL#

4. Redirect the User#

Error Handling#

Security Best Practices#

Final Recommendations#

Hosted Payment Form (Token Sale)

Prerequisites

Process Flow Diagram

Environments

Step-by-Step Integration Guide

1. Prepare Your Payload

2. Encrypt Your Payload

Node.js Encryption Example:

3. Construct the Hosted Payment URL

4. Redirect the User

Error Handling

Security Best Practices

Final Recommendations