navbar-image MENU

API DOCUMENTATION

Postman collection →

Introduction

Gate can process Cards, ApplePay, GooglePay, PayPal. Available methods Purchase, Recurring, Refunds.

This documentation aims to provide all the information you need to work with our API.

Security & Authentication

To ensure maximum security, our GATE DIRECT API requires requests to be cryptographically signed. We provide a lightweight PHP SDK Signer - GITHUB that automatically handles request sorting, payload flattening, and HMAC SHA-256 signature generation. You can seamlessly integrate this SDK into your application to authenticate your outgoing requests and validate incoming Webhooks.

You can retrieve your API Token by visiting the BACKOFFICE and clicking Services & API Tokens >> Select Service >> API Tokens.

GATE DIRECT API

PAYMENT


POST api/transaction/purchase/create

POST
https://payment-book.hs.domonk.co.uk
/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: 
$client = new \GuzzleHttp\Client();
$url = 'https://payment-book.hs.domonk.co.uk/api/transaction/purchase/create';
$response = $client->post(
    $url,
    [
        'headers' => [
            'X-REQUEST-TOKEN-NAME' => 'token-name',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'meta' => [
                'signature' => 'd7b7628b6c2b71f75734214e3505c662d8894024bdf2b12c634eb8c07281922855303f0aa4b23b51c7a357dde6c5ce0ac7569de39d1bdf743e91ec4cb35efccd',
                'reference_id' => 'your-id-1777580289',
                'service_id' => 9,
            ],
            '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',
                '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',
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
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/payment/0a553d60-8228-422c-b535-b1cabb6d34ea"
    }
}
{
    "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."
        ]
    }
}

WITHDRAWAL


POST api/transaction/withdrawal/create

POST
https://payment-book.hs.domonk.co.uk
/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: 
$client = new \GuzzleHttp\Client();
$url = 'https://payment-book.hs.domonk.co.uk/api/transaction/withdrawal/create';
$response = $client->post(
    $url,
    [
        'headers' => [
            'X-REQUEST-TOKEN-NAME' => 'token-name',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'meta' => [
                'signature' => '305687d660f7ff386ae068037d371b88c2c4623725c0131ae6bccfc4fb0772a8d5ecfc5762045efeacf16ad3454624e5b5e4bd40df37f1dd73a911e5aae29a0a',
                'reference_id' => 'your-id-1777580289',
                'service_id' => 9,
            ],
            'withdrawal' => [
                'amount' => '100.00',
                'currency' => 'EUR',
                'balance_id' => 99,
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
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."
        ]
    }
}

RECURRING


POST api/transaction/recurring/create

POST
https://payment-book.hs.domonk.co.uk
/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: 
$client = new \GuzzleHttp\Client();
$url = 'https://payment-book.hs.domonk.co.uk/api/transaction/recurring/create';
$response = $client->post(
    $url,
    [
        'headers' => [
            'X-REQUEST-TOKEN-NAME' => 'token-name',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'meta' => [
                'signature' => '55dac8364ad8e8664f2a7a57c86f7891bbecf1bf18ac462cdaa217748c7276f8a3897ed3d49481a942bc9c5ec21b7f26cd90b980db963ef4137bc4d9ed866b8a',
                'reference_id' => 'your-id-1777580289',
                'service_id' => 9,
            ],
            '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',
                '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',
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
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/payment/0a553d60-8228-422c-b535-b1cabb6d34ea"
    }
}
{
    "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
/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: 
$client = new \GuzzleHttp\Client();
$url = 'https://payment-book.hs.domonk.co.uk/api/transaction/recurring/cancel';
$response = $client->post(
    $url,
    [
        'headers' => [
            'X-REQUEST-TOKEN-NAME' => 'token-name',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'meta' => [
                'signature' => 'b4893e90caf9fb301c11011f172106affeb6112ae97a8d763483b28189f6890bdf2b2b3c8369a0e1967f6a6ed2abe60977654ee46648f57b02fb3916850ed001',
                'reference_id' => 'your-id-1777580289',
                'service_id' => 9,
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
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/registrator/payment-status"
            },
            "redirect": {
                "fail": "https://payment-book.hs.domonk.co.uk/error-registration/1111122222222",
                "return": "https://payment-book.hs.domonk.co.uk/error-registration/1111122222222",
                "success": "https://payment-book.hs.domonk.co.uk/error-registration/1111122222222"
            },
            "recurring": {
                "enabled": true,
                "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": {
            "gate": {
                "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/finish-registration/{reference_id}",
            "redirect_fail": "https://payment-book.hs.domonk.co.uk/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."
        ]
    }
}

REFUND


POST api/transaction/refund

POST
https://payment-book.hs.domonk.co.uk
/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: 
$client = new \GuzzleHttp\Client();
$url = 'https://payment-book.hs.domonk.co.uk/api/transaction/refund';
$response = $client->post(
    $url,
    [
        'headers' => [
            'X-REQUEST-TOKEN-NAME' => 'token-name',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'meta' => [
                'signature' => '9dfc6a7c99ab972a3d6f5e31bd99b6658b6a19e7e89fecf5588d6ec8a436a18ccba4c81ca8087db5355080a9514ab8f3cb91a67323bbbc6eba02b86f51e8bb82',
                'reference_id' => 'external-id-1777580289',
                'service_id' => 9,
            ],
            'refund' => [
                'amount' => '100.00',
                'currency' => 'EUR',
                'comment' => 'Package with defect',
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
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"
                    }
                },
                "payment_gateway": {
                    "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."
        ]
    }
}

COMMON


POST api/transaction/status

POST
https://payment-book.hs.domonk.co.uk
/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: 
$client = new \GuzzleHttp\Client();
$url = 'https://payment-book.hs.domonk.co.uk/api/transaction/status';
$response = $client->post(
    $url,
    [
        'headers' => [
            'X-REQUEST-TOKEN-NAME' => 'token-name',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'meta' => [
                'signature' => 'b49ec1b797e5207420de471f88892960d20e33e6a648be34670111e8b43afce0cfa40fdf5559849563590dd2bffd6950c31a093f0438b5a1bc37e6675ab3fde3',
                'reference_id' => 'external-reference-id',
                'service_id' => 9,
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
Example response:
{
    "meta": {
        "code": 200,
        "success": true,
        "message": "Transaction status request successful",
        "response_time": "0.18425893783569 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": {
                "signature": "FbTUZFk/nH1wuVhFT9SCg75NTZmbueiLtCwKMoYddu/g2lyrvFYK9YC9+vwSJDhXkAioPtlmJRDofr2MG8V/AQ==",
                "reference_id": "1111122222222",
                "service_id": 1
            },
            "payment": {
                "amount": 12.32,
                "currency": "EUR"
            },
            "callback": {
                "url": "https://payment-book.hs.domonk.co.uk/registrator/payment-status"
            },
            "redirect": {
                "fail": "https://payment-book.hs.domonk.co.uk/error-registration/1111122222222",
                "return": "https://payment-book.hs.domonk.co.uk/error-registration/1111122222222",
                "success": "https://payment-book.hs.domonk.co.uk/error-registration/1111122222222"
            },
            "recurring": {
                "enabled": true,
                "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": {
            "gate": {
                "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"
            }
        ]
    }
}
{
    "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/payment-methods

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

Headers

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

Body Parameters

Example request: 
$client = new \GuzzleHttp\Client();
$url = 'https://payment-book.hs.domonk.co.uk/api/payment-methods';
$response = $client->post(
    $url,
    [
        'headers' => [
            'X-REQUEST-TOKEN-NAME' => 'token-name',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'meta' => [
                'signature' => '79b93a245490d1f68e3ffd0d2783b82d34a335ba3c4a764783af34d3d774a0dcf41446595f899331861bba2c2d6065f4f09c05c91ca32753297ba642e7c02fda',
                'service_id' => 9,
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
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
}

Miscellaneous

Here you may get info about additional services and tutorials, guidelines how to configure additional service settings.

WEBHOOKS

Setting Up Webhooks

Webhooks can be configured through the backoffice Services & API Keys >> Select Service >> Webhooks\'s. 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 an 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
    },
    "transaction": {
        "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
    },
    "operation": {
        "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

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
purchaseA standard purchase transaction.
withdrawalA withdrawal transaction to a merchant or private person from balance.
recurringA recurring transaction such as a subscription.

Statuses

Status Description
createdThe transaction has been created but not yet processed.
processingThe transaction is currently being processed.
successThe transaction was completed successfully.
refundedThe transaction amount has been fully refunded.
partially_refundedThe transaction amount has been partially refunded.
failedThe transaction failed due to an error.
expiredThe 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
0Success
100General decline
110Internal error
120Internal timeout
310Gate validation
320Gate error
330Gate timeout
999Error not provided

Error Messages (Unified)

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

Message
Awaiting first payment.
Awaiting processing.
Cancelled by user.
Error occured.
Error: message not provided.
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.

Operation Details

Types

Type Description
paymentA standard payment operation.
payoutA payout operation to a merchant or private user.
subscriptionA recurring subscription operation.
refundA refund of a transaction.

Statuses

Status Description
createdThe operation has been created and can be processed.
awaiting_confirmationThe operation is awaiting confirmation to proceed.
processingThe operation is currently being processed.
external_processingThe operation is being processed by an external gateway or system.
successThe operation was completed successfully.
partial_successThe operation was partially successful. Treat this as failed.
expiredThe operation has expired without being completed.
failedThe operation failed due to an error.
cancelledThe 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
0Success
28100Fee calculation failed
28101Invalid amount or currency
28102Not enough balance to hold
28103Un hold failed
28104Gate exception
28105Internal expire
28106Failed via status check
28107Network error
28108Gate internal error
28999Error not provided

Error Messages (System)

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

Message
Don't have enough available balance.
General network error. [%s:%d]
Hold balance failed while unhold.
Invalid amount or currency. Requested: %s, Received: %s
Operation failed.
Timeout: final status for 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 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: