Hosted payment page

The Hosted Payment page redirects the shopper to a Datman-hosted form that handles the complete card payment. You don't send an API request yourself, and there's no API key in it. Instead, your server encrypts the payment details and sends the shopper's browser to a Datman URL. Datman takes the payment, sends the shopper back to you, and tells your server the result with a webhook.

This is one of two ways to take online payments. The endpoint reference is Open the hosted payment form (Sale).

RequirementsCopy Anchor Link

Before you begin, take into account the following requirements, limitations, and preparations.

How it worksCopy Anchor Link

For a Hosted Payment page integration, you must integrate the following parts:

• Your payment server: builds and encrypts the payment details, and builds the URL to the hosted form.
• Your webhook server: listens for the webhook that includes the outcome of each payment.

Integration stepsCopy Anchor Link

To integrate the Hosted Payment page:

1. Build the payload.
2. Encrypt it.
3. Redirect the shopper to the hosted payment page.
4. Get the payment outcome.

Shopper checkout experienceCopy Anchor Link

When the shopper goes to check out:

1. You redirect the shopper to the Datman-hosted payment form.
2. The shopper completes the payment on the form.
3. The shopper is redirected to your redirect_url, or to your cancel_url if they cancel.

Payments integration flowCopy Anchor Link

Your website, your server and the hosted payment page work together to complete the payment flow:

1. The shopper chooses to check out on your website.
2. Your server builds the payment details and encrypts them with your secret key.
3. Your server builds the URL to the hosted form with the encrypted payload as data and your pub_key.
4. Your website redirects the shopper's browser to that URL.
5. The shopper completes the payment on the hosted form.
6. The shopper is redirected to your redirect_url or cancel_url.
7. Your webhook server receives the payment status webhook with the payment outcome at your webhook_url.

1. Build the payloadCopy Anchor Link

Create a JSON object with the payment details. Keys are case-sensitive. Note that amount is in major units, as a string, for example 24.50.

{
  "host": "sandbox.example.com",
  "merchant_id": 63155480,
  "order_id": "987654321",
  "customer_id": "CUST98765",
  "email": "john.doe@example.com",
  "provider": "provider_value",
  "phone_number": "+447911123456",
  "amount": "150.75",
  "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"
}

2. Encrypt itCopy Anchor Link

Encrypt the payload on your server, because the secret key must never reach the browser. Use AES-256-CBC:

• Key: your secret key, padded with zero bytes (or cut) to 32 bytes.
• IV: the first 16 characters of your secret key.
• Encoding: base64-encode the encrypted bytes, then base64-encode the result again.

import crypto from 'node:crypto';

export function encryptPayload(payload, secret) {
  const key = Buffer.concat([Buffer.from(secret), Buffer.alloc(32)], 32); // 32-byte key
  const iv = Buffer.from(secret).subarray(0, 16); // first 16 bytes of the secret
  const cipher = crypto.createCipheriv('aes-256-cbc', key, iv);
  const encrypted = cipher.update(JSON.stringify(payload), 'utf8', 'base64') + cipher.final('base64');
  return Buffer.from(encrypted).toString('base64'); // base64 a second time
}

function encryptPayload(array $payload, string $secret): string {
    $iv = substr($secret, 0, 16); // first 16 characters of the secret
    // openssl_encrypt pads or cuts the key to 32 bytes, as Datman does
    $encrypted = openssl_encrypt(json_encode($payload), 'AES-256-CBC', $secret, OPENSSL_RAW_DATA, $iv);
    return base64_encode(base64_encode($encrypted)); // base64 twice
}

3. Redirect the shopper to the hosted payment pageCopy Anchor Link

Build the URL with the encrypted payload as data and your public key as pub_key, URL-encoding both. Then redirect the shopper's browser to it. The shopper pays on the hosted form.

The Open the hosted payment form (Sale) page in the API Explorer shows the sandbox and production endpoint URLs. Keep the endpoint URL in your configuration.

app.post('/checkout', (req, res) => {
  const data = encryptPayload(buildPayload(req), process.env.DATMAN_SECRET_KEY);
  const url = new URL(process.env.DATMAN_HOSTED_FORM_URL); // endpoint URL from the API Explorer
  url.searchParams.set('data', data);
  url.searchParams.set('pub_key', process.env.DATMAN_PUBLIC_KEY);
  res.redirect(303, url.toString());
});

4. Get the payment outcomeCopy Anchor Link

After the hosted form finishes the payment flow, you can show the shopper the current payment status. Datman sends a webhook with the outcome of the payment.

Show the result of the paymentCopy Anchor Link

• After a successful payment, the shopper is sent to your redirect_url.
• If they cancel, they're sent to your cancel_url.

Don't treat the redirect as the final status, because redirects can be skipped or faked.

Update your order management systemCopy Anchor Link

Update your order management system when you get the payment status webhook at your webhook_url. Verify the webhook's signature, then use order_id to match it to your order. Only fulfil the order once the webhook says it's paid.

For a successful payment, the webhook contains status authorisation and success true. For an unsuccessful payment, it contains success false and a reason.

Example webhook for a successful payment

{
  "order_id": "987654321",
  "amount": "150.75",
  "currency": "GBP",
  "customer_id": "CUST98765",
  "xref": "O88213045M63155480T4821937",
  "status": "authorisation",
  "success": "true",
  "date": "2026-10-15 12:34:56+01:00"
}

Test and go liveCopy Anchor Link

Build and test against the sandbox endpoint URL. When you are ready to go live:

1. Switch to the production endpoint URL shown in the API Explorer.
2. Use your live secret key, public key and webhook secret.
3. Make sure that redirect_url, cancel_url, webhook_url and back_url use HTTPS.

TroubleshootingCopy Anchor Link

Payment errorsCopy Anchor Link

If the request can't be processed, the page shows a message instead of the payment form:

Next stepsCopy Anchor Link