navbar-image MENU

API DOCUMENTATION

Introduction

Welcome to the PAYMENT BOOK API DOCUMENTATION — an enterprise-grade payment orchestration engine engineered for merchants, marketplaces, fintech platforms, and SaaS businesses.

The GATE DIRECT API provides a unified, developer-friendly REST interface that connects your application directly to multi-acquirer processing rails, global card networks, alternative payment methods (APMs), and digital wallets with low latency, intelligent routing, and automated reconciliation.

Integration Principles

RESTful JSON Architecture: All endpoints consume and produce UTF-8 encoded application/json payloads over secure HTTPS.

Cryptographic Request Signing: Every outgoing request and incoming webhook is cryptographically authenticated using HMAC-SHA-512 via our SDK Signer to eliminate spoofing and parameter tampering.

Idempotency & Replay Protection: Deterministic transaction and client order references ensure duplicate requests are safely recognized without double charging.

Zero-Code HTTP Bridge: Seamlessly route third-party provider traffic and vendor schemas to the gateway through an intelligent proxy without changing your integration code (see HTTP Bridge).

Security & Authentication

The GATE DIRECT API enforces a zero-trust, cryptographically signed communication model to ensure that every request between your application and our payment gateway is authenticated, intact, and protected against interception or parameter tampering.

Instead of transmitting sensitive static API secrets in plaintext headers or query parameters, our gateway utilizes an HMAC-SHA-512 cryptographic signature calculated over the canonicalized JSON payload.

Authentication Credentials

You can manage your API tokens, generate new signing keys, and configure webhooks directly in: Services & API Tokens → Select Service → API Tokens.

Token Name (X-REQUEST-TOKEN-NAME): A public identifier for your API token (e.g. service-api-key), passed as a standard HTTP request header. It tells our servers which key pair to use for validating the signature.

Service ID (meta.service_id): The unique integer identifier of your merchant service, included inside the meta object of your request payload.

Secret Token Key: A high-entropy private key shared only between your server and PAYMENT BOOK. The secret key is used exclusively to generate HMAC signatures and must never be exposed to clients, browsers, or version control.

For automated signature generation and verification in PHP, use our official SDK Signer, or review the complete Cryptographic Signature Algorithm specification.

GATE DIRECT API

Postman collection →

This documentation provides complete API integration examples, detailed field descriptions, validation requirements, and ready-to-use request and response samples in multiple programming languages. You will find information about mandatory and optional parameters, expected data formats, authentication, validation rules, error handling, and response structures to help you integrate quickly and reliably.
API communication is performed using standard JSON request bodies and JSON responses over HTTPS.

Payment

POST api/transaction/purchase/create

POST
https://payment-book.hs.domonk.co.uk/gate
/api/transaction/purchase/create
requires authentication

Payment initialization - to process payment, you must redirect the user to data.redirect_url and after finishing payment, we will redirect user to provided redirect.success|fail|return accordingly of the result and send webhook to service

Headers

X-REQUEST-TOKEN-NAME
Example:
token-name
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
$curl = curl_init();

$tokenName = 'token-name';
$tokenSecret = 'secret-key';

$payload = [
    'meta' => [
        'service_id' => 100,
        'reference_id' => 'your-id-1793335797',
    ],
    'payment' => [
        'amount' => '100.00',
        'currency' => 'EUR',
    ],
    'user' => [
        'email' => 'someone@example.com',
        'phone' => '+37127776222',
        'first_name' => 'Equuer',
        'last_name' => 'Duhhoney',
        'address' => 'Some street 1',
        'day_of_birth' => '1990-01-01',
        'city' => 'Riga',
        'zip' => 'LV-1010',
        'country' => 'CZ',
        'language' => 'en',
    ],
    'webhook' => [
        'url' => 'https://your-service-domain.com/callback-handler',
        'token_name' => 'token-name',
    ],
    'redirect' => [
        'success' => 'https://your-service-domain.com/success',
        'fail' => 'https://your-service-domain.com/fail',
        'return' => 'https://your-service-domain.com/return',
    ],
    'company' => [
        'name' => 'Company name',
        'email' => 'company@example.com',
        'phone' => '+37127776222',
        'tax_id' => 'Tax/Vat number',
        'bank_name' => 'AS SOME BANK',
        'bank_account' => 'HB49SAAD93848485849948490',
        'bank_swift' => 'SW2IS23',
        'address' => 'Belgium, Some address 123a-2121, BL-2312.',
    ],
    'order' => [
        [
            'amount' => '5.56',
            'currency' => 'EUR',
            'textual' => '<b>Soft desk wipe</b> from cotton',
        ],
        [
            'amount' => '2.56',
            'currency' => 'EUR',
            'textual' => '<b>Table lamp</b> with charger',
        ],
    ],
    'additional_data' => [
        'client_ip' => '127.0.0.1',
        'client_user_agent' => 'Mozilla/5.0',
        'key' => 'value',
        'payment_method_bank' => 'revolut',
        'payment_method_country' => 'DE',
    ],
];

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://payment-book.hs.domonk.co.uk/gate/api/transaction/purchase/create',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode(\PB\Signer::sign($payload, $tokenSecret)),
    CURLOPT_HTTPHEADER => [
        'X-REQUEST-TOKEN-NAME: ' . $tokenName,
        'Content-Type: application/json',
        'Accept: application/json',
    ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo 'cURL Error #:' . $err;
} else {
    $response = json_decode($response, true);
    print_r($response);
}
Example response:
{
    "meta": {
        "code": 200,
        "success": true,
        "message": "Transaction can be processed!",
        "response_time": "0.46769499778748 s"
    },
    "data": {
        "redirect_url": "https://payment-book.hs.domonk.co.uk/gate/payment/purchase/0a553d60-8228-422c-b535-b1cabb6d34ea",
        "id": 1,
        "ulid": "0a553d60-8228-422c-b535-b1cabb6d34ea",
        "reference_id": "ref-123",
        "service_id": 1,
        "merchant_id": 1,
        "customer_id": 1,
        "cost": "10.00000000",
        "unified_error_message": null,
        "unified_error_code": null,
        "amount": "10.00000000",
        "currency": "EUR",
        "type": "purchase",
        "status": "created",
        "request": [],
        "metadata": [],
        "updated_at": "2024-11-13 11:18:09",
        "created_at": "2024-11-13 11:18:09",
        "deleted_at": null
    }
}
{
    "meta": {
        "code": 401,
        "success": false,
        "message": "Unauthorized.",
        "response_time": "0.37983679771423 s"
    },
    "errors": null
}
{
    "meta": {
        "code": 422,
        "success": false,
        "message": "Validation Error.",
        "response_time": "0.3987729549408 s"
    },
    "errors": {
        "meta": [
            "The meta must contain 3 items."
        ],
        "meta.reference_id": [
            "The meta.reference id field is required."
        ],
        "order.0.amount": [
            "The order.0.amount field is required."
        ],
        "order.0.currency": [
            "The order.0.currency field is required."
        ]
    }
}

Recurring

POST api/transaction/recurring/create

POST
https://payment-book.hs.domonk.co.uk/gate
/api/transaction/recurring/create
requires authentication

Recurring payments initialization - to process payment you must redirect user to data.redirect_url and after finishing payment, we will redirect user to provided redirect.success|fail|return accordingly of the result and send webhook to service

Headers

X-REQUEST-TOKEN-NAME
Example:
token-name
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
$curl = curl_init();

$tokenName = 'token-name';
$tokenSecret = 'secret-key';

$payload = [
    'meta' => [
        'service_id' => 100,
        'reference_id' => 'your-id-1793335797',
    ],
    'payment' => [
        'amount' => '100.00',
        'currency' => 'EUR',
    ],
    'recurring' => [
        'enabled' => true,
        'start_date' => '2024-11-18',
        'cycle_days' => 30,
        'trial_days' => 0,
    ],
    'user' => [
        'email' => 'someone@example.com',
        'phone' => '+37127776222',
        'first_name' => 'Equuer',
        'last_name' => 'Duhhoney',
        'address' => 'Some street 1',
        'day_of_birth' => '1990-01-01',
        'city' => 'Riga',
        'zip' => 'LV-1010',
        'country' => 'CZ',
        'language' => 'en',
    ],
    'webhook' => [
        'url' => 'https://your-service-domain.com/callback-handler',
        'token_name' => 'token-name',
    ],
    'redirect' => [
        'success' => 'https://your-service-domain.com/success',
        'fail' => 'https://your-service-domain.com/fail',
        'return' => 'https://your-service-domain.com/return',
    ],
    'company' => [
        'name' => 'Company name',
        'email' => 'company@example.com',
        'phone' => '+37127776222',
        'tax_id' => 'Tax/Vat number',
        'bank_name' => 'AS SOME BANK',
        'bank_account' => 'HB49SAAD93848485849948490',
        'bank_swift' => 'SW2IS23',
        'address' => 'Belgium, Some address 123a-2121, BL-2312.',
    ],
    'order' => [
        [
            'amount' => '5.56',
            'currency' => 'EUR',
            'textual' => '<b>Soft desk wipe</b> from cotton',
        ],
        [
            'amount' => '2.56',
            'currency' => 'EUR',
            'textual' => '<b>Table lamp</b> with charger',
        ],
    ],
    'additional_data' => [
        'client_ip' => '127.0.0.1',
        'client_user_agent' => 'Mozilla/5.0',
        'key' => 'value',
        'payment_method_bank' => 'revolut',
        'payment_method_country' => 'DE',
    ],
];

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://payment-book.hs.domonk.co.uk/gate/api/transaction/recurring/create',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode(\PB\Signer::sign($payload, $tokenSecret)),
    CURLOPT_HTTPHEADER => [
        'X-REQUEST-TOKEN-NAME: ' . $tokenName,
        'Content-Type: application/json',
        'Accept: application/json',
    ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo 'cURL Error #:' . $err;
} else {
    $response = json_decode($response, true);
    print_r($response);
}
Example response:
{
    "meta": {
        "code": 200,
        "success": true,
        "message": "Transaction can be processed!",
        "response_time": "0.46769499778748 s"
    },
    "data": {
        "redirect_url": "https://payment-book.hs.domonk.co.uk/gate/payment/recurring/0a553d60-8228-422c-b535-b1cabb6d34ea",
        "id": 1,
        "ulid": "0a553d60-8228-422c-b535-b1cabb6d34ea",
        "reference_id": "ref-123",
        "service_id": 1,
        "merchant_id": 1,
        "customer_id": 1,
        "cost": "10.00000000",
        "unified_error_message": null,
        "unified_error_code": null,
        "amount": "10.00000000",
        "currency": "EUR",
        "type": "recurring",
        "status": "created",
        "request": [],
        "metadata": [],
        "updated_at": "2024-11-13 11:18:09",
        "created_at": "2024-11-13 11:18:09",
        "deleted_at": null
    }
}
{
    "meta": {
        "code": 401,
        "success": false,
        "message": "Unauthorized.",
        "response_time": "0.37983679771423 s"
    },
    "errors": null
}
{
    "meta": {
        "code": 422,
        "success": false,
        "message": "Validation Error.",
        "response_time": "0.3987729549408 s"
    },
    "errors": {
        "meta": [
            "The meta must contain 3 items."
        ],
        "meta.reference_id": [
            "The meta.reference id field is required."
        ],
        "order.0.amount": [
            "The order.0.amount field is required."
        ],
        "order.0.currency": [
            "The order.0.currency field is required."
        ]
    }
}

POST api/transaction/recurring/cancel

POST
https://payment-book.hs.domonk.co.uk/gate
/api/transaction/recurring/cancel
requires authentication

Recurring cancel - purchased service should be available till the end of the subscription period end date

Headers

X-REQUEST-TOKEN-NAME
Example:
token-name
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
$curl = curl_init();

$tokenName = 'token-name';
$tokenSecret = 'secret-key';

