navbar-image MENU

API DOCUMENTATION

Postman collection →

Introduction

Gate can process Cards, ApplePay, GooglePay, PayPal, Open Banking, APS. 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

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.com
/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.com/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' => 'a1c23e637134ef70aa1e67e6e85684ee10a2aaf7903eff75a431a762890a5582c09e391c158c5f8e5cdd764c59716ca88b7504f921f16859d341ff5c5510fb18',
                'reference_id' => 'your-id-1780351432',
                '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',
                'payment_method_bank' => 'revolut',
                'payment_method_country' => 'DE',
            ],
        ],
    ]
);
$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.com/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.com
/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.com/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' => '40676aea90608e3306440fe74899630eddedd1cbf703616b5ff015bb442641eafff9a47cdad8575a160242fe888d87e60716e0aa61090597c6a753a45cb8529c',
                'reference_id' => 'your-id-1780351433',
                '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',
                'payment_method_bank' => 'revolut',
                'payment_method_country' => 'DE',
            ],
        ],
    ]
);
$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.com/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.com
/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.com/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' => 'f5b66ac4d31f18bd2d21d52f7753b598cdec1e04ea6a7fc3416027bde531c8186a348255efdaa55da3de90e7738fde7b3e13323215b599c6a7926c354a65899e',
                'reference_id' => 'your-id-1780351433',
                '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.com/registrator/payment-status"
            },
            "redirect": {
                "fail": "https://payment-book.com/error-registration/1111122222222",
                "return": "https://payment-book.com/error-registration/1111122222222",
                "success": "https://payment-book.com/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": {
            "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.com/finish-registration/{reference_id}",
            "redirect_fail": "https://payment-book.com/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."
        ]
    }
}

Withdrawal

POST api/transaction/withdrawal/create

POST
https://payment-book.com
/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.com/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' => 'f0217bfee3b37f1403d22c64847ec73adaf8504ccd7f165a2b5fe28733ec0a94621b54d9ea451c7c34f0acbd932f83bf130a0521b155e24cd7a1e0dc2c8b776f',
                'reference_id' => 'your-id-1780351433',
                '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."
        ]
    }
}

Common

POST api/transaction/refund

POST
https://payment-book.com
/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.com/api/transaction/refund';
$response = $client->post(
    $url,
    [
        'headers' => [
            'X-REQUEST-TOKEN-NAME' => 'token-name',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'meta' => [
                'signature' => 'd6fcb7de7a3809422f97ecff52b099fab9a52eb1d458062f13646084766e90910b6a6e2534c7576133589dc0500337ed17514a576ac0adf903c3817c14bc6838',
                'reference_id' => 'external-id-1780351433',
                '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"}},"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.com
/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.com/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.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.com
/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: 
$client = new \GuzzleHttp\Client();
$url = 'https://payment-book.com/api/operation/receipt';
$response = $client->post(
    $url,
    [
        'headers' => [
            'X-REQUEST-TOKEN-NAME' => 'token-name',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'meta' => [
                'signature' => 'f005fc4330721b5b6e67a70f363927c030c1898e3b752cf025f9fba71d00d50e5f56588112e174baaeba2e8e3c6a75e0af1b4f76fa1e2bae178cbca04299b064',
                'ulid' => 'operation-ulid',
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
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.com
/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 contain 2 items.

Example:
[]
meta.signature
string
required
Example:
optio
meta.service_id
string
required

The id of an existing record in the services table.

Example:
quo
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
data
object

Dynamic parameters for gateway public data.

Example:
{"bank_id":"123"}

Body Parameters

Example request: 
$client = new \GuzzleHttp\Client();
$url = 'https://payment-book.com/api/payment-methods';
$response = $client->post(
    $url,
    [
        'headers' => [
            'X-REQUEST-TOKEN-NAME' => 'token-name',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'query' => [
            'meta[signature]' => 'optio',
            'meta[service_id]' => 'quo',
            'country' => 'UK',
            'currency' => 'USD',
            'data[bank_id]' => '123',
        ],
    ]
);
$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
}

Public

GET api/public/countries

GET
https://payment-book.com
/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: 
$client = new \GuzzleHttp\Client();
$url = 'https://payment-book.com/api/public/countries';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
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.com
/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: 
$client = new \GuzzleHttp\Client();
$url = 'https://payment-book.com/api/public/currencies';
$response = $client->get(
    $url,
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
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 may get info about additional services and tutorials, guidelines, configuration tips for additional services.

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 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
    },
    "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

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 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
1Pre success
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
Awaiting first payment.
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.
Operation is pre-approved and successful, waiting for final confirmation from the provider.
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: