PAYMENT BOOK - GATE API

Postman collection →

Introduction

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

Base URL: https://payment-book.com

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

Authenticating requests

To authenticate requests, include a parameter meta.signature in the body of the request.

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

You can retrieve your token by visiting dashboard and clicking Services >> Generate API Token.

GATE Direct

These endpoints protected with custom authorization, request should be signed using PHP SDK - https://payment-book.com/lib/signer-1.0.0.zip

PURCHASE

POST api/transaction/purchase/create

POST

https://payment-book.com

/api/transaction/purchase/create

requires authentication

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

Headers

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

meta

object

required

Meta information. Must contain 3 items.

payment

object

required

Payment details. Must contain 2 items.

user

object

required

user personal information. Must have at least 2 items.

string

required

Must be a valid email address.

Example:

someone@example.com

phone

string

required

Must not be greater than 25 characters. Must be at least 6 characters.

Example:

shapphfjqiwcqxrulmhb

name

string

Example:

quasi

surname

string

Example:

aperiam

address

string

Example:

vel

day_of_birth

string

Must be a valid date in the format Y-m-d.

Example:

2025-04-09

city

string

Must not be greater than 80 characters.

Example:

xxqyodubheadxu

zip

string

Must not be greater than 30 characters.

Example:

vcfzcvotizdrcewwubalzgkzt

country

string

Must not be greater than 2 characters.

Example:

language

string

Must not be greater than 2 characters.

Example:

webhook

object

URLs used to override service settings and send webhook somewhere else. SSL required.

redirect

object

URLs used to override service settings and return users form payment page somewhere else. SSL required.

company

object

Company legal data.

name

string

Must not be greater than 50 characters.

Example:

Company name

tax_id

string

Must not be greater than 30 characters.

Example:

Tax/Vat number

bank_name

string

Must not be greater than 30 characters.

Example:

AS SOME BANK

bank_account

string

Must not be greater than 25 characters.

Example:

HB49SAAD93848485849948490

bank_swift

string

Must not be greater than 30 characters.

Example:

SW2IS23

address

string

Must not be greater than 255 characters.

Example:

Belgium, Some address 123a-2121, BL-2312.

order

string[][]

price

number

Must be between 1 and 10000.

Example:

currency

string

Must not be greater than 5 characters.

Example:

tip

textual

string

Example:

dolores

object

additional_data

string[]

Example:

["eligendi"]

Example request:

$client = new \GuzzleHttp\Client();
$url = 'https://payment-book.com/api/transaction/purchase/create';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'meta' => [
                'signature' => 'signed_request_token',
                'service_id' => 948,
                'payment_id' => 'your-id-1744241274',
            ],
            'payment' => [
                'price' => '100.00',
                'currency' => 'EUR',
            ],
            'user' => [
                'country' => 'CZ',
                'first_name' => 'Equuer',
                'last_name' => 'Duhhoney',
                'email' => 'someone@example.com',
                'phone' => 'shapphfjqiwcqxrulmhb',
                'name' => 'quasi',
                'surname' => 'aperiam',
                'address' => 'vel',
                'day_of_birth' => '2025-04-09',
                'city' => 'xxqyodubheadxu',
                'zip' => 'vcfzcvotizdrcewwubalzgkzt',
                'language' => 'q',
            ],
            'webhook' => [
                'url' => 'https://your-service-domain.com/callback-handler',
                'token_name' => 'SOME TOKEN NAME',
            ],
            'redirect' => [
                'success_url' => 'https://your-service-domain.com/success',
                'fail_url' => 'https://your-service-domain.com/fail',
                'return_url' => '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.',
            ],
            'additional_data' => [
                'eligendi',
            ],
        ],
    ]
);
$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/0a553d60-8228-422c-b535-b1cabb6d34ea"
    }
}

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_url|fail_url|return_url accordingly of the result and send webhook to service

Headers

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

meta

object

required

Meta information. Must contain 3 items.

payment

object

required

Payment details. Must contain 2 items.

recurring

object

required

Recurring details.

enabled

boolean

required

Example:

false

start_date

string

Must be a valid date in the format Y-m-d\TH:i:sP.

Example:

2024-11-18T22:45:55+00:00

end_date

string

Must be a valid date in the format Y-m-d\TH:i:sP. Must be a date after recurring.start_date.

Example:

2107-09-08

cycle_days

integer

Must be between 1 and 730.

Example:

trial_days

integer

Must be between 1 and 730.

Example:

user

object

required

User personal information. Must have at least 2 items.

string

required

Must be a valid email address.

Example:

someone@example.com

phone

string

required

Must not be greater than 25 characters. Must be at least 6 characters.

Example:

fqdmpezlurtlaonoqywguadapsdvwzdmvlyagylkmwruqjjbadtlclqrcntwxbguwsmrnrbcyhczdccdrowfv

name

string

Example:

nulla

surname

string

Example:

provident

address

string

Example:

eum

day_of_birth

string

Must be a valid date in the format Y-m-d.

Example:

2025-04-09

city

string

Must not be greater than 80 characters.

Example:

krcgaxutlmlmpqaup

zip

string

Must not be greater than 30 characters.

Example:

lnjejyxtzsqz

country

string

Must not be greater than 2 characters.

Example:

language

string

Must not be greater than 2 characters.

Example:

webhook

object

URLs used to override service settings and send webhook somewhere else. SSL required.

redirect

object

URLs used to override service settings and return users form payment page somewhere else. SSL required.

company

object

Company legal data.

name

string

Must not be greater than 50 characters.

Example:

Company name

tax_id

string

Must not be greater than 30 characters.

Example:

Tax/Vat number

bank_name

string

Must not be greater than 30 characters.

Example:

AS SOME BANK

bank_account

string

Must not be greater than 25 characters.

Example:

HB49SAAD93848485849948490

bank_swift

string

Must not be greater than 30 characters.

Example:

SW2IS23

address

string

Must not be greater than 255 characters.

Example:

Belgium, Some address 123a-2121, BL-2312.

order

string[][]

additional_data

string[]

Example:

["saepe"]

Example request:

$client = new \GuzzleHttp\Client();
$url = 'https://payment-book.com/api/transaction/recurring/create';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'meta' => [
                'signature' => 'signed_request_token',
                'service_id' => 948,
                'payment_id' => 'your-id-1744241274',
            ],
            'payment' => [
                'price' => '100.00',
                'currency' => 'EUR',
            ],
            'recurring' => [
                'enabled' => true,
                'start_date' => '2024-11-18T22:45:55+00:00',
                'end_date' => '2107-09-08',
                'cycle_days' => 2,
                'trial_days' => 1,
            ],
            'user' => [
                'country' => 'CZ',
                'first_name' => 'Equuer',
                'last_name' => 'Duhhoney',
                'email' => 'someone@example.com',
                'phone' => 'fqdmpezlurtlaonoqywguadapsdvwzdmvlyagylkmwruqjjbadtlclqrcntwxbguwsmrnrbcyhczdccdrowfv',
                'name' => 'nulla',
                'surname' => 'provident',
                'address' => 'eum',
                'day_of_birth' => '2025-04-09',
                'city' => 'krcgaxutlmlmpqaup',
                'zip' => 'lnjejyxtzsqz',
                'language' => 'q',
            ],
            'webhook' => [
                'url' => 'https://your-service-domain.com/callback-handler',
                'token_name' => 'repudiandae',
            ],
            'redirect' => [
                'success_url' => 'https://your-service-domain.com/success',
                'fail_url' => 'https://your-service-domain.com/fail',
                'return_url' => '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.',
            ],
            'additional_data' => [
                'saepe',
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

const url = new URL(
    "https://payment-book.com/api/transaction/recurring/create"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "meta": {
        "signature": "signed_request_token",
        "service_id": 948,
        "payment_id": "your-id-1744241274"
    },
    "payment": {
        "price": "100.00",
        "currency": "EUR"
    },
    "recurring": {
        "enabled": true,
        "start_date": "2024-11-18T22:45:55+00:00",
        "end_date": "2107-09-08",
        "cycle_days": 2,
        "trial_days": 1
    },
    "user": {
        "country": "CZ",
        "first_name": "Equuer",
        "last_name": "Duhhoney",
        "email": "someone@example.com",
        "phone": "fqdmpezlurtlaonoqywguadapsdvwzdmvlyagylkmwruqjjbadtlclqrcntwxbguwsmrnrbcyhczdccdrowfv",
        "name": "nulla",
        "surname": "provident",
        "address": "eum",
        "day_of_birth": "2025-04-09",
        "city": "krcgaxutlmlmpqaup",
        "zip": "lnjejyxtzsqz",
        "language": "q"
    },
    "webhook": {
        "url": "https:\/\/your-service-domain.com\/callback-handler",
        "token_name": "repudiandae"
    },
    "redirect": {
        "success_url": "https:\/\/your-service-domain.com\/success",
        "fail_url": "https:\/\/your-service-domain.com\/fail",
        "return_url": "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."
    },
    "additional_data": [
        "saepe"
    ]
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

curl --request POST \
    "https://payment-book.com/api/transaction/recurring/create" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"meta\": {
        \"signature\": \"signed_request_token\",
        \"service_id\": 948,
        \"payment_id\": \"your-id-1744241274\"
    },
    \"payment\": {
        \"price\": \"100.00\",
        \"currency\": \"EUR\"
    },
    \"recurring\": {
        \"enabled\": true,
        \"start_date\": \"2024-11-18T22:45:55+00:00\",
        \"end_date\": \"2107-09-08\",
        \"cycle_days\": 2,
        \"trial_days\": 1
    },
    \"user\": {
        \"country\": \"CZ\",
        \"first_name\": \"Equuer\",
        \"last_name\": \"Duhhoney\",
        \"email\": \"someone@example.com\",
        \"phone\": \"fqdmpezlurtlaonoqywguadapsdvwzdmvlyagylkmwruqjjbadtlclqrcntwxbguwsmrnrbcyhczdccdrowfv\",
        \"name\": \"nulla\",
        \"surname\": \"provident\",
        \"address\": \"eum\",
        \"day_of_birth\": \"2025-04-09\",
        \"city\": \"krcgaxutlmlmpqaup\",
        \"zip\": \"lnjejyxtzsqz\",
        \"language\": \"q\"
    },
    \"webhook\": {
        \"url\": \"https:\\/\\/your-service-domain.com\\/callback-handler\",
        \"token_name\": \"repudiandae\"
    },
    \"redirect\": {
        \"success_url\": \"https:\\/\\/your-service-domain.com\\/success\",
        \"fail_url\": \"https:\\/\\/your-service-domain.com\\/fail\",
        \"return_url\": \"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.\"
    },
    \"additional_data\": [
        \"saepe\"
    ]
}"

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/0a553d60-8228-422c-b535-b1cabb6d34ea"
    }
}

POST api/transaction/recurring/cancel

POST

https://payment-book.com

/api/transaction/recurring/cancel

requires authentication

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

Headers

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

meta

object

required

Meta information. Must contain 3 items.

Example request:

$client = new \GuzzleHttp\Client();
$url = 'https://payment-book.com/api/transaction/recurring/cancel';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'meta' => [
                'signature' => 'signed_request_token',
                'service_id' => 948,
                'payment_id' => 'your-id-1744241274',
            ],
        ],
    ]
);
$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,
        "payment_id": "1111122222222",
        "uuid": "ff6bcd26-9e70-40fd-a3aa-80c8586193d1",
        "service_id": 1,
        "merchant_id": 1,
        "cost_type": "in",
        "last_error_message": "Cannot use a payment_method_nonce more than once.",
        "last_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": {
                "name": "max",
                "email": "maksimsge@gmail.com",
                "phone": "+37123446666",
                "address": "dsasdas",
                "surname": "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==",
                "payment_id": "1111122222222",
                "service_id": 1
            },
            "payment": {
                "price": 12.32,
                "currency": "EUR"
            },
            "callback": {
                "url": "https://payment-book.com/registrator/payment-status"
            },
            "redirect": {
                "fail_url": "https://payment-book.com/error-registration/1111122222222",
                "return_url": "https://payment-book.com/error-registration/1111122222222",
                "success_url": "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": {
            "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_system_transaction_id": "",
                "transaction_id": 11,
                "merchant_id": 1,
                "service_id": 1,
                "payment_system_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."
                    }
                ],
                "error_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_system_id": 1,
            "url": "http://jacobson.com/quam-dolorem-quasi-nihil",
            "redirect_success_url": "https://payment-book.com/finish-registration/{payment_id}",
            "redirect_fail_url": "https://payment-book.com/error-registration/{payment_id}",
            "redirect_return_url": "",
            "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
            }
        }
    }
}

PAYOUT

POST api/transaction/payout/create

POST

https://payment-book.com

/api/transaction/payout/create

requires authentication

Payout initialization - will create payout request to your merchant account from your balance

Headers

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

meta

object

required

Meta information. Must contain 3 items.

payment

object

required

Payment details. Must contain 2 items.

user

object

required

User personal information. Must have at least 2 items.

string

required

Must be a valid email address.

Example:

someone@example.com

phone

string

required

Must not be greater than 25 characters. Must be at least 6 characters.

Example:

wcnukjjlzrzsnfdxpoooxjuslpzazvueatgxohqsnuqfdipbemudpmfvtxzncil

name

string

Example:

eveniet

surname

string

Example:

deserunt

address

string

Example:

eaque

day_of_birth

string

Must be a valid date in the format Y-m-d.

Example:

2025-04-09

city

string

Must not be greater than 80 characters.

Example:

dyffwckmjpnmthgdwin

zip

string

Must not be greater than 30 characters.

Example:

nsateezgaseysvxnvdnirtqq

country

string

Must not be greater than 2 characters.

Example:

language

string

Must not be greater than 2 characters.

Example:

webhook

object

URLs used to override service settings and send webhook somewhere else. SSL required.

redirect

object

URLs used to override service settings and return users form payment page somewhere else. SSL required.

company

object

Company legal data.

name

string

Must not be greater than 50 characters.

Example:

Company name

tax_id

string

Must not be greater than 30 characters.

Example:

Tax/Vat number

bank_name

string

Must not be greater than 30 characters.

Example:

AS SOME BANK

bank_account

string

Must not be greater than 25 characters.

Example:

HB49SAAD93848485849948490

bank_swift

string

Must not be greater than 30 characters.

Example:

SW2IS23

address

string

Must not be greater than 255 characters.

Example:

Belgium, Some address 123a-2121, BL-2312.

order

string[][]

additional_data

string[]

Example:

["repudiandae"]

Example request:

$client = new \GuzzleHttp\Client();
$url = 'https://payment-book.com/api/transaction/payout/create';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'meta' => [
                'signature' => 'signed_request_token',
                'service_id' => 948,
                'payment_id' => 'your-id-1744241274',
            ],
            'payment' => [
                'price' => '100.00',
                'currency' => 'EUR',
            ],
            'user' => [
                'country' => 'CZ',
                'first_name' => 'Equuer',
                'last_name' => 'Duhhoney',
                'email' => 'someone@example.com',
                'phone' => 'wcnukjjlzrzsnfdxpoooxjuslpzazvueatgxohqsnuqfdipbemudpmfvtxzncil',
                'name' => 'eveniet',
                'surname' => 'deserunt',
                'address' => 'eaque',
                'day_of_birth' => '2025-04-09',
                'city' => 'dyffwckmjpnmthgdwin',
                'zip' => 'nsateezgaseysvxnvdnirtqq',
                'language' => 'on',
            ],
            'webhook' => [
                'url' => 'https://your-service-domain.com/callback-handler',
                'token_name' => 'at',
            ],
            'redirect' => [
                'success_url' => 'https://your-service-domain.com/success',
                'fail_url' => 'https://your-service-domain.com/fail',
                'return_url' => '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.',
            ],
            'additional_data' => [
                'repudiandae',
            ],
        ],
    ]
);
$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/0a553d60-8228-422c-b535-b1cabb6d34ea"
    }
}

REFUND

POST api/operation/refund

POST

https://payment-book.com

/api/operation/refund

requires authentication

Headers

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

meta

object

required

meta information. Must contain 2 items.

refund

object

required

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

Example request:

$client = new \GuzzleHttp\Client();
$url = 'https://payment-book.com/api/operation/refund';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'meta' => [
                'signature' => 'signed_request_token',
                'transaction_uuid' => 'transaction-uuid-1744241274',
            ],
            'refund' => [
                'price' => '100.00',
                'currency' => 'EUR',
                'comment' => 'necessitatibus',
            ],
        ],
    ]
);
$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",
                "last_error_message": "Amount is to low",
                "request": {
                    "meta": {
                        "signature": "c8b7e64819a3db0be9e8ef33dd05586d78bcddbd91ed621ce263f7f568ef58ca0b9057cb0f27f65bace03c082373f7b62ac43aa95ea42ece380d83139d338c86",
                        "payment_id": "2222211123-te22222st-3141124322233",
                        "merchant_id": "1"
                    },
                    "user": {
                        "email": "test@crypto-fusion.com",
                        "country": "TST",
                        "last_name": "Surname",
                        "first_name": "Name"
                    },
                    "order": {
                        "stock_id": 1,
                        "stock_rate": "56698.46",
                        "node_network_id": 1,
                        "stock_currency_code": "BTC",
                        "stock_currency_code_source": "EUR"
                    },
                    "return": {
                        "fail": "http://merchant.site/fail",
                        "return": "http://merchant.site/return",
                        "success": "http://merchant.site/success"
                    },
                    "payment": {
                        "price": "103.96",
                        "currency": "EUR"
                    }
                },
                "status": "failed",
                "created_at": "2024-06-25T08:10:18.000000Z",
                "updated_at": "2024-06-25T08:13:43.000000Z"
            }
        }
    }
}

COMMON

POST api/transaction/status

POST

https://payment-book.com

/api/transaction/status

requires authentication

Headers

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

meta

object

required

Meta information. Must contain 2 items.

Example request:

$client = new \GuzzleHttp\Client();
$url = 'https://payment-book.com/api/transaction/status';
$response = $client->post(
    $url,
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'meta' => [
                'signature' => 'signed_request_token',
                'transaction_uuid' => 'transaction-uuid',
            ],
        ],
    ]
);
$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,
        "payment_id": "1111122222222",
        "uuid": "ff6bcd26-9e70-40fd-a3aa-80c8586193d1",
        "service_id": 1,
        "merchant_id": 1,
        "cost_type": "in",
        "last_error_message": "Cannot use a payment_method_nonce more than once.",
        "last_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": {
                "name": "max",
                "email": "maksimsge@gmail.com",
                "phone": "+37123446666",
                "address": "dsasdas",
                "surname": "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==",
                "payment_id": "1111122222222",
                "service_id": 1
            },
            "payment": {
                "price": 12.32,
                "currency": "EUR"
            },
            "callback": {
                "url": "https://payment-book.com/registrator/payment-status"
            },
            "redirect": {
                "fail_url": "https://payment-book.com/error-registration/1111122222222",
                "return_url": "https://payment-book.com/error-registration/1111122222222",
                "success_url": "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": {
            "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_system_transaction_id": "",
                "transaction_id": 11,
                "merchant_id": 1,
                "service_id": 1,
                "payment_system_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."
                    }
                ],
                "error_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"
            }
        ]
    }
}

Webhooks, Statuses, etc.

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",
        "payment_id": "payment-unique-id",
        "service_id": 11
    },
    "data": {
        "transaction": {
            "id": 20,
            "cost": "0.54",
            "cost_is_hidden": "no",
            "type": "purchase",
            "uuid": "494d7969-3d84-49c3-812b-2fbbc1944e4a",
            "amount": "100.00",
            "currency": "EUR",
            "status": "created",
            "request": { initial request },
            "payment_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",
            "last_error_code": 0,
            "last_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_url": "https://service.domain/fail",
                "request_expiration": 86300,
                "transactions_count": 20,
                "redirect_return_url": "https://service.domain/return",
                "redirect_success_url": "https://service.domain/success"
            },
            "operations": [
                {
                    "id": 20,
                    "fee": "2.84",
                    "type": "sale",
                    "uuid": "1496ddaa-3f8e-4bdb-baea-cab587582466",
                    "amount": "100.54",
                    "errors": null,
                    "status": "init",
                    "message": "",
                    "currency": "EUR",
                    "metadata": null,
                    "direction": "in",
                    "fee_group": "default",
                    "created_at": "2025-01-29 23:44:10",
                    "error_code": 0,
                    "service_id": 11,
                    "updated_at": "2025-01-29 23:44:10",
                    "merchant_id": 11,
                    "confirmed_at": null,
                    "transaction_id": 20,
                    "payment_system_id": 1,
                    "payment_system_transaction_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",
        "payment_id": "payment-unique-id",
        "service_id": 11
    },
    "data": {
        "operations": [
            { ... },
            { ... },
            { ... }
        ]
    }
}

STATUES

Statuses and Error Code Explanation

This section explains the various transaction statuses and their meanings.

Transaction Types

Type	Description
purchase	A standard purchase transaction.
payout	A payout transaction to a user.
recurring	A recurring transaction such as a subscription.

Transaction Statuses

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

Operation Types

Type	Description
sale	A standard sale transaction.
payout	A payout transaction to a user.
refund	A full refund of a transaction.
subscription	A recurring payment related to a subscription.

Operation Statuses

Status	Description
init	The operation has been initialized but not processed.
created	The operation has been created and can be processed.
processing	The operation is currently being processed.
success	The operation was completed successfully.
partial_success	The operation was partially successful. Treat this as failed.
internal_error	The operation failed due to an internal error.
external_error	The operation failed due to an external system error.

Error Codes

Code	Description
0	Operation was successful.
223	Not enough balance to hold the amount. (For payout & refund)
222	Failed to un-hold the balance.(For payout & refund)
434	Fee calculator failed.

Error Messages

Message	Description
payment failed, fix errors and try again	The payment process encountered an error. Try Again.
refund successful	The refund was processed successfully.
refund failed, fix errors and try again	The refund could not be processed. Try Again.
cancelled: payment method not deleted	Subscription was canceled but payment method remains.
awaiting first payment	The subscription is waiting for the first payment.
awaiting status check confirmation	Waiting for confirmation of status check.
external processing	The transaction is being processed by an external system.
wrong gate status: %s	The provided status does not match the expected one.
operation successfully processed	The operation was successful.
invalid amount or currency	Initial request amount or currency does not match with gate.
operation failed	The operation encountered an error and failed.