Sale

Hosted Payment Form (Sale)

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

Prerequisites

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.

Key	Description	Required / Optional	Example
host	The host URL (usually your website or callback origin)	Required	sandbox.example.com
merchant_id	Unique merchant identifier provided by Datman	Required	63155480
order_id	Unique order identifier for the transaction	Required	987654321 or '3555f1ab-6e0d-48c3-b9e9'
customer_id	Unique customer identifier	Optional	98763455 or CUST98765
email	Customer's email address	Required	john.doe@example.com
phone_number	Customer's phone number in international format	Required	+447911123456
name	Merchant's Business name	Optional	Adam's Kitchen
amount	Transaction amount (as string)	Required	150.75
avs_house_number	House number for address verification	Optional	221B
avs_postcode	Postal code for address verification	Optional	NW16XE
merchant_reference	Reference string for merchant tracking	Optional	REF123456
redirect_url	URL where the user will be redirected after successful payment	Required	https://example.com/success
cancel_url	URL where the user will be redirected if they cancel the payment	Required	https://example.com/cancel
webhook_url	URL for webhook callback after payment completion	Required	https://example.com/webhook
back_url	URL to return the user back to your application if needed	Optional	https://example.com/back
first_name	Customer's first name	Required	John
last_name	Customer's last name	Required	Doe
flat	Flat or apartment number	Optional	12A
address1	Address line 1	Optional	London
address2	Address line 2	Optional	Baker Street
split_fee	Array of partner splits with partner_merchant_id, type_id, value, and value_type	Optional (if revenue split needed)	[ { "partner_merchant_id": "MID_001", "type_id": "2", "value": "10.50", "value_type": "amount" } ]

Example Split Commission Types

Type Id	Commission Types
1	Food/Goods
2	Service Fee
3	Delivery Fee
4	Delivery Tip
5	Restaurant Tip

Example Payload

{
  "host": "sandbox.example.com",
  "merchant_id": 63155480,
  "order_id": "987654321",
  "customer_id": "CUST98765",
  "email": "john.doe@example.com",
  "phone_number": "+447911123456",
  "name": "Adam's Kitchen",
  "amount": "150.75",
  "avs_house_number": "221B",
  "avs_postcode": "NW16XE",
  "merchant_reference": "REF123456",
  "redirect_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel",
  "webhook_url": "https://example.com/webhook",
  "back_url": "https://example.com/back",
  "first_name": "John",
  "last_name": "Doe",
  "flat": "12A",
  "address1": "London",
  "address2": "Baker Street"
}

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 (Sale)#

Prerequisites#

Process Flow Diagram#

Environments#

Step-by-Step Integration Guide#

1. Prepare Your Payload#

2. Encrypt Your Payload#

3. Construct the Hosted Payment URL#

4. Redirect the User#

Error Handling#

Security Best Practices#

Final Recommendations#