$payload = [
    'meta' => [
        'service_id' => 100,
        'reference_id' => 'your-id-1793335797',
        'ulid' => 'similique',
    ],
];

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://payment-book.hs.domonk.co.uk/gate/api/transaction/recurring/cancel',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode(\PB\Signer::sign($payload, $tokenSecret)),
    CURLOPT_HTTPHEADER => [
        'X-REQUEST-TOKEN-NAME: ' . $tokenName,
        'Content-Type: application/json',
        'Accept: application/json',
    ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo 'cURL Error #:' . $err;
} else {
    $response = json_decode($response, true);
    print_r($response);
}
Example response:
{
    "meta": {
        "code": 200,
        "success": true,
        "message": "Transaction is cancelling",
        "response_time": "0.31760692596436 s"
    },
    "data": {
        "id": 11,
        "reference_id": "1111122222222",
        "uuid": "ff6bcd26-9e70-40fd-a3aa-80c8586193d1",
        "service_id": 1,
        "merchant_id": 1,
        "cost_type": "in",
        "unified_error_message": "Cannot use a payment_method_nonce more than once.",
        "unified_error_code": 93107,
        "amount": 12.32,
        "currency": "EUR",
        "type": "recurring",
        "status": "processing",
        "request": {
            "order": [
                {
                    "textual": "Tava skrējiena \"TEST 01 2020\" starts <b>2020-02-12 18:10:00</b><br />Dalībnieka numurs \"TEST 01 2020\" ir #<b>9</b><br />Distance: <b>25 KM</b><br />Vienas biļetes cena: <b>15.00 EUR</b>"
                }
            ],
            "user": {
                "first_name": "max",
                "email": "maksimsge@gmail.com",
                "phone": "+37123446666",
                "address": "dsasdas",
                "last_name": "test"
            },
            "company": {
                "name": "sadasd",
                "address": "Some addresss 2443-112",
                "bank_name": "LV45UNLA3242344342342342",
                "tax_id": "das231312",
                "bank_account": "HABA"
            },
            "meta": {
                "type": "subscription",
                "signature": "FbTUZFk/nH1wuVhFT9SCg75NTZmbueiLtCwKMoYddu/g2lyrvFYK9YC9+vwSJDhXkAioPtlmJRDofr2MG8V/AQ==",
                "reference_id": "1111122222222",
                "service_id": 1
            },
            "refund": {
                "amount": 12.32,
                "currency": "EUR"
            },
            "callback": {
                "url": "https://payment-book.hs.domonk.co.uk/gate/registrator/payment-status"
            },
            "redirect": {
                "fail": "https://payment-book.hs.domonk.co.uk/gate/error-registration/1111122222222",
                "return": "https://payment-book.hs.domonk.co.uk/gate/error-registration/1111122222222",
                "success": "https://payment-book.hs.domonk.co.uk/gate/error-registration/1111122222222"
            },
            "recurring": {
                "cycle_days": 30,
                "start_date": "2024-09-10T00:30:23+03:00",
                "trial_days": 14
            },
            "additional_data": {
                "device_data": "{\"correlation_id\":\"709925ec085ac8ca37f7feaff3784e05\"}",
                "payment_method_nonce": "fd94fb20-04ae-1814-105b-116978b6bcff"
            }
        },
        "metadata": {
            "end_date": "Infinite (until cancellation/expiration)",
            "card_meta": {
                "mask": null,
                "type": null,
                "token": null,
                "holder": null,
                "expiration": null
            },
            "days_cycle": 30,
            "start_date": "ERR",
            "trial_days": 14,
            "customer_id": "ERR",
            "subscription_id": "ERR"
        },
        "created_at": "2024-10-19T21:24:12.000000Z",
        "updated_at": "2024-10-19T21:28:25.000000Z",
        "operations": [
            {
                "id": 17,
                "payment_method_reference_id": "",
                "transaction_id": 11,
                "merchant_id": 1,
                "service_id": 1,
                "payment_method_id": 1,
                "amount": 12.32,
                "currency": "EUR",
                "total_fee": 0,
                "metadata": {
                    "subscription_data": []
                },
                "errors": [
                    {
                        "code": "93107",
                        "name": "paymentMethodNonce",
                        "message": "Cannot use a paymentMethodNonce more than once."
                    }
                ],
                "code": 93107,
                "message": "Cannot use a payment_method_nonce more than once.",
                "type": "subscription",
                "status": "processing",
                "confirmed_at": "2024-10-19 21:28:12",
                "created_at": "2024-10-19T21:24:12.000000Z",
                "updated_at": "2024-10-19T21:28:25.000000Z"
            }
        ],
        "service": {
            "id": 1,
            "name": "Glover Group",
            "slug": "parisian-inc",
            "merchant_id": 1,
            "payment_method_id": 1,
            "url": "http://jacobson.com/quam-dolorem-quasi-nihil",
            "redirect_success": "https://payment-book.hs.domonk.co.uk/gate/finish-registration/{reference_id}",
            "redirect_fail": "https://payment-book.hs.domonk.co.uk/gate/error-registration/{reference_id}",
            "redirect_return": "",
            "request_expiration": 86300,
            "currency": "EUR",
            "type": "unknown",
            "status": "active",
            "params": null,
            "created_at": "2024-09-10T23:12:41.000000Z",
            "updated_at": "2024-09-10T23:12:41.000000Z",
            "deleted_at": null,
            "payment_system": {},
            "merchant": {
                "id": 1,
                "name": "Howell-Waelchi",
                "slug": "dach-hartmann",
                "phone": "",
                "email": "",
                "bank_name": "Dessie Daugherty",
                "bank_swift": "NCLNKW7L",
                "bank_account": "CZ8676262270903896080057",
                "tax_id": "wgulgowski",
                "homepage": "http://fritsch.com/mollitia-facilis-deserunt-qui-enim",
                "address": "90614 Horacio Lock\nPort Kellenbury, IL 32559",
                "user_id": 1,
                "status": "verified",
                "created_at": "2024-09-10T23:12:41.000000Z",
                "updated_at": "2024-09-10T23:12:41.000000Z",
                "deleted_at": null
            }
        }
    }
}
{
    "meta": {
        "code": 401,
        "success": false,
        "message": "Unauthorized.",
        "response_time": "0.37983679771423 s"
    },
    "errors": null
}
{
    "meta": {
        "code": 422,
        "success": false,
        "message": "Validation Error.",
        "response_time": "0.3987729549408 s"
    },
    "errors": {
        "meta": [
            "The meta must contain 3 items."
        ],
        "meta.reference_id": [
            "The meta.reference id field is required."
        ]
    }
}

POST api/transaction/recurring/update

POST
https://payment-book.hs.domonk.co.uk/gate
/api/transaction/recurring/update
requires authentication

Recurring update - Updates the recurring subscription amount for a customer.

This endpoint modifies the scheduled billing amount for all future cycles. If the new subscription price is higher than the current price, the system will calculate the prorated missing amount for the remainder of the current billing cycle. This prorated difference will be instantly and automatically charged to the customer's payment method as an immediate, one-time payment operation. If the new subscription price is lower than or equal to the current price, only the future recurring billing amount will be updated, and no instant charge will occur.

Headers

X-REQUEST-TOKEN-NAME
Example:
token-name
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
$curl = curl_init();

$tokenName = 'token-name';
$tokenSecret = 'secret-key';

$payload = [
    'meta' => [
        'service_id' => 100,
        'reference_id' => 'your-id-1793335797',
        'ulid' => 'doloremque',
    ],
    'payment' => [
        'amount' => '100.00',
        'currency' => 'EUR',
    ],
    'user' => [
        'email' => 'isaiah.williamson@example.net',
        'first_name' => 'ex',
        'last_name' => 'fugiat',
        'address' => 'mollitia',
        'day_of_birth' => '2100-07-31',
        'city' => 'cehbbwy',
        'zip' => 'xwpydekdiegnzx',
        'country' => 't',
        'language' => 'zn',
    ],
    'company' => [
        'name' => 'sfuzccnyln',
        'email' => 'chadrick.schmidt@example.org',
        'tax_id' => 'gqk',
        'bank_account' => 'zxtolsaqzgwtlstkzc',
        'bank_name' => 'gm',
        'bank_swift' => 'hjsazj',
        'address' => 'dttb',
    ],
];

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://payment-book.hs.domonk.co.uk/gate/api/transaction/recurring/update',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode(\PB\Signer::sign($payload, $tokenSecret)),
    CURLOPT_HTTPHEADER => [
        'X-REQUEST-TOKEN-NAME: ' . $tokenName,
        'Content-Type: application/json',
        'Accept: application/json',
    ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo 'cURL Error #:' . $err;
} else {
    $response = json_decode($response, true);
    print_r($response);
}
Example response:
{
    "meta": {
        "code": 200,
        "success": true,
        "message": "Transaction is updating",
        "response_time": "0.46769499778748 s"
    },
    "data": {
        "id": 1,
        "ulid": "0a553d60-8228-422c-b535-b1cabb6d34ea",
        "reference_id": "ref-123",
        "service_id": 1,
        "merchant_id": 1,
        "customer_id": 1,
        "cost": "10.00000000",
        "unified_error_message": null,
        "unified_error_code": null,
        "amount": "15.00000000",
        "currency": "EUR",
        "type": "recurring",
        "status": "processing",
        "request": [],
        "metadata": [],
        "updated_at": "2024-11-13 11:18:09",
        "created_at": "2024-11-13 11:18:09",
        "deleted_at": null
    }
}
{
    "meta": {
        "code": 401,
        "success": false,
        "message": "Unauthorized.",
        "response_time": "0.37983679771423 s"
    },
    "errors": null
}
{
    "meta": {
        "code": 422,
        "success": false,
        "message": "Validation Error.",
        "response_time": "0.3987729549408 s"
    },
    "errors": {
        "meta": [
            "The meta must contain 3 items."
        ],
        "meta.reference_id": [
            "The meta.reference id field is required."
        ]
    }
}

Withdrawal

POST api/transaction/withdrawal/create

POST
https://payment-book.hs.domonk.co.uk/gate
/api/transaction/withdrawal/create
requires authentication

Withdrawal initialization - will create a withdrawal request to your merchant/private account from your balance

Headers

X-REQUEST-TOKEN-NAME
Example:
token-name
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
$curl = curl_init();

$tokenName = 'token-name';
$tokenSecret = 'secret-key';

$payload = [
    'meta' => [
        'service_id' => 100,
        'reference_id' => 'your-id-1793335797',
    ],
    'withdrawal' => [
        'amount' => '100.00',
        'currency' => 'EUR',
        'balance_id' => 99,
    ],
];

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://payment-book.hs.domonk.co.uk/gate/api/transaction/withdrawal/create',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode(\PB\Signer::sign($payload, $tokenSecret)),
    CURLOPT_HTTPHEADER => [
        'X-REQUEST-TOKEN-NAME: ' . $tokenName,
        'Content-Type: application/json',
        'Accept: application/json',
    ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo 'cURL Error #:' . $err;
} else {
    $response = json_decode($response, true);
    print_r($response);
}
Example response:
{
    "meta": {
        "code": 200,
        "success": true,
        "message": "Transaction can be processed!",
        "response_time": "0.46769499778748 s"
    },
    "data": null
}
{
    "meta": {
        "code": 401,
        "success": false,
        "message": "Unauthorized.",
        "response_time": "0.37983679771423 s"
    },
    "errors": null
}
{
    "meta": {
        "code": 422,
        "success": false,
        "message": "Validation Error.",
        "response_time": "0.3987729549408 s"
    },
    "errors": {
        "meta": [
            "The meta must contain 3 items."
        ],
        "meta.reference_id": [
            "The meta.reference id field is required."
        ]
    }
}

Common

POST api/transaction/refund

POST
https://payment-book.hs.domonk.co.uk/gate
/api/transaction/refund
requires authentication

Headers

X-REQUEST-TOKEN-NAME
Example:
token-name
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
$curl = curl_init();

$tokenName = 'token-name';
$tokenSecret = 'secret-key';

$payload = [
    'meta' => [
        'service_id' => 100,
        'reference_id' => 'external-id-1793335797',
    ],
    'refund' => [
        'amount' => '100.00',
        'currency' => 'EUR',
        'comment' => 'Package with defect',
    ],
];

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://payment-book.hs.domonk.co.uk/gate/api/transaction/refund',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode(\PB\Signer::sign($payload, $tokenSecret)),
    CURLOPT_HTTPHEADER => [
        'X-REQUEST-TOKEN-NAME: ' . $tokenName,
        'Content-Type: application/json',
        'Accept: application/json',
    ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo 'cURL Error #:' . $err;
} else {
    $response = json_decode($response, true);
    print_r($response);
}
Example response:
{"meta":{"code":200,"success":true,"message":"OK","response_time":"0.21948504447937 s"},"data":{"message":"Status: success","operation":{"id":1,"reference_id":"aac00f57-b30b-4acd-9ba9-cc43a3c4e808","transaction_id":1,"user_profile_id":2,"merchant_id":1,"tariff_group":"default","currency":"EUR","amount":"103.96","fee":"1.00000000","direction":"in","action":"pay_via_payment_gate","service":"payment_gateway","service_id":1,"service_reference_id":"89b6647c-b0b7-4b93-a5fd-820edb4dcf42","metadata":{"site":{"return":{"fail":"http:\/\/merchant.site\/fail","return":"http:\/\/merchant.site\/return","success":"http:\/\/merchant.site\/success"}},"redirect_url":"https:\/\/some-link-for-redirect.com\/89b6647c-b0b7-4b93-a5fd-820edb4dcf42\/},"errors":[],"message":"","code":0,"status":"success","confirmed_at":"2024-06-25 08:13:19","created_at":"2024-06-25T08:10:18.000000Z","updated_at":"2024-06-25T08:13:40.000000Z","transaction":{"id":1,"reference_id":"2222211123-te22222st-3141124322233","user_profile_id":2,"user_balance_id":1,"merchant_id":1,"type":"in_by_payment_gateway","unified_error_message":"Amount is to low","request":{"meta":{"signature":"c8b7e64819a3db0be9e8ef33dd05586d78bcddbd91ed621ce263f7f568ef58ca0b9057cb0f27f65bace03c082373f7b62ac43aa95ea42ece380d83139d338c86","reference_id":"2222211123-te22222st-3141124322233","merchant_id":"1"},"user":{"email":"test@crypto-fusion.com","country":"TST","last_name":"Surname","first_name":"Name"},"return":{"fail":"http:\/\/merchant.site\/fail","return":"http:\/\/merchant.site\/return","success":"http:\/\/merchant.site\/success"},"refund":{"amount":"103.96","currency":"EUR"}},"status":"failed","created_at":"2024-06-25T08:10:18.000000Z","updated_at":"2024-06-25T08:13:43.000000Z"}}}}
{
    "meta": {
        "code": 401,
        "success": false,
        "message": "Unauthorized.",
        "response_time": "0.88372492790222 s"
    },
    "errors": null
}
{
    "meta": {
        "code": 404,
        "success": false,
        "message": "Not found",
        "response_time": "0.39620399475098 s"
    },
    "errors": null
}
{
    "meta": {
        "code": 422,
        "success": false,
        "message": "Validation Error.",
        "response_time": "0.24134182929993 s"
    },
    "errors": {
        "meta": [
            "The meta must contain 3 items."
        ],
        "meta.service_id": [
            "The meta.service id field is required."
        ]
    }
}

POST api/transaction/status

POST
https://payment-book.hs.domonk.co.uk/gate
/api/transaction/status
requires authentication

Headers

X-REQUEST-TOKEN-NAME
Example:
token-name
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
$curl = curl_init();

$tokenName = 'token-name';
$tokenSecret = 'secret-key';

$payload = [
    'meta' => [
        'service_id' => 100,
        'reference_id' => 'external-reference-id',
    ],
];

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://payment-book.hs.domonk.co.uk/gate/api/transaction/status',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode(\PB\Signer::sign($payload, $tokenSecret)),
    CURLOPT_HTTPHEADER => [
        'X-REQUEST-TOKEN-NAME: ' . $tokenName,
        'Content-Type: application/json',
        'Accept: application/json',
    ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo 'cURL Error #:' . $err;
} else {
    $response = json_decode($response, true);
    print_r($response);
}
Example response:
{
    "meta": {
        "code": 200,
        "success": true,
        "message": "Transaction status request successful",
        "response_time": "0.70079708099365 s"
    },
    "data": {
        "id": 1200,
        "ulid": "01KS8KBXCEXY26RFKA99BQ23A0",
        "reference_id": "PIx38sKzZTwLqnYI2Z8W",
        "service_id": 1,
        "merchant_id": 1,
        "customer_id": 259,
        "cost": "0.30",
        "unified_error_message": "",
        "unified_error_code": 0,
        "amount": "100.00",
        "currency": "EUR",
        "type": "purchase",
        "status": "success",
        "request": {
            "meta": {
                "signature": "0a185d4f6dd28ed68b1f6c3df15f9d3a5ed0545eda1357d58f6cf98753e32d8b49f29a919ff6504b2d298ea441c0bf6e877175a05d28344d799e73b05faa3fed",
                "service_id": 1,
                "reference_id": "PIx38sKzZTwLqnYI2Z8W"
            },
            "user": {
                "zip": "RC0645",
                "city": "San Francisco",
                "email": "linda.williams@example.com",
                "phone": "+4915154456389",
                "address": "514 Main St, Miami, CA 37409",
                "country": "GB",
                "last_name": "Doe",
                "first_name": "Jane",
                "day_of_birth": "2000-01-31"
            },
            "payment": {
                "amount": "100.00",
                "currency": "EUR"
            },
            "redirect": {
                "fail": "http://merchant.site/fail",
                "return": "http://merchant.site/return",
                "success": "http://merchant.site/success"
            }
        },
        "metadata": {
            "open_banking": {
                "bank_id": "revolut",
                "bank_name": "unknown",
                "account_id": "",
                "sender_name": "Jane Doe",
                "account_iban": "unknown",
                "account_name": "unknown",
                "bank_country": "",
                "sender_email": "linda.williams@example.com",
                "account_swift": "unknown",
                "account_number": "unknown",
                "beneficiary_id": "unknown",
                "sender_details": [],
                "account_country": "",
                "account_currency": "EUR",
                "beneficiary_country": "",
                "beneficiary_customer_id": ""
            },
            "redirect_url": "http://127.0.0.1:8005/PaymentSystem/Volt/behavior/form/a65f61e3-54a2-40cd-b76c-164219c1c7bb?language=en&country=GB"
        },
        "updated_at": "2026-05-22 19:55:44",
        "created_at": "2026-05-22 19:42:31",
        "deleted_at": null,
        "service": {
            "id": 1,
            "name": "DOMONK SIA",
            "slug": "system-service",
            "user_id": 1,
            "merchant_id": 1,
            "url": "http://merchant.site/base",
            "redirect_success": "http://merchant.site/success",
            "redirect_fail": "http://merchant.site/fail",
            "redirect_return": "http://merchant.site/return",
            "request_expiration": 604800,
            "timezone": "Europe/Riga",
            "logo": "",
            "favicon": "",
            "currency": "EUR",
            "type": "ecommerce",
            "status": "active",
            "params": {
                "mailing": {
                    "payment_receipt": true,
                    "payout_receipt": true,
                    "transaction_created": true,
                    "transaction_receipt": true,
                    "subscription_receipt": true
                },
                "notifier": {
                    "telegram": [
                        "652545688"
                    ]
                },
                "payment_method": {
                    "default_alias": null
                }
            },
            "fee_group": "default",
            "fee_cost": "0.30",
            "transactions_count": 199,
            "created_at": "2026-01-09 21:02:57",
            "updated_at": "2026-05-21 22:35:05",
            "webhooks": []
        },
        "customer": {
            "id": 259,
            "service_id": 1,
            "email": "linda.williams@example.com",
            "first_name": "Jane",
            "last_name": "Doe",
            "phone": "+4915154456389",
            "day_of_birth": "2000-01-31T00:00:00.000000Z",
            "country": "GB",
            "address": "514 Main St, Miami, CA 37409",
            "city": "San Francisco",
            "zip": "RC0645",
            "language": "en",
            "created_at": "2026-05-22 19:31:31",
            "updated_at": "2026-05-22 19:31:31"
        },
        "operations": [
            {
                "id": 1208,
                "ulid": "01KS8KBXCYQ25ZB8CNCD0D3C23",
                "transaction_id": 1200,
                "transaction_reference_id": "PIx38sKzZTwLqnYI2Z8W",
                "customer_id": 259,
                "merchant_id": 1,
                "service_id": 1,
                "payment_method_id": 254,
                "payment_method_reference_id": "a65f61e3-54a2-40cd-b76c-164219c1c7bb",
                "direction": "in",
                "amount": "100.30",
                "currency": "EUR",
                "fee_group": "default",
                "fee": "2.11",
                "request": {
                    "meta": {
                        "ulid": "01KS8KBXCYQ25ZB8CNCD0D3C23",
                        "signature": "37e361fa00f6ade156fe0af080206a450e2fee2ee892ab76f6fe6de4d474123f2687c94dfaa031ef1bd51439d819fb4c22c7d54ea3daa961288aa9106cfdd59e"
                    },
                    "payment": {
                        "payment_method_id": "254"
                    },
                    "additional_data": {
                        "client_ip": "192.168.65.1",
                        "client_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.0.0 Safari/537.36",
                        "payment_method_bank": "revolut",
                        "payment_method_country": "GB"
                    }
                },
                "metadata": {
                    "open_banking": {
                        "bank_id": "revolut",
                        "bank_name": "unknown",
                        "account_id": "",
                        "sender_name": "Jane Doe",
                        "account_iban": "unknown",
                        "account_name": "unknown",
                        "bank_country": "",
                        "sender_email": "linda.williams@example.com",
                        "account_swift": "unknown",
                        "account_number": "unknown",
                        "beneficiary_id": "unknown",
                        "sender_details": [],
                        "account_country": "",
                        "account_currency": "EUR",
                        "beneficiary_country": "",
                        "beneficiary_customer_id": ""
                    },
                    "redirect_url": "http://127.0.0.1:8005/PaymentSystem/Volt/behavior/form/a65f61e3-54a2-40cd-b76c-164219c1c7bb?language=en&country=GB"
                },
                "errors": [],
                "code": 0,
                "message": "",
                "type": "payment",
                "status": "success",
                "confirmed_at": "2026-05-22 19:42:42",
                "created_at": "2026-05-22 19:42:31",
                "updated_at": "2026-05-22 19:55:38"
            }
        ]
    }
}
{
    "meta": {
        "code": 401,
        "success": false,
        "message": "Unauthorized.",
        "response_time": "0.37983679771423 s"
    },
    "errors": null
}
{
    "meta": {
        "code": 422,
        "success": false,
        "message": "Validation Error.",
        "response_time": "0.24134182929993 s"
    },
    "errors": {
        "meta": [
            "The meta must contain 3 items."
        ],
        "meta.service_id": [
            "The meta.service id field is required."
        ]
    }
}

POST api/operation/receipt

POST
https://payment-book.hs.domonk.co.uk/gate
/api/operation/receipt
requires authentication

Download operation receipt

Downloads a PDF receipt for the selected operation. Returns a JSON error response if the PDF is not available or the operation was not successful.

Headers

X-REQUEST-TOKEN-NAME
Example:
token-name
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
$curl = curl_init();

$tokenName = 'token-name';
$tokenSecret = 'secret-key';

$payload = [
    'meta' => [
        'service_id' => 100,
        'ulid' => 'operation-ulid',
    ],
];

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://payment-book.hs.domonk.co.uk/gate/api/operation/receipt',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode(\PB\Signer::sign($payload, $tokenSecret)),
    CURLOPT_HTTPHEADER => [
        'X-REQUEST-TOKEN-NAME: ' . $tokenName,
        'Content-Type: application/json',
        'Accept: application/json',
    ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo 'cURL Error #:' . $err;
} else {
    $response = json_decode($response, true);
    print_r($response);
}
Example response:
<<binary PDF content>>
{
    "meta": {
        "code": 400,
        "success": false,
        "message": "Cannot get receipt for this operation.",
        "response_time": "0.1 s"
    },
    "errors": null
}
{
    "meta": {
        "code": 401,
        "success": false,
        "message": "Unauthorized.",
        "response_time": "0.88372492790222 s"
    },
    "errors": null
}
{
    "meta": {
        "code": 404,
        "success": false,
        "message": "Not found",
        "response_time": "0.39620399475098 s"
    },
    "errors": null
}
{
    "meta": {
        "code": 422,
        "success": false,
        "message": "Validation Error.",
        "response_time": "0.24134182929993 s"
    },
    "errors": {
        "meta": [
            "The meta must contain 3 items."
        ],
        "meta.signature": [
            "The meta.signature field is required."
        ]
    }
}

POST api/payment-methods

POST
https://payment-book.hs.domonk.co.uk/gate
/api/payment-methods

Headers

X-REQUEST-TOKEN-NAME
Example:
token-name
Content-Type
Example:
application/json
Accept
Example:
application/json

Query Parameters

meta
object
required

Must have at least 2 items. Must not have more than 3 items.

Example:
[]
meta.signature
string
required
Example:
quia
meta.service_id
integer
required

Must match an existing stored value.

Example:
18
meta.reference_id
string

Must not be greater than 100 characters.

Example:
ppkjeqdoigpq
country
string

Two-letter ISO country code. Must be 2 characters.

Example:
UK
currency
string

Three-letter ISO currency code. Must be 3 characters.

Example:
USD
payment_method_id
integer

Payment Method ID. Must match an existing stored value.

Example:
1
data
string[]
Example:
["reiciendis"]

Body Parameters

Example request: 
$curl = curl_init();

$tokenName = 'token-name';
$tokenSecret = 'secret-key';


curl_setopt_array($curl, [
    CURLOPT_URL => 'https://payment-book.hs.domonk.co.uk/gate/api/payment-methods',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'X-REQUEST-TOKEN-NAME: ' . $tokenName,
        'Content-Type: application/json',
        'Accept: application/json',
    ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo 'cURL Error #:' . $err;
} else {
    $response = json_decode($response, true);
    print_r($response);
}
Example response:
{
    "meta": {
        "code": 200,
        "success": true,
        "message": "Payment system public data gathered.",
        "response_time": "0.044358968734741 s"
    },
    "data": [
        {
            "id": 251,
            "name": "Skrill",
            "description": "Pay by Skrill",
            "public_data": null,
            "alias": "skrill",
            "logo": "",
            "is_public": "yes",
            "pp_behavior": "redirect",
            "timeout": 0,
            "currencies": [
                {
                    "id": 5,
                    "payment_method_id": 251,
                    "currency": "EUR",
                    "status": "active",
                    "created_at": "2026-01-20T14:28:06.000000Z",
                    "updated_at": "2026-01-20T14:28:06.000000Z"
                },
                {
                    "id": 4,
                    "payment_method_id": 251,
                    "currency": "USD",
                    "status": "disabled",
                    "created_at": "2026-01-20T14:28:00.000000Z",
                    "updated_at": "2026-01-20T14:28:02.000000Z"
                }
            ],
            "request_params": [],
            "created_at": "2026-01-20T09:35:47.000000Z",
            "updated_at": "2026-01-20T09:53:55.000000Z"
        },
        {
            "id": 252,
            "name": "Neteller",
            "description": "Pay by Neteller",
            "public_data": null,
            "alias": "neteller",
            "logo": "",
            "is_public": "yes",
            "pp_behavior": "redirect",
            "timeout": 0,
            "currencies": [
                {
                    "id": 6,
                    "payment_method_id": 252,
                    "currency": "EUR",
                    "status": "active",
                    "created_at": "2026-01-20T14:28:16.000000Z",
                    "updated_at": "2026-01-20T14:28:16.000000Z"
                }
            ],
            "request_params": [],
            "created_at": "2026-01-20T09:36:22.000000Z",
            "updated_at": "2026-01-20T09:53:03.000000Z"
        }
    ]
}
{
    "meta": {
        "code": 401,
        "success": false,
        "message": "Unauthorized.",
        "response_time": "0.88372492790222 s"
    },
    "errors": null
}

Public

GET api/public/countries

GET
https://payment-book.hs.domonk.co.uk/gate
/api/public/countries

Retrieve the list of supported countries.

Note: Unauthenticated or unknown clients are limited to 6 requests per minute.

Headers

Content-Type
Example:
application/json
Accept
Example:
application/json
Example request: 
$curl = curl_init();

$tokenName = 'token-name';
$tokenSecret = 'secret-key';


curl_setopt_array($curl, [
    CURLOPT_URL => 'https://payment-book.hs.domonk.co.uk/gate/api/public/countries',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Accept: application/json',
    ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo 'cURL Error #:' . $err;
} else {
    $response = json_decode($response, true);
    print_r($response);
}
Example response:
{
    "meta": {
        "code": 200,
        "success": true,
        "message": "Countries retrieved.",
        "response_time": "0.00s"
    },
    "data": [
        {
            "id": 1,
            "name": "United Kingdom",
            "iso_alpha2": "GB",
            "iso_alpha3": "GBR",
            "dialing_code": "+44",
            "region": "Europe",
            "timezone": "Europe/London",
            "status": "active",
            "created_at": "2026-05-20 12:00:00",
            "updated_at": "2026-05-20 12:00:00"
        },
        {
            "id": 2,
            "name": "United States",
            "iso_alpha2": "US",
            "iso_alpha3": "USA",
            "dialing_code": "+1",
            "region": "Americas",
            "timezone": "America/New_York",
            "status": "active",
            "created_at": "2026-05-20 12:00:00",
            "updated_at": "2026-05-20 12:00:00"
        }
    ]
}

GET api/public/currencies

GET
https://payment-book.hs.domonk.co.uk/gate
/api/public/currencies

Retrieve the list of available currencies.

Note: Unauthenticated or unknown clients are limited to 6 requests per minute.

Headers

Content-Type
Example:
application/json
Accept
Example:
application/json
Example request: 
$curl = curl_init();

$tokenName = 'token-name';
$tokenSecret = 'secret-key';


curl_setopt_array($curl, [
    CURLOPT_URL => 'https://payment-book.hs.domonk.co.uk/gate/api/public/currencies',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Accept: application/json',
    ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo 'cURL Error #:' . $err;
} else {
    $response = json_decode($response, true);
    print_r($response);
}
Example response:
{
    "meta": {
        "code": 200,
        "success": true,
        "message": "Currencies retrieved.",
        "response_time": "0.00s"
    },
    "data": [
        {
            "id": 1,
            "name": "Euro",
            "code": "EUR",
            "fiat": "yes",
            "decimals": 2,
            "params": [],
            "status": "active",
            "created_at": "2026-05-20 12:00:00",
            "updated_at": "2026-05-20 12:00:00"
        },
        {
            "id": 2,
            "name": "US Dollar",
            "code": "USD",
            "fiat": "yes",
            "decimals": 2,
            "params": [],
            "status": "active",
            "created_at": "2026-05-20 12:00:00",
            "updated_at": "2026-05-20 12:00:00"
        }
    ]
}

REFERENCE

Here you can find information about additional services, tutorials, configuration guides, and helpful setup tips for extra integrations.

Webhooks

Setting Up Webhooks

Webhooks can be configured through the backoffice Services & API Tokens → Select Service → Webhooks. Once set up, they will automatically trigger when an event occurs in the system. You will need to provide an endpoint URL to which the data will be sent. HTTPS is Required for this action.

Make sure your system is ready to handle these incoming requests (POST+HTTPS).

Webhook Event
transaction.status
requires backoffice setup

This webhook is triggered when the status of a transaction changes. The payload contains detailed information about the transaction.

    {
        "meta": {
            "signature": "request-signature-hash-with-service-secret_key",
            "reference_id": "payment-unique-id",
            "service_id": 11
        },
        "data": {
            "id": 20,
            "cost": "0.54",
            "type": "purchase",
            "ulid": "494d7969-3d84-49c3-812b-2fbbc1944e4a",
            "amount": "100.00",
            "currency": "EUR",
            "status": "created",
            "request": { "initial_request": "..." },
            "reference_id": "payment-unique-id",
            "service_id": 11,
            "updated_at": "2025-01-29 23:44:15",
            "customer_id": 10,
            "merchant_id": 11,
            "redirect_url": "https://service.domain/payment/494d7969-3d84-49c3-812b-2fbbc1944e4a",
            "unified_error_code": 0,
            "unified_error_message": "",
            "metadata": null,
            "created_at": "2025-01-29 23:44:10",
            "service": {
                "id": 11,
                "url": "https://service.domain",
                "name": "MY TEST",
                "slug": "my-test",
                "type": "unknown",
                "params": [],
                "status": "active",
                "user_id": 6,
                "currency": "EUR",
                "fee_cost": "0.54",
                "webhooks": [
                    {
                        "id": 1,
                        "url": "https://test.webhook.domain",
                        "status": "active",
                        "created_at": "2025-01-26T23:36:53.000000Z",
                        "deleted_at": null,
                        "service_id": 11,
                        "updated_at": "2025-01-26T23:36:53.000000Z"
                    }
                ],
                "fee_group": "default",
                "created_at": "2025-01-26 23:34:39",
                "updated_at": "2025-01-26 23:36:15",
                "merchant_id": 11,
                "redirect_fail": "https://service.domain/fail",
                "request_expiration": 86300,
                "transactions_count": 20,
                "redirect_return": "https://service.domain/return",
                "redirect_success": "https://service.domain/success"
            },
            "operations": [
                {
                    "id": 20,
                    "fee": "2.84",
                    "type": "payment",
                    "ulid": "1496ddaa-3f8e-4bdb-baea-cab587582466",
                    "amount": "100.54",
                    "errors": null,
                    "status": "created",
                    "message": "",
                    "currency": "EUR",
                    "metadata": null,
                    "direction": "in",
                    "fee_group": "default",
                    "created_at": "2025-01-29 23:44:10",
                    "code": 0,
                    "service_id": 11,
                    "updated_at": "2025-01-29 23:44:10",
                    "merchant_id": 11,
                    "confirmed_at": null,
                    "transaction_id": 20,
                    "transaction_reference_id": "payment-unique-id",
                    "payment_method_id": 1,
                    "payment_method_reference_id": ""
                }
            ]
        }
    }
Webhook Event
not available yet 
operation.status
requires backoffice setup

This webhook is triggered when the status of an operation changes. The payload contains detailed information about the operation.

    {
        "meta": {
            "signature": "request-signature-hash-with-service-secret_key",
            "reference_id": "payment-unique-id",
            "service_id": 11
        },
        "data": {
            "id": 20,
            "fee": "2.84",
            "type": "payment",
            "ulid": "1496ddaa-3f8e-4bdb-baea-cab587582466",
            "amount": "100.54",
            "errors": null,
            "status": "created",
            "message": "",
            "currency": "EUR",
            "metadata": null,
            "direction": "in",
            "fee_group": "default",
            "created_at": "2025-01-29 23:44:10",
            "code": 0,
            "service_id": 11,
            "updated_at": "2025-01-29 23:44:10",
            "merchant_id": 11,
            "confirmed_at": null,
            "transaction_id": 20,
            "transaction_reference_id": "payment-unique-id",
            "payment_method_id": 1,
            "payment_method_reference_id": ""
        }
    }

Statuses

Transaction/​Operation Flow Statuses and Error Code Explanation

This section explains the various transaction statuses and their meanings.

Note: Transactions strictly use Unified Codes and Messages to ensure standardized error reporting. Operations may expose internal system codes as well as raw external gateway responses. Operation data may be viewed only in backoffice.

Transaction Details

Types

Type Description
purchase A standard purchase transaction.
withdrawal A withdrawal transaction to a merchant or private person from balance.
recurring A recurring transaction such as a subscription.

Statuses

Status Description
created The transaction has been created but not yet processed.
processing The transaction is currently being processed.
success The transaction was completed successfully.
refunded The transaction amount has been fully refunded.
partially_refunded The transaction amount has been partially refunded.
failed The transaction failed due to an error.
expired The transaction has expired without being completed.
active (only for recurring) The transaction is active and ongoing.
canceled (only for recurring) The transaction was canceled by the user or system.

Error Codes (Unified)

Note: Unmapped external system error codes will safely fall back to 100 (Ex. [#100] General decline).

Error codes are categorized by their logical prefix: 1XX series indicates an internal system error, whereas the 3XX series indicates a third-party gateway or external processor error.

Code Description
0 Success
100 General decline
110 Internal error
120 Internal timeout
310 Gate validation
320 Gate error
330 Gate timeout
340 Gate cancellation
999 Error not provided

Error Messages (Unified)

Note: Unmapped external system error messages will safely fall back to General decline. (Ex. [#100] General decline)

Message
Awaiting processing.
Error occured.
Error: message not provided.
Failed to update subscription. Support: %s
Failed while cancelling subscription, contact system administrator: %s
Gate error.
Gate timeout.
Gate validation error.
General decline.
Invalid amount or currency.
Timeout: final status not obtained within the expected time.
Transaction canceled by the user.

Operation Details

Types

Type Description
payment A standard payment operation.
payout A payout operation to a merchant or private user.
subscription A recurring subscription operation.
refund A refund of a transaction.

Statuses

Status Description
created The operation has been created and can be processed.
awaiting_confirmation The operation is awaiting confirmation to proceed.
processing The operation is currently being processed.
external_processing The operation is being processed by an external gateway or system.
success The operation was completed successfully.
partial_success The operation was partially successful. Treat this as failed.
expired The operation has expired without being completed.
failed The operation failed due to an error.
cancelled The operation was cancelled by the user or system.

Error Codes (System & External)

Note: Operation error codes may also include raw responses from third-party processors depending on routing.

Code Description
0 Success
1 Pre success
28100 Fee calculation failed
28101 Invalid amount or currency
28102 Not enough balance to hold
28103 Un hold failed
28104 Gate exception
28105 Internal expire
28106 Failed via status check
28107 Network error
28108 Gate internal error
28109 Canceled
28999 Error not provided

Error Messages (System)

Note: Operation errors may also include raw text responses from third-party processors depending on routing.

Message
Awaiting first payment.
Cancelled by the user.
Don't have enough available balance.
General network error. [%s:%d]
Hold balance failed while unhold.
Invalid amount or currency. Requested: %s, Received: %s
Next billing date is not defined.
Operation failed.
Operation is pre-approved and successful, waiting for final confirmation from the provider.
Timeout: final status for the subscription operation was not obtained by %s.
Timeout: the final status of the operation was not obtained within %d seconds.
Wrong gate status: %s.

HTTP Bridge

Overview & Features

The HTTP Bridge is a dedicated microservice that acts as an intelligent proxy between the main PAYMENT BOOK ecosystem and external third-party payment providers.

The core concept of the Bridge is a zero-code integration strategy for merchants. You can instantly acquire all advanced Gateway features simply by altering endpoint URLs in your existing e-commerce systems to route through the Bridge. This transparently translates traffic to the PAYMENT BOOK GATE DIRECT API, completely bypassing the need for any custom code integration or complex development work on your end.

Main Features

Available Bridges

Currently, the HTTP Bridge natively supports standardized integrations for:

Backoffice Setup Guidelines

To enable and configure a provider through the HTTP Bridge in the Backoffice:

INTEGRATIONS

Payment Providers

- GATEWAYS, ACQUIRERS, DIGITAL WALLETS AND ALTERNATIVE PAYMENT METHODS (APMS)

PAYMENT BOOK comes with turnkey, pre-built integrations for industry-leading payment gateways, acquiring processors, digital wallets, and alternative payment methods (APMs). All providers are unified under a single standard API, allowing you to configure routing rules, activate payment methods in the Backoffice, or migrate seamlessly using the Zero-Code HTTP Bridge.

Braintree

Payment Gateway / Acquirer
braintreepayments.com
Direct Hub Integration
Implemented Methods
Payment Refund Subscription Callback Check Status Public Data

Full-stack global payment gateway and acquiring platform by PayPal. Supports major international credit and debit card brands (Visa, Mastercard, American Express, Discover, JCB, Diners Club), card tokenization, client token generation for drop-in checkouts, automated subscription billing, settlement tracking, and 3D Secure verification. Also serves as the foundational acquiring engine for PayPal, Apple Pay, and Google Pay integrations.

BtcBit

Crypto & APM Gateway
btcbit.net
Direct Hub Integration
Implemented Methods
Payment Callback Check Status

Licensed European cryptocurrency and alternative payment method (APM) gateway. Enables secure crypto payments, instant fiat-to-crypto settlements, and regional electronic wallet and voucher processing (Skrill, Neteller, Rapid Transfer, Paysafecard) with automated transaction polling and real-time status callbacks.

Klyme

Open Banking / Bank Transfers
klyme.com
Direct Hub Integration
Implemented Methods
Payment Check Status Public Data

Next-generation European Open Banking and Account-to-Account (A2A) payment gateway. Connects directly to European banking networks via PSD2 APIs, providing instant bank institution discovery, direct account authorization, and real-time payment status inquiries.

PayNetEasy

Card Processing Gateway
payneteasy.com
Direct Hub Integration
Implemented Methods
Payment Callback Check Status Refund

Enterprise payment engine and white-label gateway supporting global merchant card acquiring. Implements 3D-Secure 2.x card authorization, asynchronous server-to-server webhook callbacks, transaction status validation, and automated full/partial refund processing.

Spell

Payment Gateway / Acquirer
wespell.com
Direct Hub Integration
Implemented Methods
Payment Callback Check Status

Modern merchant payment platform delivering frictionless checkout experiences across the Nordic and European markets. Supports multi-currency purchases, dynamic status checks, and instant callback notifications for digital commerce.

Volt

Real-Time Open Banking (A2A)
volt.io
Direct Hub Integration
Implemented Methods
Payment Callback Check Status Public Data Refund

Global real-time Open Banking payments network interconnecting thousands of banks across Europe, the UK, and beyond. Provides bank directory discovery, instant account-to-account payments, OAuth token caching, automated transaction reconciliation, refunds, and webhook event handling.

Yapily

Open Banking API Platform
yapily.com
Direct Hub Integration
Implemented Methods
Payment Check Status Public Data

Leading European enterprise Open Banking API platform. Offers direct access to bank payment rails across the UK and Europe, institution selection, secure payment authorization, and real-time bank transfer status tracking with high compliance standards.

PayPal

Digital Wallet
paypal.com
Integrated via Braintree Hub
Implemented Methods
Payment Check Status Callback Refund Subscription

Global digital wallet processed via the Braintree gateway integration. Enables one-click PayPal checkout, buyer protection, recurring billing agreements for subscription services, automated refund capabilities, and webhook status notifications.

Apple Pay

Mobile / Digital Wallet
apple.com/apple-pay
Integrated via Braintree Hub
Implemented Methods
Payment Check Status Callback Refund Subscription

Frictionless biometric one-touch payments (Face ID and Touch ID) on iOS and macOS Safari devices, tokenized via the Braintree gateway. Supports merchant domain validation, recurring subscription tokens, and automated refunds.

Google Pay

Mobile / Digital Wallet
pay.google.com
Integrated via Braintree Hub
Implemented Methods
Payment Check Status Callback Refund Subscription

Fast, encrypted checkout using payment methods stored in Google Accounts across Android devices and Chrome browsers, processed via Braintree tokenization. Supports one-time payments, recurring subscriptions, and refunds.

Skrill

Alternative Payment Method (APM)
skrill.com
Integrated via BtcBit Hub
Implemented Methods
Payment Check Status Callback

Popular multi-currency digital e-wallet supporting international online payments, fast deposits, and instant account balance transfers, processed via the BtcBit gateway with real-time webhook status callbacks.

Neteller

Alternative Payment Method (APM)
neteller.com
Integrated via BtcBit Hub
Implemented Methods
Payment Check Status Callback

Global electronic money transfer service and digital wallet designed for high-frequency digital commerce and cross-border transactions, processed via the BtcBit APM pipeline with automated status updates.

Rapid Transfer

Instant Online Banking
rapidtransfer.com
Integrated via BtcBit Hub
Implemented Methods
Payment Check Status Callback

Instant bank transfer service by Paysafe connecting over 3,000 European banks. Customers pay directly from their bank account using familiar online banking credentials without leaving the merchant flow.

Paysafecard

Prepaid Voucher
paysafecard.com
Integrated via BtcBit Hub
Implemented Methods
Payment Check Status Callback

World-leading prepaid payment card solution allowing customers to pay online safely without sharing credit card or bank details by using a 16-digit PIN voucher, processed through the BtcBit gateway.

WooCommerce Plugin

GitHub

WooCommerce Plugin is a ready-to-use plugin for WordPress/WooCommerce to start accepting payments through our API. It simplifies the integration process, allowing you to quickly enable payments on your e-commerce store.

SDK Signer

GitHub

PHP SDK: Signer is a lightweight PHP library for generating and validating cryptographic signatures for API requests. It ensures secure communication and prevents data tampering.

Cryptographic Signature Algorithm (HMAC-SHA-512)

The meta.signature field is computed using a 5-step canonicalization and hashing algorithm:

1. Exclude Signature: If the payload already contains a meta.signature key, it is excluded before calculating the hash.

2. Recursive Key Sorting (ksort): All dictionary and associative array keys are recursively sorted in ascending alphabetical order (lexicographical string comparison).

3. Whitespace Normalization: All string values have leading and trailing whitespace trimmed, and internal consecutive whitespace characters are normalized (collapsed into a + symbol).

4. Deterministic Serialization: The sorted data structure is serialized into a deterministic string representation matching PHP's native serialization schema (e.g. a:2:{s:4:"data";...}).

5. HMAC-SHA-512 Computation: Generate the final signature using the sha512 algorithm and your secret token key:

$signature = hash_hmac('sha512', $serializedPayload, $secretKey);

Installation & Usage:

Install the official library via Composer:

composer require payment_book/signer

Quick PHP example to sign outgoing requests and validate incoming webhooks:

use PB\Signer;

// 1. Prepare your request payload (service_id inside meta)
$payload = [
    'meta' => ['service_id' => 10],
    'data' => [
        'order_id' => 'ORD-10023',
        'amount' => 50.00,
        'currency' => 'EUR',
    ],
];

// 2. Cryptographically sign the request (injects meta.signature)
$signedPayload = Signer::sign($payload, $secretKey);

// 3. Validate incoming webhooks or responses
$isValid = Signer::validate($incomingWebhookData, $secretKey);

USEFUL LINKS

© 2026 PAYMENT BOOK. All rights reserved.