NAV

Введение

О сервисе

PayBox.money - универсальное средство приема платежей для бизнеса.

Сервис предоставляет возможность приема платежей, выплат на банковские карты, а также сохранения карт. Базовые сценарии описаны в разделе "Сценарии платежа".

Сценарии разделены на три части:

Каждый сценарий документации содержит все запросы которые можно выполнить для реализации выбранного сценария.

Работа с Postman

Данная документация доступна в виде Postman коллекции для HTTP-клиента Postman

Коллекция активно работает с переменными окружения Postman.

Run in Postman

Реализована динамическая генерация подписи с помощью Pre-request scripts. При правильной настройке переменных, параметр подписи будет генерироваться для каждого запроса автоматически(в консоли можно смотреть из чего была сгенерирована подпись).

Основные переменные окружения для работы с Postman:

Наименование Описание
paybox_url Базовый url для API(По умолчанию https://api.paybox.money)
paybox_merchant_id ID магазина на стороне PayBox.money
paybox_merchant_secret Секретный ключ(для приема платежей) магазина на стороне PayBox.money
paybox_merchant_secret_payout Секретный ключ(для выплат) магазина на стороне PayBox.money

Дополнительные переменные окружения:

Наименование Описание
result_url URL мерчанта для уведомления о результате оплаты
post_link URL мерчанта для уведомления о результате выплаты
check_url URL мерчанта для предварительной проверки возможности проведения платежа на стороне магазина
success_url URL мерчанта, на который PayBox.Money перенаправляет пользователя после успешной оплаты
failure_url URL мерчанта, на который PayBox.money перенаправляет пользователя после не успешной оплаты

Пример редактирования переменных окружения:

[newman gif](https://paybox.money/gifs/postman-add-variables.gif)

Механика запросов

API поддерживает GET запросы и POST запросы с Content-type равным form-data или x-www-form-urlencoded

Данные можно отправлять:

Обратная связь

Вопросы и предложения отправляйте по адресу:documentation@paybox.money

https://paybox.money

Сценарии платежей

Прием платежей

В этом разделе описана механика, при которой PayBox.money списывает деньги в пользу мерчанта и впоследствии перечисляет их на соответствующий расчетный счет.

Прием платежей с помощью банковских карт и мобильной коммерции может проводиться в тестовом режиме. Другие способы будут доступны только в боевом режиме.

Через платежную страницу

Инициализация платежа

Инициализация платежа

Запрос

curl --location --request POST 'https://api.paybox.money/init_payment.php' \
--form 'pg_order_id=23' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_amount=25' \
--form 'pg_description=test' \
--form 'pg_salt=molbulak' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'init_payment.php;25;test;{{paybox_merchant_id}};23;molbulak;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>4567788</pg_payment_id>
    <pg_redirect_url>https://api.paybox.money/pay.html?customer=498333170d6a895148c57c53ffb18287</pg_redirect_url>
    <pg_redirect_url_type>need data</pg_redirect_url_type>
    <pg_salt>bdwLavL9lg6It91b</pg_salt>
    <pg_sig>709633e91387c56ac6fb7cb33d1e07d8</pg_sig>
</response>

Генерация подписи

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = $requestForSignature = [
    'pg_order_id' => '23',
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_amount' => '25',
    'pg_description' => 'test',
    'pg_salt' => 'molbulak',
    'pg_currency' => 'KZT',
    'pg_check_url' => 'http://site.kz/check',
    'pg_result_url' => 'http://site.kz/result',
    'pg_request_method' => 'POST',
    'pg_success_url' => 'http://site.kz/success',
    'pg_failure_url' => 'http://site.kz/failure',
    'pg_success_url_method' => 'GET',
    'pg_failure_url_method' => 'GET',
    'pg_state_url' => 'http://site.kz/state',
    'pg_state_url_method' => 'GET',
    'pg_site_url' => 'http://site.kz/return',
    'pg_payment_system' => 'EPAYWEBKZT',
    'pg_lifetime' => '86400',
    'pg_user_phone' => '77777777777',
    'pg_user_contact_email' => 'mail@customer.kz',
    'pg_user_ip' => '127.0.0.1',
    'pg_postpone_payment' => '0',
    'pg_language' => 'ru',
    'pg_testing_mode' => '1',
    'pg_user_id' => '1',
    'pg_recurring_start' => '1',
    'pg_recurring_lifetime' => '156',
    'pg_receipt_positions' => [
        [
            'count' => '1',
            'name' => 'название товара',
            'tax_type' => '3',
            'price' => '900',
        ]
    ],
    'pg_user_id' => '1',
    'pg_param1' => 'дополнительные данные',
    'pg_param2' => 'дополнительные данные',
    'pg_param3' => 'дополнительные данные',
];

/**
 * Функция превращает многомерный массив в плоский
 */
function makeFlatParamsArray($arrParams, $parent_name = '')
{
    $arrFlatParams = [];
    $i = 0;
    foreach ($arrParams as $key => $val) {
        $i++;
        /**
         * Имя делаем вида tag001subtag001
         * Чтобы можно было потом нормально отсортировать и вложенные узлы не запутались при сортировке
         */
        $name = $parent_name . $key . sprintf('%03d', $i);
        if (is_array($val)) {
            $arrFlatParams = array_merge($arrFlatParams, makeFlatParamsArray($val, $name));
            continue;
        }
        $arrFlatParams += array($name => (string)$val);
    }

    return $arrFlatParams;
}

// Превращаем объект запроса в плоский массив
$requestForSignature = makeFlatParamsArray($requestForSignature);

// Генерация подписи
ksort($requestForSignature); // Сортировка по ключю
array_unshift($requestForSignature, 'init_payment.php'); // Добавление в начало имени скрипта
array_push($requestForSignature, $secret_key); // Добавление в конец секретного ключа

$request['pg_sig'] = md5(implode(';', $requestForSignature)); // Полученная подпись

При прямой передаче данных от мерчанта в PayBox.money, мерчант должен посылать данные на init_payment.php.

Можно передавать произвольные дополнительные параметры, имена которых не начинаются на pg_. Все эти параметры будут переданы на pg_check_url и pg_result_url.

Имена дополнительных параметров мерчанта должны быть уникальны.

После получение параметра pg_redirect_url пользователя перенаправляют на платежную страницу, где плательщик завершает платеж.

В случае успеха пользователь будет перенаправлен на страницу оплаты.

В случае если мерчантом переданы не все параметры, необходимые для создания платежной транзакции (платежная система, телефон пользователя и параметры, необходимые для выбранной платежной системы), они запрашиваются у пользователя на сайте paybox.money.

URL запроса

POST https://api.paybox.money/init_payment.php

Поля запроса
Название Описание Тип
pg_order_id
required
Идентификатор платежа в системе мерчанта. Рекомендуется поддерживать уникальность этого поля.
Пример: 00102
string
pg_merchant_id
required
Идентификатор мерчанта в PayBox.money Выдается при подключении. integer
pg_amount
required
Сумма платежа в валюте pg_currency.
Пример: 10
number
pg_description
required
Описание товара или услуги. Отображается покупателю в процессе платежа.
Пример: Ticket
string
pg_salt
required
Случайная строка
Пример: some random string
string
pg_sig
required
Подпись запроса string
pg_currency Валюта, в которой указана сумма. KZT, USD, EUR. В случае выбора покупателем способа платежа в другой валюте, производится пересчет по курсу ЦБ на день платежа. См. в разделе Справочник валют
Пример: KZT
string
pg_check_url URL для проверки возможности платежа. Вызывается перед платежом, если платежная система предоставляет такую возможность. Если параметр не указан, то берется из настроек магазина. Если параметр установлен равным пустой строке, то проверка возможности платежа не производится. string
pg_result_url URL для сообщения о результате платежа. Вызывается после платежа в случае успеха или неудачи. Если параметр не указан, то берется из настроек магазина. Если параметр установлен равным пустой строке, то PayBox.money не сообщает магазину о результате платежа. string
pg_request_method GET, POST или XML – метод вызова скриптов магазина Check URL, Result URL, для передачи информации от платежного гейта.
Пример: POST
string
pg_success_url url, на который отправляется пользователь в случае успешного платежа (только для online систем) string
pg_failure_url url, на который отправляется пользователь в случае неуспешного платежа (только для online систем) string
pg_success_url_method GET – кнопка, которая сабмитится методом GET. POST – кнопка, которая сабмитится методом POST. Если выбран метод GET или POST, то страница с подтверждением оплаты показывается пользователю на сайте paybox.money, и предлагается нажать кнопку, чтобы вернуться на сайт магазина.
Пример: GET
string
pg_failure_url_method GET – кнопка, которая сабмитится методом GET. POST – кнопка, которая сабмитится методом POST. Если выбран метод GET или POST, то страница с сообщением о неудавшейся оплате показывается пользователю на сайте paybox.money, и предлагается нажать кнопку, чтобы вернуться на сайт магазина.
Пример: GET
string
pg_state_url URL скрипта на сайте магазина, куда перенаправляется покупатель для ожидания ответа от платежной системы.
Пример: http://site.kz/state
string
pg_state_url_method GET – кнопка, которая сабмитится методом GET.
POST – кнопка, которая сабмитится методом POST.
AUTOGET – 302 редирект. См. Автоматическая передача информации, п.1.
AUTOPOST – форма, которая автоматически сабмитится. См. Автоматическая передача информации, п.2.
Если выбран метод GET или POST, то страница с сообщением о неудавшейся оплате показывается пользователю на сайте paybox.money, и предлагается нажать кнопку, чтобы вернуться на сайт магазина.
Если выбран метод AUTOGET или AUTOPOST, то страница с сообщением о неудавшейся оплате не показывается пользователю, и пользователь сразу передается магазину.
Пример: GET
string
pg_site_url URL сайта магазина для показа покупателю ссылки, по которой он может вернуться на сайт магазина после создания счета. Применяется для offline ПС (наличные).
Пример: http://site.kz/return
string
pg_payment_system Идентификатор платежной системы. Этот параметр передается только если выбор платежной системы совершается на сайте мерчанта. Если параметр не указан, то выбор ПС совершается на сайте paybox.money
Пример: EPAYWEBKZT
string
pg_lifetime Default: "86400"
Время (в секундах) в течение которого платеж должен быть завершен, в противном случае заказ при проведении платежа PayBox.money откажет платежной системе в проведении. Этот параметр контролируется PayBox.money, а также, если платежная система поддерживает такую возможность, и платежной системой. Минимально допустимое значение: 300 секунд (5 минут). Максимально допустимое значение: 604800 секунд (7 суток). В случае выхода за пограничные значения будет присвоено минимальное или максимальное значение, соответственно.
Пример: 86400
integer
pg_user_phone Телефон пользователя (начиная с кода страны), необходим для идентификации покупателя. Если не указан, выбор будет предложен пользователю на сайте платежного гейта.
Пример: 77777777777
string
pg_user_contact_email Контактный адрес электронной почты пользователя. Если указан, на этот адрес будут высылаться уведомления об изменении статуса транзакции.
Пример: mail@customer.kz
string
pg_user_ip IP-адрес клиента. Необходим для разбора спорных ситуаций в случае подозрения на мошенничество. Параметр можно не передавать при передаче информации через браузер пользователя, в этом случае будет записан тот IP, с которого пользователь перешёл на страницу инициализации платежа.
Пример: 127.0.0.1
string
pg_postpone_payment Создание платежа с отложенной оплатой если в этом параметре передано «1». В таком случае покупатель будет перенаправлен на страницу с информацией о том, что ему было выслано письмо со ссылкой на страницу для продолжения проведения платежа. Если этот параметр присутствует в запросе, то должен быть указан также pg_user_contact_email, иначе пользователь будет перенаправлен на уточнение платежных параметров, где он сможет, указать email и попробовать отложить платеж ещё раз.
Пример: 0
integer
pg_language Язык платежных страниц на сайте PayBox.money и (если возможно) платежных систем. "en", "ru"
Пример: ru
string
pg_testing_mode Создание платежа в тестовом режиме.
Пример: 1
integer
pg_user_id ID пользователя в системе мерчанта.
Пример: 123
integer
pg_recurring_start Флаг, принимает значение 0 или 1. Подробное описание см. в разделе Рекуррентные платежи. Для использования данного параметра Вам следует обратиться к своему менеджеру.
Пример: 1
integer
pg_recurring_lifetime Время на продолжении которого мерчант рассчитывает использовать профиль рекуррентных платежей. Минимально допустимое значение 1 (1 месяц). Максимально допустимое значение: 156 (13 лет). В случае выхода за пограничные значения будет присвоено минимальное или максимальное значение, соответственно. Подробное описание см. в разделе Рекуррентные платежи. Для использования данного параметра Вам следует обратиться к своему менеджеру.
Пример: 156
integer
pg_receipt_positions[0][count] Количество товара.
Пример: 2
integer
pg_receipt_positions[0][name] Наименование товара
Пример: Коврик для мыши
string
pg_receipt_positions[0][tax_type] Тип налога.
Пример: 3
integer
pg_receipt_positions[0][price] Цена за 1 ед. товара.
Пример: 1000
number
pg_param1 Дополнительный параметр 1
Пример: Дополнительная информация
string
pg_param2 Дополнительный параметр 2
Пример: Дополнительная информация
string
pg_param3 Дополнительный параметр 3
Пример: Дополнительная информация
string
pg_auto_clearing Если 1 клиринг будет происходить сразу, в случае 0 необходимо сделать ручной клиринг. Подробное описание см. в разделе Запрос на клиринг транзакций по банковским картам. Для использования данного параметра Вам следует обратиться к своему менеджеру.
Пример: 1
integer
Параметры ответа
Название Описание Тип
pg_status Показывает результат выполнения запроса string
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money cлужит ключом для всей дальнейшей работы с транзакцией integer
pg_redirect_url URL для перенаправления пользователя. Может быть как на сайте paybox.money, так и на сайте платежной системы string
pg_redirect_url_type Тип страницы, на которую происходит перенаправление. Возможные значения:
need data – диалог с покупателем с целью уточнения параметров: платежной системы, номера телефона, обязательных для данной платежной системы параметров;
payment system – страница сайта платежной системы либо страница с инструкциями оплаты через данную платежную систему. Страница с инструкциями может располагаться как на сайте paybox.money, так и на сайте мерчанта.

В случае получения мерчантом ответа с pg_redirect_url_type=”need data”, мерчант может не перенаправлять покупателя по полученному URL, а уточнить недостающие параметры у себя на сайте. В этом случае после уточнения параметров и повторного запроса на создание платежной транзакции будет создана новая транзакция
string
pg_salt Случайная строка string
pg_sig Подпись запроса string


Запрос на check_url магазина. Проверка возможности совершить платеж.

Пример положительного ответа магазина

Запрос

curl --location --request POST '{{check_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=10' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_ps_amount=5' \
--form 'pg_ps_full_amount=5' \
--form 'pg_payment_system=EPAYWEBKZT' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <status>ok</status>
    <pg_description>Платеж разрешен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>

Пример отрицательного ответа магазина

Запрос

curl --location --request POST '{{check_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=10' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_ps_amount=5' \
--form 'pg_ps_full_amount=5' \
--form 'pg_payment_system=EPAYWEBKZT' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <status>rejected</status>
    <pg_description>Платеж не разрешен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>

Перед тем как принять деньги от покупателя по счету, платежный гейт может вызвать скрипт мерчанта Check URL с помощью метода Request Method.

PayBox.money передает информацию о номере, свойствах заказа и ожидает ответа. Отсутствие ответа за указанное время воспринимается как отказ от платежа.

Вызов скрипта Check URL происходит только в случае, если такая опция была включена в настройках мерчанта.

Ответ на check_url от мерчанта

Если Check URL определен пустым в момент инициализации платежа или не указан в момент инициализации платежа, а в настройках мерчанта установлен пустым, то шаг проверки возможности платежа пропускается и считается, что магазин согласен принять платеж.

Название Описание Тип
pg_order_id Идентификатор заказа в системе мерчанта
Пример: 123456789
string
pg_payment_id Внутренний идентификатор платежа в системе PayBox.money
Пример: 12345
integer
pg_amount Сумма выставленного счета (в валюте pg_currency), совпадает с pg_amount в момент инициализации платежа.
Пример: 10
number
pg_currency Валюта выставленного счета, совпадает с pg_currency в момент инициализации платежа.
Пример: KZT
string
pg_ps_currency Валюта, в которой был произведен платеж в платежной системе. Поле может отсутствовать в случае неудачного платежа
Пример: KZT
string
pg_ps_amount Сумма счета (в валюте pg_ps_currency), выставленного в платежной системе.
Пример: 5
number
pg_ps_full_amount Полная сумма (в валюте pg_ps_currency), которую заплатит покупатель с учетом всех комиссий.
Пример: 5
number
pg_payment_system Идентификатор платежной системы
Пример: EPAYWEBKZT
string
Параметры мерчанта Все поля, переданные с веб-сайта мерчанта, не имеющие префикса pg_ string
pg_salt Случайная строка
Пример: some random string
string
pg_sig Подпись запроса string


Запрос на result_url магазина. Результат платежа

Пример отрицательного ответа магазина

Запрос

curl --location --request POST '{{result_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_payment_system=EPAYWEBKZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=1' \
--form 'pg_payment_date=2019-01-01 12:00:00' \
--form 'pg_can_reject=1' \
--form 'pg_user_phone=7077777777777' \
--form 'pg_user_contact_email=mail@customer.kz' \
--form 'pg_testing_mode=1' \
--form 'pg_captured=0' \
--form 'pg_card_pan=5483-18XX-XXXX-0293' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <status>rejected</status>
    <pg_description>Платеж отменен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>

Пример положительного ответа магазина

Запрос

curl --location --request POST '{{result_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_payment_system=EPAYWEBKZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=1' \
--form 'pg_payment_date=2019-01-01 12:00:00' \
--form 'pg_can_reject=1' \
--form 'pg_user_phone=7077777777777' \
--form 'pg_user_contact_email=mail@customer.kz' \
--form 'pg_testing_mode=1' \
--form 'pg_captured=0' \
--form 'pg_card_pan=5483-18XX-XXXX-0293' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <status>ok</status>
    <pg_description>Заказ оплачен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>

После приема оплаты от клиента или при невозможности совершить платеж PayBox.money вызывает Result URL магазина и передает на него методом Request Method информацию о результате платежа.

При получении данного запроса мерчант должен произвести необходимые действия для передачи товара или услуги покупателю, в случае если платеж был успешным. Если pg_can_reject равно 1 и мерчант не может принять платеж (например, бронь на билеты истекла), он обязан ответить со статусом rejected, и PayBox.money отзовет платеж. В этом случае поле pg_description из ответа мерчанта показывается пользователю как причина отказа.

Если сервер мерчанта недоступен в момент вызова Result URL или ответ от сервера был со статусом 500, PayBox.money будет предпринимать повторные попытки его вызвать каждые полчаса в течение 2 часов, даже если время жизни счета pg_lifetime истечет.

Если первая попытка вызова Result URL оказалась неуспешной, то платеж не отменяется, и в последующих вызовах Result URL не позволяет магазину отказаться от платежа.

Магазин должен быть готов к тому, что Result URL будет вызван повторно для одного и того же платежа. Ответы на повторные вызовы должны совпадать с первоначальным ответом, даже если время жизни транзакции pg_lifetime истекло.

Ответ на result_url от мерчанта

Статус rejected может быть возвращен мерчантом только в случае, когда во входящем запросе от гейта был указан параметр pg_can_reject равный 1, в противном случае, вне зависимости от ответа мерчанта, платеж будет считаться совершенным. Если мерчант отказался от платежа (ответил rejected), покупатель перенаправляется на Failure URL, иначе – на Success URL.

Название Описание Тип
pg_order_id Идентификатор заказа в системе мерчанта
Пример: 123456789
string
pg_payment_id Внутренний идентификатор платежа в системе PayBox.money
Пример: 12345
integer
pg_currency Валюта выставленного счета, совпадает с pg_currency в момент инициализации платежа.
Пример: KZT
string
pg_ps_currency Валюта, в которой был произведен платеж в платежной системе. Поле может отсутствовать в случае неудачного платежа
Пример: KZT
string
pg_payment_system Идентификатор платежной системы
Пример: EPAYWEBKZT
string
pg_description Описание платежа
Пример: Покупка в интернет магазине Site.kz
string
pg_result Результат платежа. 1 – успех, 0 – неудача.
Пример: 1
integer
pg_payment_date Дата и время совершения платежа в формате YYYY-MM-DD HH:MM:SS.
Пример: 2019-01-01 12:00:00
datetime
pg_can_reject 1 – платеж можно откатить назад (например, Банковские карты), 0 – платеж безотзывный.
Пример: 1
integer
pg_user_phone Телефон покупателя (указанный при инициализации платежа)
Пример: 7077777777777
string
pg_user_contact_email Email покупателя (указанный при инициализации платежа)
Пример: mail@customer.kz
string
pg_testing_mode Тестовый режим. 1 - тестовый, 0 - боевой.
Пример: 1
integer
pg_captured Передается только в случае успешной оплаты банковской картой и показывает, был ли произведен клиринг в момент авторизации (что зависит только от настроек мерчанта). Если значение этого поля равно 0, мерчант должен в последующем дать команду на клиринг (см. раздел Запрос на клиринг транзакций по банковским картам) или дождаться когда PayBox.money сделает это сам.
Пример: 0
integer
pg_card_pan Маскированный номер карты (часть цифр номера карты скрыты). Этот параметр передается только в случае успешной оплаты банковской картой
Пример: 5483-18XX-XXXX-0293
string
Параметры мерчанта Все поля, переданные с веб-сайта мерчанта, не имеющие префикса pg_ string
pg_salt Случайная строка
Пример: some random string
string
pg_sig Подпись запроса string


Запрос на success_url магазина. Возврат покупателя на сайт мерчанта

После завершения платежа в online платежной системе, покупатель перенаправляется на страницу мерчанта Success URL или Failure URL, в зависимости от результата платежа. Перенаправление происходит методом Success URL Method или Failure URL Method, указанным при инициализации платежа.

Если при GET запросе Success URL или Failure URL уже содержат параметры в query string, то дополнительные параметры pg_order_id, pg_payment_id и пользовательские переменные мерчанта дописываются в конец query string. мерчанта должен следить за тем, чтобы имена дополнительных параметров не совпадали с именами уже имеющимися параметров.

Необходимо четко понимать разницу между Result URL и Success URL.

Result URL вызывается напрямую с сервера PayBox.money, в то время как Success URL вызывается браузером пользователя, когда PayBox.money перенаправляет пользователя обратно на сайт магазина. Неправильно использовать Success URL как единственный способ узнать о завершении оплаты, потому что пользователь может по разным причинам (например, при разрыве связи) не дойти до Success URL после оплаты. Самый надежный способ узнать о завершении платежа – это реализовать Result URL, который PayBox.money обязуется вызывать повторно каждые полчаса в течение 2 часов после оплаты, если первая попытка по любым причинам не удалась.

URL запроса

POST {{success_url}}

Поля запроса
Название Описание Тип
pg_order_id Идентификатор заказа в системе мерчанта
Пример: 123456789
string
pg_payment_id Внутренний идентификатор платежа в системе PayBox.money
Пример: 12345
integer
Параметры мерчанта Все поля, переданные с веб-сайта мерчанта, не имеющие префикса pg_ string
pg_salt Случайная строка
Пример: some random string
string
pg_sig Подпись запроса string


Получение статуса платежа

Ok - Получение статуса платежа

Запрос

curl --location --request POST 'https://api.paybox.money/get_status.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_payment_id=4567775' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status.php;{{paybox_merchant_id}};4567775;00102;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>4567775</pg_payment_id>
    <pg_transaction_status>ok</pg_transaction_status>
    <pg_can_reject>1</pg_can_reject>
    <pg_testing_mode>1</pg_testing_mode>
    <pg_captured>0</pg_captured>
    <pg_card_pan>5483-18XX-XXXX-0293</pg_card_pan>
    <pg_card_id>205</pg_card_id>
    <pg_card_hash>e5b78033320bb1de831439cbc9ec543a</pg_card_hash>
    <pg_create_date>2020-06-01 16:58:40</pg_create_date>
    <pg_salt>OX1MwChiToQFR1Fy</pg_salt>
    <pg_sig>8fec63c0e02d3d8f98d9eff2d4f6c226</pg_sig>
</response>

Partial - Получение статуса платежа

Запрос

curl --location --request POST 'https://api.paybox.money/get_status.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_payment_id=4567617' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status.php;{{paybox_merchant_id}};4567617;00102;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>4567617</pg_payment_id>
    <pg_transaction_status>partial</pg_transaction_status>
    <pg_can_reject>0</pg_can_reject>
    <pg_testing_mode>1</pg_testing_mode>
    <pg_captured>0</pg_captured>
    <pg_create_date>2020-05-21 18:44:21</pg_create_date>
    <pg_salt>u1aHmP4QyTxUqzXz</pg_salt>
    <pg_sig>574a9d2e4783cb3d5ea443e1cc4f9434</pg_sig>
</response>

Мерчант может запрашивать PayBox.money статус любого платежа, инициированного магазином. Это может быть полезно, например, в случае если вызов Result URL не был получен мерчантом из-за временного сбоя связи, а покупатель уже был передан на Success URL, однако статус транзакции мерчанту еще не известен.

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_payment_id' => 12345,
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'get_status.php');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/get_status.php

Поля запроса
Название Описание Тип
pg_merchant_id
required
Идентификатор мерчанта в PayBox.money. Выдается при подключении. string
pg_payment_id
required
Внутренний идентификатор платежа в системе PayBox.money
если отправлена вместе с полем pg_order_id, то поле pg_order_id будет проигнорировано.
Пример: 12345
integer
pg_order_id Идентификатор платежа в системе мерчанта. Будьте внимательны, при запросе по order_id магазин должен самостоятельно следить за уникальностью данного параметра иначе будет выдана информация для последнего платежа с данным order_id для данного магазина
Пример: 00102
string
pg_salt
required
Случайная строка
Пример: some random string
string
pg_sig
required
Подпись запроса string
Параметры ответа
Название Описание Тип
pg_status Показывает результат выполнения запроса string
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money Служит ключом для всей дальнейшей работы с транзакцией integer
pg_transaction_status Статус платежа string
pg_can_reject 0 или 1 – может ли платеж быть отменен. Значение 1 возможно только если статус платежа равен ok и платежная система предоставляет возможность отзыва платежа. В этом случае мерчант может вызвать revoke.php. integer
pg_testing_mode Enum:0 1
0 - платеж в боевом режиме 1 - платеж в тестовом режиме
integer
pg_captured Enum:0 1
Передается только в случае успешной оплаты банковской картой и показывает, был ли произведен клиринг в момент авторизации (что зависит только от настроек мерчанта). Если значение этого поля равно 0, мерчант должен в последующем дать команду на клиринг или дождаться когда PayBox.money сделает это сам.
integer
pg_card_pan Маскированный номер карты (часть цифр номера карты скрыты). Этот параметр передается только в случае успешной оплаты банковской картой. string
pg_card_id ID карты integer
pg_card_hash Хеш маскированной PAN карты string
pg_create_date Дата и время создания платежной транзакции datetime
pg_salt Случайная строка string
pg_sig Подпись запроса string


Через платежный фрейм

Инициализация платежа

Инициализация платежа

Запрос

curl --location --request POST 'https://api.paybox.money/init_payment.php' \
--form 'pg_order_id=23' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_amount=25' \
--form 'pg_description=test' \
--form 'pg_salt=molbulak' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'init_payment.php;25;test;{{paybox_merchant_id}};23;molbulak;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>4567788</pg_payment_id>
    <pg_redirect_url>https://api.paybox.money/pay.html?customer=498333170d6a895148c57c53ffb18287</pg_redirect_url>
    <pg_redirect_url_type>need data</pg_redirect_url_type>
    <pg_salt>bdwLavL9lg6It91b</pg_salt>
    <pg_sig>709633e91387c56ac6fb7cb33d1e07d8</pg_sig>
</response>

При прямой передаче данных от мерчанта в PayBox.money магазин должен посылать данные на init_payment.php.

Можно передавать произвольные дополнительные параметры, имена которых не начинаются на pg_. Все эти параметры будут переданы на pg_check_url и pg_result_url.

Имена дополнительных параметров мерчанта должны быть уникальны.

После получение параметра pg_redirect_url пользователя перенаправляют на платежную страницу где плательщик завершает платеж.

В случае успеха пользователь будет перенаправлен на страницу оплаты.

В случае если мерчантом переданы не все параметры, необходимые для создания платежной транзакции (платежная система, телефон пользователя и параметры, необходимые для выбранной платежной системы), они запрашиваются у пользователя на сайте PayBox.money.

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = $requestForSignature = [
    'pg_order_id' => '23',
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_amount' => '25',
    'pg_description' => 'test',
    'pg_salt' => 'molbulak',
    'pg_payment_route' => 'frame',
    'pg_currency' => 'KZT',
    'pg_check_url' => 'http://site.kz/check',
    'pg_result_url' => 'http://site.kz/result',
    'pg_request_method' => 'POST',
    'pg_success_url' => 'http://site.kz/success',
    'pg_failure_url' => 'http://site.kz/failure',
    'pg_success_url_method' => 'GET',
    'pg_failure_url_method' => 'GET',
    'pg_state_url' => 'http://site.kz/state',
    'pg_state_url_method' => 'GET',
    'pg_site_url' => 'http://site.kz/return',
    'pg_payment_system' => 'EPAYWEBKZT',
    'pg_lifetime' => '86400',
    'pg_user_phone' => '77777777777',
    'pg_user_contact_email' => 'mail@customer.kz',
    'pg_user_ip' => '127.0.0.1',
    'pg_postpone_payment' => '0',
    'pg_language' => 'ru',
    'pg_testing_mode' => '1',
    'pg_user_id' => '1',
    'pg_recurring_start' => '1',
    'pg_recurring_lifetime' => '156',
    'pg_receipt_positions' => [
        [
            'count' => '1',
            'name' => 'название товара',
            'tax_type' => '3',
            'price' => '900',
        ]
    ],
    'pg_user_id' => '1',
    'pg_param1' => 'дополнительные данные',
    'pg_param2' => 'дополнительные данные',
    'pg_param3' => 'дополнительные данные',
];

/**
 * Функция превращает многомерный массив в плоский
 */
function makeFlatParamsArray($arrParams, $parent_name = '')
{
    $arrFlatParams = [];
    $i = 0;
    foreach ($arrParams as $key => $val) {
        $i++;
        /**
         * Имя делаем вида tag001subtag001
         * Чтобы можно было потом нормально отсортировать и вложенные узлы не запутались при сортировке
         */
        $name = $parent_name . $key . sprintf('%03d', $i);
        if (is_array($val)) {
            $arrFlatParams = array_merge($arrFlatParams, makeFlatParamsArray($val, $name));
            continue;
        }
        $arrFlatParams += array($name => (string)$val);
    }

    return $arrFlatParams;
}

// Превращаем объект запроса в плоский массив
$requestForSignature = makeFlatParamsArray($requestForSignature);

// Генерация подписи
ksort($requestForSignature); // Сортировка по ключю
array_unshift($requestForSignature, 'init_payment.php'); // Добавление в начало имени скрипта
array_push($requestForSignature, $secret_key); // Добавление в конец секретного ключа

$request['pg_sig'] = md5(implode(';', $requestForSignature)); // Полученная подпись
URL запроса

POST https://api.paybox.money/init_payment.php

Поля запроса
Название Описание Тип
pg_order_id
required
Идентификатор платежа в системе мерчанта. Рекомендуется поддерживать уникальность этого поля.
Пример: 00102
string
pg_merchant_id
required
Идентификатор мерчанта в PayBox.money. Выдается при подключении. integer
pg_amount
required
Сумма платежа в валюте pg_currency.
Пример: 10
number
pg_description
required
Описание товара или услуги. Отображается покупателю в процессе платежа.
Пример: Ticket
string
pg_salt
required
Случайная строка
Пример: some random string
string
pg_sig
required
Подпись запроса string
pg_payment_route
required
Для инициализации frame
Пример: frame
string
pg_currency Валюта, в которой указана сумма. KZT, USD, EUR. В случае выбора покупателем способа платежа в другой валюте, производится пересчет по курсу ЦБ на день платежа. См. в разделе Справочник валют
Пример: KZT
string
pg_check_url URL для проверки возможности платежа. Вызывается перед платежом, если платежная система предоставляет такую возможность. Если параметр не указан, то берется из настроек мерчанта. Если параметр установлен равным пустой строке, то проверка возможности платежа не производится. string
pg_result_url URL для сообщения о результате платежа. Вызывается после платежа в случае успеха или неудачи. Если параметр не указан, то берется из настроек магазина. Если параметр установлен равным пустой строке, то PayBox не сообщает магазину о результате платежа. string
pg_request_method GET, POST или XML – метод вызова скриптов мерчанта Check URL, Result URL, для передачи информации от платежного гейта.
Пример: POST
string
pg_failure_url url, на который отправляется пользователь в случае неуспешного платежа (только для online систем) string
pg_failure_url_method GET – кнопка, которая сабмитится методом GET. POST – кнопка, которая сабмитится методом POST. Если выбран метод GET или POST, то страница с сообщением о неудавшейся оплате показывается пользователю на сайте paybox.money.
Пример: GET
string
pg_state_url URL скрипта на сайте мерчанта, куда перенаправляется покупатель для ожидания ответа от платежной системы.
Пример: http://site.kz/state
string
pg_state_url_method GET – кнопка, которая сабмитится методом GET.
POST – кнопка, которая сабмитится методом POST.
AUTOGET – 302 редирект. См. Автоматическая передача информации, п.1.
AUTOPOST – форма, которая автоматически сабмитится. См. Автоматическая передача информации, п.2.
Если выбран метод GET или POST, то страница с сообщением о неудавшейся оплате показывается пользователю на сайте paybox.money, и предлагается нажать кнопку, чтобы вернуться на сайт мерчанта.
Если выбран метод AUTOGET или AUTOPOST, то страница с сообщением о неудавшейся оплате не показывается пользователю, и пользователь сразу передается мерчанту.
Пример: GET
string
pg_site_url URL сайта магазина для показа покупателю ссылки, по которой он может вернуться на сайт магазина после создания счета. Применяется для offline ПС (наличные).
Пример: http://site.kz/return
string
pg_lifetime Default: "86400"
Время (в секундах) в течение которого платеж должен быть завершен, в противном случае заказ при проведении платежа PayBox откажет платежной системе в проведении. Этот параметр контролируется PayBox’ом, а также, если платежная система поддерживает такую возможность, и платежной системой. Минимально допустимое значение: 300 секунд (5 минут). Максимально допустимое значение: 604800 секунд (7 суток). В случае выхода за пограничные значения будет присвоено минимальное или максимальное значение, соответственно.
Пример: 86400
integer
pg_user_phone Телефон пользователя (начиная с кода страны), необходим для идентификации покупателя. Если не указан, выбор будет предложен пользователю на сайте платежного гейта.
Пример: 77777777777
string
pg_user_contact_email Контактный адрес электронной почты пользователя. Если указан, на этот адрес будут высылаться уведомления об изменении статуса транзакции.
Пример: mail@customer.kz
string
pg_user_ip IP-адрес клиента. Необходим для разбора спорных ситуаций в случае подозрения на мошенничество. Параметр можно не передавать при передаче информации через браузер пользователя, в этом случае будет записан тот IP, с которого пользователь перешёл на страницу инициализации платежа.
Пример: 127.0.0.1
string
pg_postpone_payment Создание платежа с отложенной оплатой если в этом параметре передано «1». В таком случае покупатель будет перенаправлен на страницу с информацией о том, что ему было выслано письмо со ссылкой на страницу для продолжения проведения платежа. Если этот параметр присутствует в запросе, то должен быть указан также pg_user_contact_email, иначе пользователь будет перенаправлен на уточнение платежных параметров, где он сможет, указать email и попробовать отложить платеж ещё раз.
Пример: 0
integer
pg_language Язык платежных страниц на сайте PayBoxа и (если возможно) платежных систем. "en", "ru"
Пример: ru
string
pg_testing_mode Создание платежа в тестовом режиме.
Пример: 1
integer
pg_user_id
required
ID пользователя в системе мерчанта.
Пример: 123
integer
pg_recurring_start Флаг, принимает значение 0 или 1. Подробное описание см. в разделе Рекурентные платежи. Для использования данного параметра Вам следует обратиться к своему менеджеру.
Пример: 1
integer
pg_recurring_lifetime Время на продолжении которого магазин рассчитывает использовать профиль рекуррентных платежей. Минимально допустимое значение 1 (1 месяц). Максимально допустимое значение: 156 (13 лет). В случае выхода за пограничные значения будет присвоено минимальное или максимальное значение, соответственно. Подробное описание см. в разделе Рекуррентные платежи. Для использования данного параметра Вам следует обратиться к своему менеджеру.
Пример: 156
integer
pg_param1 Дополнительный параметр 1
Пример: Дополнительная информация
string
pg_param2 Дополнительный параметр 2
Пример: Дополнительная информация
string
pg_param3 Дополнительный параметр 3
Пример: Дополнительная информация
string
pg_auto_clearing Если 1 клиринг будет происходить сразу, в случае 0 необходимо сделать ручной клиринг. Подробное описание см. в разделе Запрос на клиринг транзакций по банковским картам. Для использования данного параметра Вам следует обратиться к своему менеджеру.
Пример: 1
integer
Параметры ответа
Название Описание Тип
pg_status Показывает результат выполнения запроса string
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money. Служит ключом для всей дальнейшей работы с транзакцией integer
pg_redirect_url URL для перенаправления пользователя. Может быть как на сайте paybox.money, так и на сайте платежной системы string
pg_redirect_url_type Тип страницы, на которую происходит перенаправление. Возможные значения:
need data – диалог с покупателем с целью уточнения параметров: платежной системы, номера телефона, обязательных для данной платежной системы параметров;
payment system – страница сайта платежной системы либо страница с инструкциями оплаты через данную платежную систему. Страница с инструкциями может располагаться как на сайте paybox.money, так и на сайте мерчанта.

В случае получения мерчантом ответа с pg_redirect_url_type=”need data”, мерчант может не перенаправлять покупателя по полученному URL, а уточнить недостающие параметры у себя на сайте. В этом случае после уточнения параметров и повторного запроса на создание платежной транзакции будет создана новая транзакция
string
pg_salt Случайная строка string
pg_sig Подпись запроса string


Запрос на check_url магазина. Проверка возможности совершить платеж

Пример положительного ответа магазина

Запрос

curl --location --request POST '{{check_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=10' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_ps_amount=5' \
--form 'pg_ps_full_amount=5' \
--form 'pg_payment_system=EPAYWEBKZT' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <status>ok</status>
    <pg_description>Платеж разрешен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>

Пример отрицательного ответа магазина

Запрос

curl --location --request POST '{{check_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=10' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_ps_amount=5' \
--form 'pg_ps_full_amount=5' \
--form 'pg_payment_system=EPAYWEBKZT' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <status>rejected</status>
    <pg_description>Платеж не разрешен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>

Перед тем как принять деньги от покупателя по счету, платежный гейт может вызвать скрипт мерчанта Check URL с помощью метода Request Method.

PayBox.money передает информацию о номере и свойствах заказа и ожидает ответа. Отсутствие ответа за указанное время воспринимается как отказ от платежа.

Вызов скрипта Check URL происходит только в случае, если такая опция была включена в настройках мерчанта.

Ответ на check_url от мерчанта

Если Check URL определен пустым в момент инициализации платежа или не указан в момент инициализации платежа, а в настройках мерчанта установлен пустым, то шаг проверки возможности совершить платеж пропускается и считается, что мерчант согласен принять платеж.

Название Описание Тип
pg_order_id Идентификатор заказа в системе мерчанта
Пример: 123456789
string
pg_payment_id Внутренний идентификатор платежа в системе PayBox.money.
Пример: 12345
integer
pg_amount Сумма выставленного счета (в валюте pg_currency), совпадает с pg_amount в момент инициализации платежа.
Пример: 10
number
pg_currency Валюта выставленного счета, совпадает с pg_currency в момент инициализации платежа.
Пример: KZT
string
pg_ps_currency Валюта, в которой был произведен платеж в платежной системе. Поле может отсутствовать в случае неудачного платежа
Пример: KZT
string
pg_ps_amount Сумма счета (в валюте pg_ps_currency), выставленного в платежной системе.
Пример: 5
number
pg_ps_full_amount Полная сумма (в валюте pg_ps_currency), которую заплатит покупатель с учетом всех комиссий.
Пример: 5
number
pg_payment_system Идентификатор платежной системы
Пример: EPAYWEBKZT
string
Параметры мерчанта Все поля, переданные с веб-сайта мерчанта, не имеющие префикса pg_ string
pg_salt Случайная строка
Пример: some random string
string
pg_sig Подпись запроса string


Запрос на check_url магазина. Проверка возможности совершить платеж Copy

Пример отрицательного ответа магазина

Запрос

curl --location --request POST '{{check_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=10' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_ps_amount=5' \
--form 'pg_ps_full_amount=5' \
--form 'pg_payment_system=EPAYWEBKZT' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <status>rejected</status>
    <pg_description>Платеж не разрешен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>

Пример положительного ответа магазина

Запрос

curl --location --request POST '{{check_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=10' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_ps_amount=5' \
--form 'pg_ps_full_amount=5' \
--form 'pg_payment_system=EPAYWEBKZT' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <status>ok</status>
    <pg_description>Платеж разрешен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>

Перед тем как принять деньги от покупателя по счету, платежный гейт может вызвать скрипт мерчанта Check URL с помощью метода Request Method.

PayBox.money передает информацию о номере и свойствах заказа и ожидает ответа. Отсутствие ответа за указанное время воспринимается как отказ от платежа.

Вызов скрипта Check URL происходит только в случае, если такая опция была включена в настройках мерчанта.

Ответ на check_url от мерчанта

Если Check URL определен пустым в момент инициализации платежа или не указан в момент инициализации платежа, а в настройках мерчанта установлен пустым, то шаг проверки возможности совершить платеж пропускается и считается, что мерчант согласен принять платеж.

Название Описание Тип
pg_order_id Идентификатор заказа в системе мерчанта
Пример: 123456789
string
pg_payment_id Внутренний идентификатор платежа в системе PayBox.money.
Пример: 12345
integer
pg_amount Сумма выставленного счета (в валюте pg_currency), совпадает с pg_amount в момент инициализации платежа.
Пример: 10
number
pg_currency Валюта выставленного счета, совпадает с pg_currency в момент инициализации платежа.
Пример: KZT
string
pg_ps_currency Валюта, в которой был произведен платеж в платежной системе. Поле может отсутствовать в случае неудачного платежа
Пример: KZT
string
pg_ps_amount Сумма счета (в валюте pg_ps_currency), выставленного в платежной системе.
Пример: 5
number
pg_ps_full_amount Полная сумма (в валюте pg_ps_currency), которую заплатит покупатель с учетом всех комиссий.
Пример: 5
number
pg_payment_system Идентификатор платежной системы
Пример: EPAYWEBKZT
string
Параметры мерчанта Все поля, переданные с веб-сайта мерчанта, не имеющие префикса pg_ string
pg_salt Случайная строка
Пример: some random string
string
pg_sig Подпись запроса string


Запрос на result_url магазина. Результат платежа

Пример отрицательного ответа магазина

Запрос

curl --location --request POST '{{result_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_payment_system=EPAYWEBKZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=1' \
--form 'pg_payment_date=2019-01-01 12:00:00' \
--form 'pg_can_reject=1' \
--form 'pg_user_phone=7077777777777' \
--form 'pg_user_contact_email=mail@customer.kz' \
--form 'pg_testing_mode=1' \
--form 'pg_captured=0' \
--form 'pg_card_pan=5483-18XX-XXXX-0293' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <status>rejected</status>
    <pg_description>Платеж отменен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>

Пример положительного ответа магазина

Запрос

curl --location --request POST '{{result_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_payment_system=EPAYWEBKZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=1' \
--form 'pg_payment_date=2019-01-01 12:00:00' \
--form 'pg_can_reject=1' \
--form 'pg_user_phone=7077777777777' \
--form 'pg_user_contact_email=mail@customer.kz' \
--form 'pg_testing_mode=1' \
--form 'pg_captured=0' \
--form 'pg_card_pan=5483-18XX-XXXX-0293' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <status>ok</status>
    <pg_description>Заказ оплачен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>

После приема денег от клиента или при невозможности совершить платеж PayBox.money вызывает Result URL мерчанта и передает на него методом Request Method информацию о результате платежа.

При получении данного запроса мерчант должен произвести необходимые действия для передачи товара или услуги покупателю, в случае если платеж был успешным. Если pg_can_reject равно 1 и магазин не может принять платеж (например, бронь на билеты истекла), он обязан ответить со статусом rejected, и PayBox.money отзовет платеж. В этом случае поле pg_description из ответа мерчанта показывается пользователю как причина отказа.

Если сервер мерчанта недоступен в момент вызова Result URL или ответ от сервера был со статусом 500, PayBox.money будет предпринимать повторные попытки его вызвать каждые полчаса в течение 2 часов, даже если время жизни счета pg_lifetime истечет.

Если первая попытка вызова Result URL оказалась неуспешной, то платеж не отменяется, и в последующих вызовах Result URL не позволяет мерчанту отказаться от платежа.

Мерчант должен быть готов к тому, что Result URL будет вызван повторно для одного и того же платежа. Ответы на повторные вызовы должны совпадать с первоначальным ответом, даже если время жизни транзакции pg_lifetime истекло.

Ответ на result_url от мерчанта

Статус rejected может быть возвращен мерчантом только в случае, когда во входящем запросе от гейта был указан параметр pg_can_reject равный 1, в противном случае, вне зависимости от ответа мерчанта, платеж будет считаться совершенным. Если мерчант отказался от платежа (ответил rejected), покупатель перенаправляется на Failure URL, иначе – на Success URL.

Название Описание Тип
pg_order_id Идентификатор заказа в системе мерчанта
Пример: 123456789
string
pg_payment_id Внутренний идентификатор платежа в системе PayBox.money.
Пример: 12345
integer
pg_currency Валюта выставленного счета, совпадает с pg_currency в момент инициализации платежа.
Пример: KZT
string
pg_ps_currency Валюта, в которой был произведен платеж в платежной системе. Поле может отсутствовать в случае неудачного платежа
Пример: KZT
string
pg_payment_system Идентификатор платежной системы
Пример: EPAYWEBKZT
string
pg_description Описание платежа
Пример: Покупка в интернет магазине Site.kz
string
pg_result Результат платежа. 1 – успех, 0 – неудача.
Пример: 1
integer
pg_payment_date Дата и время совершения платежа в формате YYYY-MM-DD HH:MM:SS.
Пример: 2019-01-01 12:00:00
datetime
pg_can_reject 1 – платеж можно откатить назад (например, Банковские карты), 0 – платеж безотзывный.
Пример: 1
integer
pg_user_phone Телефон покупателя (указанный при инициализации платежа)
Пример: 7077777777777
string
pg_user_contact_email Email покупателя (указанный при инициализации платежа)
Пример: mail@customer.kz
string
pg_testing_mode Тестовый режим. 1 - тестовый, 0 - боевой.
Пример: 1
integer
pg_captured Передается только в случае успешной оплаты банковской картой и показывает, был ли произведен клиринг в момент авторизации (что зависит только от настроек мерчанта). Если значение этого поля равно 0, мерчант должен в последующем дать команду на клиринг (см. раздел Запрос на клиринг транзакций по банковским картам) или дождаться когда PayBox.money сделает это сам.
Пример: 0
integer
pg_card_pan Маскированный номер карты (часть цифр номера карты скрыты). Этот параметр передается только в случае успешной оплаты банковской картой
Пример: 5483-18XX-XXXX-0293
string
Параметры мерчанта Все поля, переданные с веб-сайта мерчанта, не имеющие префикса pg_ string
pg_salt Случайная строка
Пример: some random string
string
pg_sig Подпись запроса string


Запрос на success_url магазина. Возврат покупателя на сайт мерчанта

После завершения платежа в online платежной системе покупатель перенаправляется на страницу мерчанта Success URL или Failure URL, в зависимости от результата платежа. Перенаправление происходит методом Success URL Method или Failure URL Method, указанным при инициализации платежа.

Если при GET запросе Success URL или Failure URL уже содержат параметры в query string, то дополнительные параметры pg_order_id, pg_payment_id и пользовательские переменные мерчанта дописываются в конец query string. Мерчант должен следить за тем, чтобы имена дополнительных параметров не совпадали с именами уже имеющихся параметров.

Необходимо четко понимать разницу между Result URL и Success URL.

Result URL вызывается напрямую с сервера PayBox.money, в то время как Success URL вызывается браузером пользователя, когда PayBox.mone перенаправляет пользователя обратно на сайт магазина. Неправильно использовать Success URL как единственный способ узнать о завершении оплаты, потому что пользователь может по разным причинам (например, при разрыве связи) не дойти до Success URL после оплаты. Самый надежный способ узнать о завершении платежа – это реализовать Result URL, который PayBox.money обязуется вызывать повторно каждые полчаса в течение 2 часов после оплаты, если первая попытка по любым причинам не удалась.

URL запроса

POST {{success_url}}

Поля запроса
Название Описание Тип
pg_order_id Идентификатор заказа в системе мерчанта
Пример: 123456789
string
pg_payment_id Внутренний идентификатор платежа в системе PayBox.money.
Пример: 12345
integer
Параметры мерчанта Все поля, переданные с веб-сайта мерчанта, не имеющие префикса pg_ string
pg_salt Случайная строка
Пример: some random string
string
pg_sig Подпись запроса string


Получение статуса платежа

Partial - Получение статуса платежа

Запрос

curl --location --request POST 'https://api.paybox.money/get_status.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_payment_id=4567617' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status.php;{{paybox_merchant_id}};4567617;00102;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>4567617</pg_payment_id>
    <pg_transaction_status>partial</pg_transaction_status>
    <pg_can_reject>0</pg_can_reject>
    <pg_testing_mode>1</pg_testing_mode>
    <pg_captured>0</pg_captured>
    <pg_create_date>2020-05-21 18:44:21</pg_create_date>
    <pg_salt>u1aHmP4QyTxUqzXz</pg_salt>
    <pg_sig>574a9d2e4783cb3d5ea443e1cc4f9434</pg_sig>
</response>

Ok - Получение статуса платежа

Запрос

curl --location --request POST 'https://api.paybox.money/get_status.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_payment_id=4567775' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status.php;{{paybox_merchant_id}};4567775;00102;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>4567775</pg_payment_id>
    <pg_transaction_status>ok</pg_transaction_status>
    <pg_can_reject>1</pg_can_reject>
    <pg_testing_mode>1</pg_testing_mode>
    <pg_captured>0</pg_captured>
    <pg_card_pan>5483-18XX-XXXX-0293</pg_card_pan>
    <pg_card_id>205</pg_card_id>
    <pg_card_hash>e5b78033320bb1de831439cbc9ec543a</pg_card_hash>
    <pg_create_date>2020-06-01 16:58:40</pg_create_date>
    <pg_salt>OX1MwChiToQFR1Fy</pg_salt>
    <pg_sig>8fec63c0e02d3d8f98d9eff2d4f6c226</pg_sig>
</response>

Мерчант может запрашивать PayBox.money о статусе любого платежа, инициированного мерчантом. Это может быть полезно, например, в случае если вызов Result URL не был получен мерчантом из-за временного сбоя связи, а покупатель уже был передан на Success URL, однако статус транзакции мерчанту еще не известен.

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_payment_id' => 12345,
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'get_status.php');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/get_status.php

Поля запроса
Название Описание Тип
pg_merchant_id
required
Идентификатор мерчанта в PayBox.monry Выдается при подключении. string
pg_payment_id
required
Внутренний идентификатор платежа в системе PayBox.money
если отправлена вместе с полем pg_order_id, то поле pg_order_id будет проигнорировано.
Пример: 12345
integer
pg_order_id Идентификатор платежа в системе мерчанта. Будьте внимательны, при запросе по order_id мерчант должен самостоятельно следить за уникальностью данного параметра иначе будет выдана информация для последнего платежа с данным order_id для данного мерчанта
Пример: 00102
string
pg_salt
required
Случайная строка
Пример: some random string
string
pg_sig
required
Подпись запроса string
Параметры ответа
Название Описание Тип
pg_status Показывает результат выполнения запроса string
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money. Служит ключом для всей дальнейшей работы с транзакцией integer
pg_transaction_status Статус платежа string
pg_can_reject 0 или 1 – может ли платеж быть отменен. Значение 1 возможно только если статус платежа равен ok и платежная система предоставляет возможность отзыва платежа. В этом случае мерчант может вызвать revoke.php. integer
pg_testing_mode Enum:0 1
0 - платеж в боевом режиме 1 - платеж в тестовом режиме
integer
pg_captured Enum:0 1
Передается только в случае успешной оплаты банковской картой и показывает, был ли произведен клиринг в момент авторизации (что зависит только от настроек мерчанта). Если значение этого поля равно 0, мерчант должен в последующем дать команду на клиринг или дождаться когда PayBox.money сделает это сам.
integer
pg_card_pan Маскированный номер карты (часть цифр номера карты скрыты). Этот параметр передается только в случае успешной оплаты банковской картой. string
pg_card_id ID карты integer
pg_card_hash Хеш маскированной PAN карты string
pg_create_date Дата и время создания платежной транзакции datetime
pg_salt Случайная строка string
pg_sig Подпись запроса string


Сохраненной картой

[newman gif](/flow/cardsave/pay.svg)

Инициализация платежа по карте

Оплата сохраненной картой происходит в два этапа:

Для инициализации платежа используется следующий запрос:

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_amount' => 100,
    'pg_order_id' => 12345,
    'pg_user_id' => 1234,
    'pg_card_id' => 1234,
    'pg_description' => 'Описание платежа',
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'init');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/v1/merchant/{{paybox_merchant_id}}/card/init

Поля запроса
Название Описание Тип
pg_merchant_id
required
Идентификатор мерчанта в системе PayBox.money string
pg_amount
required
Сумма платежа.
Пример: 100
number
pg_order_id
required
ID заказа в системе мерчанта
Пример: 12345
string
pg_user_id
required
ID пользователя в системе мерчанта.
Пример: 1234
integer
pg_card_id
required
ID карты.
Пример: 56
integer
pg_description
required
Описание заказа
Пример: Описание платежа
string
pg_salt
required
Случайная строка, состоящая из произвольных цифр и латинских букв.
Пример: some random string
string
pg_sig
required
Подпись запроса string
pg_result_url URL для сообщения о результате платежа string
pg_success_url URL, на который отправляется пользователь в случае успешной оплаты string
pg_failure_url URL, на который отправляется пользователь в случае не успешного платежа string
Параметры ответа
Название Описание Тип
pg_status Показывает результат выполнения запроса string
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money. Служит ключом для всей дальнейшей работы с транзакцией integer
pg_merchant_id Идентификатор мерчанта в системе PayBox.money integer
pg_order_id Идентификатор заказа в системе мерчанта integer
pg_salt Случайная строка string
pg_sig Подпись запроса string


Проведение оплаты сохраненной карты

Для проведения оплаты необходимо выполнить следующий запрос:

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_payment_id' => 12345,
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'pay');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/v1/merchant/{{paybox_merchant_id}}/card/pay

Поля запроса
Название Описание Тип
pg_merchant_id
required
Идентификатор мерчанта в системе PayBox string
pg_payment_id
required
Внутренний идентификатор платежа в системе PayBox.money
Пример: 12345
integer
pg_salt
required
Случайная строка, состоящая из произвольных цифр и латинских букв.
Пример: some random string
string
pg_sig
required
Подпись запроса string


Запрос на result_url магазина. Результат платежа

Пример отрицательного ответа магазина

Запрос

curl --location --request POST '{{result_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_payment_system=EPAYWEBKZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=1' \
--form 'pg_payment_date=2019-01-01 12:00:00' \
--form 'pg_can_reject=1' \
--form 'pg_user_phone=7077777777777' \
--form 'pg_user_contact_email=mail@customer.kz' \
--form 'pg_testing_mode=1' \
--form 'pg_captured=0' \
--form 'pg_card_pan=5483-18XX-XXXX-0293' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <status>rejected</status>
    <pg_description>Платеж отменен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>

Пример положительного ответа магазина

Запрос

curl --location --request POST '{{result_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_payment_system=EPAYWEBKZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=1' \
--form 'pg_payment_date=2019-01-01 12:00:00' \
--form 'pg_can_reject=1' \
--form 'pg_user_phone=7077777777777' \
--form 'pg_user_contact_email=mail@customer.kz' \
--form 'pg_testing_mode=1' \
--form 'pg_captured=0' \
--form 'pg_card_pan=5483-18XX-XXXX-0293' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <status>ok</status>
    <pg_description>Заказ оплачен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>

После приема оплаты от клиента или при невозможности совершить платеж PayBox.money вызывает Result URL мерчанта и передает на него методом Request Method информацию о результате платежа.

При получении данного запроса мерчант должен произвести необходимые действия для передачи товара или услуги покупателю, в случае если платеж был успешным. Если pg_can_reject равно 1 и мерчант не может принять платеж (например, бронь на билеты истекла), он обязан ответить со статусом rejected, и PayBox,money отзовет платеж. В этом случае поле pg_description из ответа мерчанта показывается пользователю как причина отказа.

Если сервер мерчанта недоступен в момент вызова Result URL или ответ от сервера был со статусом 500, PayBox.money будет предпринимать повторные попытки его вызвать каждые полчаса в течение 2 часов, даже если время жизни счета pg_lifetime истечет.

Если первая попытка вызова Result URL оказалась не успешной, то платеж не отменяется, и в последующих вызовах Result URL не позволяет мерчанту отказаться от платежа.

Мерчант должен быть готов к тому, что Result URL будет вызван повторно для одного и того же платежа. Ответы на повторные вызовы должны совпадать с первоначальным ответом, даже если время жизни транзакции pg_lifetime истекло.

Ответ на result_url от мерчанта

Статус rejected может быть возвращен мерчантом только в случае, когда во входящем запросе от гейта был указан параметр pg_can_reject равный 1, в противном случае, вне зависимости от ответа мерчанта, платеж будет считаться совершенным. Если мерчант отказался от платежа (ответил rejected), покупатель перенаправляется на Failure URL, иначе – на Success URL.

Название Описание Тип
pg_order_id Идентификатор заказа в системе мерчанта
Пример: 123456789
string
pg_payment_id Внутренний идентификатор платежа в системе PayBox.money
Пример: 12345
integer
pg_currency Валюта выставленного счета, совпадает с pg_currency в момент инициализации платежа.
Пример: KZT
string
pg_ps_currency Валюта, в которой был произведен платеж в платежной системе. Поле может отсутствовать в случае неудачного платежа
Пример: KZT
string
pg_payment_system Идентификатор платежной системы
Пример: EPAYWEBKZT
string
pg_description Описание платежа
Пример: Покупка в интернет магазине Site.kz
string
pg_result Результат платежа. 1 – успех, 0 – неудача.
Пример: 1
integer
pg_payment_date Дата и время совершения платежа в формате YYYY-MM-DD HH:MM:SS.
Пример: 2019-01-01 12:00:00
datetime
pg_can_reject 1 – платеж можно откатить назад (например, Банковские карты), 0 – платеж безотзывный.
Пример: 1
integer
pg_user_phone Телефон покупателя (указанный при инициализации платежа)
Пример: 7077777777777
string
pg_user_contact_email Email покупателя (указанный при инициализации платежа)
Пример: mail@customer.kz
string
pg_testing_mode Тестовый режим. 1 - тестовый, 0 - боевой.
Пример: 1
integer
pg_captured Передается только в случае успешной оплаты банковской картой и показывает, был ли произведен клиринг в момент авторизации (что зависит только от настроек мерчанта). Если значение этого поля равно 0, мерчант должен в последующем дать команду на клиринг (см. раздел Запрос на клиринг транзакций по банковским картам) или дождаться когда PayBox.money сделает это сам.
Пример: 0
integer
pg_card_pan Маскированный номер карты (часть цифр номера карты скрыты). Этот параметр передается только в случае успешной оплаты банковской картой
Пример: 5483-18XX-XXXX-0293
string
Параметры мерчанта Все поля, переданные с веб-сайта мерчанта, не имеющие префикса pg_ string
pg_salt Случайная строка
Пример: some random string
string
pg_sig Подпись запроса string


Реккурентным платежом

Для использования профиля рекуррентных платежей мерчанту следует инициализировать платеж обычным способом c передачей дополнительного параметра pg_recurring_start, обозначающий требование создания рекуррентного профиля. Номер профиля для повторения платежа будет передан при оповещении о результате платежа.

Мерчант может задать требуемый срок, в течение которого будет возможным использовать рекуррентный профиль (параметр является необязательным, и в случае, когда мерчант не передал параметр, вместо него будет использован срок годности карты).

Если мерчант задал pg_recurring_lifetime, больше чем срок годности карты, датой истечения годности рекуррентного профиля будет дата, до которой возможно использовать карту.

В случае, когда мерчанту нужен рекуррентный профиль без первоначального платежа, возможно задать сумму pg_amount как 0, в этом случае будет создан профиль для проведения повторных платежей.

Инициализация платежа

Инициализация платежа

Запрос

curl --location --request POST 'https://api.paybox.money/init_payment.php' \
--form 'pg_order_id=23' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_amount=25' \
--form 'pg_description=test' \
--form 'pg_salt=molbulak' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'init_payment.php;25;test;{{paybox_merchant_id}};23;molbulak;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>4567788</pg_payment_id>
    <pg_redirect_url>https://api.paybox.money/pay.html?customer=498333170d6a895148c57c53ffb18287</pg_redirect_url>
    <pg_redirect_url_type>need data</pg_redirect_url_type>
    <pg_salt>bdwLavL9lg6It91b</pg_salt>
    <pg_sig>709633e91387c56ac6fb7cb33d1e07d8</pg_sig>
</response>

При прямой передаче данных от магазина в PayBox.money мерчант должен посылать данные на init_payment.php.

Отправляется параметры pg_recurring_start и pg_recurring_lifetime для подписки платежа.

Можно передавать произвольные дополнительные параметры, имена которых не начинаются на pg_. Все эти параметры будут переданы на pg_check_url и pg_result_url.

Имена дополнительных параметров мерчанта должны быть уникальны.

После получение параметра pg_redirect_url пользователя перенаправляют на платежную страницу где плательщик завершает платеж.

В случае успеха пользователь будет перенаправлен на страницу оплаты, где сохраняет карту в нашей системе.

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_amount' => 10,
    'pg_salt' => 'some random string',
    'pg_order_id'=> '00102',
    'pg_description' => 'Ticket',
    'pg_result_url' => 'http://site.kz/result'
];

// $request['pg_testing_mode'] = 1; //add this parameter to request for testing payments

//if you pass any of your parameters, which you want to get back after the payment, then add them. For example:
// $request['client_name'] = 'My Name';
// $request['client_address'] = 'Earth Planet';

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'init_payment.php');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // request sign

unset($request[0], $request[1]);

Далее в Result url приходит параметр pg_recurring_profile_id.

URL запроса

POST https://api.paybox.money/init_payment.php

Поля запроса
Название Описание Тип
pg_order_id
required
Идентификатор платежа в системе мерчанта. Рекомендуется поддерживать уникальность этого поля.
Пример: 00102
string
pg_merchant_id
required
Идентификатор мерчанта в PayBox.money. Выдается при подключении. integer
pg_amount
required
Сумма платежа в валюте pg_currency.
Пример: 10
number
pg_description
required
Описание товара или услуги. Отображается покупателю в процессе платежа.
Пример: Ticket
string
pg_salt
required
Случайная строка
Пример: some random string
string
pg_sig
required
Подпись запроса string
pg_currency Валюта, в которой указана сумма. KZT, USD, EUR. В случае выбора покупателем способа платежа в другой валюте, производится пересчет по курсу ЦБ на день платежа. См. в разделе Справочник валют
Пример: KZT
string
pg_check_url URL для проверки возможности платежа. Вызывается перед платежом, если платежная система предоставляет такую возможность. Если параметр не указан, то берется из настроек мерчанта. Если параметр установлен равным пустой строке, то проверка возможности платежа не производится. string
pg_result_url URL для сообщения о результате платежа. Вызывается после платежа в случае успеха или неудачи. Если параметр не указан, то берется из настроек мерчанта. Если параметр установлен равным пустой строке, то PayBox.money не сообщает мерчанту о результате платежа. string
pg_request_method GET, POST или XML – метод вызова скриптов мерчанта Check URL, Result URL, для передачи информации от платежного гейта.
Пример: POST
string
pg_success_url url, на который отправляется пользователь в случае успешного платежа (только для online систем) string
pg_failure_url url, на который отправляется пользователь в случае неуспешного платежа (только для online систем) string
pg_success_url_method GET – кнопка, которая сабмитится методом GET. POST – кнопка, которая сабмитится методом POST. Если выбран метод GET или POST, то страница с подтверждением оплаты показывается пользователю на сайте paybox.money, и предлагается нажать кнопку, чтобы вернуться на сайт мерчанта.
Пример: GET
string
pg_failure_url_method GET – кнопка, которая сабмитится методом GET. POST – кнопка, которая сабмитится методом POST. Если выбран метод GET или POST, то страница с сообщением о неудавшейся оплате показывается пользователю на сайте paybox.money, и предлагается нажать кнопку, чтобы вернуться на сайт мерчанта.
Пример: GET
string
pg_state_url URL скрипта на сайте мерчанта, куда перенаправляется покупатель для ожидания ответа от платежной системы.
Пример: http://site.kz/state
string
pg_state_url_method GET – кнопка, которая сабмитится методом GET.
POST – кнопка, которая сабмитится методом POST.
AUTOGET – 302 редирект. См. Автоматическая передача информации, п.1.
AUTOPOST – форма, которая автоматически сабмитится. См. Автоматическая передача информации, п.2.
Если выбран метод GET или POST, то страница с сообщением о неудавшейся оплате показывается пользователю на сайте paybox.money, и предлагается нажать кнопку, чтобы вернуться на сайт мерчанта.
Если выбран метод AUTOGET или AUTOPOST, то страница с сообщением о неудавшейся оплате не показывается пользователю, и пользователь сразу передается мерчанту.
Пример: GET
string
pg_site_url URL сайта мерчанта для показа покупателю ссылки, по которой он может вернуться на сайт мерчанта после создания счета. Применяется для offline ПС (наличные).
Пример: http://site.kz/return
string
pg_payment_system Идентификатор платёжной системы. Этот параметр передается только если выбор платежной системы совершается на сайте мерчанта. Если параметр не указан, то выбор ПС совершается на сайте PayBox.money
Пример: EPAYWEBKZT
string
pg_lifetime Default: "86400"
Время (в секундах) в течение которого платеж должен быть завершен, в противном случае PayBox.money откажет платежной системе в проведении платежа. Этот параметр контролируется PayBox.money, а также, если платежная система поддерживает такую возможность, и платежной системой. Минимально допустимое значение: 300 секунд (5 минут). Максимально допустимое значение: 604800 секунд (7 суток). В случае выхода за пограничные значения будет присвоено минимальное или максимальное значение, соответственно.
Пример: 86400
integer
pg_user_phone Телефон пользователя (начиная с кода страны), необходим для идентификации покупателя. Если не указан, выбор будет предложен пользователю на сайте платежного гейта.
Пример: 77777777777
string
pg_user_contact_email Контактный адрес электронной почты пользователя. Если указан, на этот адрес будут высылаться уведомления об изменении статуса транзакции.
Пример: mail@customer.kz
string
pg_user_ip IP-адрес клиента. Необходим для разбора спорных ситуаций в случае подозрения на мошенничество. Параметр можно не передавать, при передаче информации через браузер пользователя, в этом случае будет записан тот IP, с которого пользователь перешёл на страницу инициализации платежа.
Пример: 127.0.0.1
string
pg_postpone_payment Создание платежа с отложенной оплатой если в этом параметре передано «1». В таком случае покупатель будет перенаправлен на страницу с информацией о том, что ему было выслано письмо с ссылкой на страницу для продолжения проведения платежа. Если этот параметр присутствует в запросе, то должен быть указан также pg_user_contact_email, иначе пользователь будет перенаправлен на уточнение платежных параметров, где он может указать email и попробовать отложить платеж ещё раз.
Пример: 0
integer
pg_language Язык платежных страниц на сайте PayBox.money и (если возможно) платежных систем. "en", "ru"
Пример: ru
string
pg_testing_mode Создание платежа в тестовом режиме.
Пример: 1
integer
pg_user_id
required
ID пользователя в системе мерчанта.
Пример: 123
integer
pg_recurring_start Флаг, принимает значение 0 или 1. Подробное описание см. в разделе Рекуррентные платежи. Для использования данного параметра Вам следует обратиться к своему менеджеру.
Пример: 1
integer
pg_recurring_lifetime Время на продолжении которого мерчант рассчитывает использовать профиль рекуррентных платежей. Минимально допустимое значение 1 (1 месяц). Максимально допустимое значение: 156 (13 лет). В случае выхода за пограничные значения будет присвоено минимальное или максимальное значение, соответственно. Подробное описание см. в разделе Рекуррентные платежи. Для использования данного параметра Вам следует обратиться к своему менеджеру.
Пример: 156
integer
pg_receipt_positions[0][count] Количество товара.
Пример: 2
integer
pg_receipt_positions[0][name] Наименование товара
Пример: Коврик для мыши
string
pg_receipt_positions[0][tax_type] Тип налога.
Пример: 3
integer
pg_receipt_positions[0][price] Цена за 1 ед. товара.
Пример: 1000
number
pg_param1 Дополнительный параметр 1
Пример: Дополнительная информация
string
pg_param2 Дополнительный параметр 2
Пример: Дополнительная информация
string
pg_param3 Дополнительный параметр 3
Пример: Дополнительная информация
string
pg_auto_clearing Если 1 клиринг будет происходить сразу, в случае 0 необходимо сделать ручной клиринг. Подробное описание см. в разделе Запрос на клиринг транзакций по банковским картам. Для использования данного параметра Вам следует обратиться к своему менеджеру.
Пример: 1
integer
Параметры ответа
Название Описание Тип
pg_status Показывает результат выполнения запроса string
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money. Служит ключом для всей дальнейшей работы с транзакцией integer
pg_redirect_url URL для перенаправления пользователя. Может быть как на сайте paybox.money, так и на сайте платежной системы string
pg_redirect_url_type Тип страницы, на которую происходит перенаправление. Возможные значения:
need data – диалог с покупателем с целью уточнения параметров: платежной системы, номера телефона, обязательных для данной платежной системы параметров;
payment system – страница сайта платежной системы либо страница с инструкциями оплаты через данную платежную систему. Страница с инструкциями может располагаться как на сайте paybox.money, так и на сайте мерчанта.

В случае получения мерчантом ответа с pg_redirect_url_type=”need data”, мерчант может не перенаправлять покупателя по полученному URL, а уточнить недостающие параметры у себя на сайте. В этом случае после уточнения параметров и повторного запроса на создание платежной транзакции будет создана новая транзакция
string
pg_salt Случайная строка string
pg_sig Подпись запроса string


Повторение рекуррентного платежа

Мерчант может повторять платежи по рекуррентному профилю в любой момент по своему усмотрению, для этого необходимо выполнить запрос на make_recurring_payment.php с параметром pg_recurring_profile полученный от Result url запроса.

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_recurring_profile' => 1234,
    'pg_description' => 'Описание платежа',
    'pg_salt' => 'some random string',
];

array_unshift($request, 'make_recurring_payment.php');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // request sign

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/make_recurring_payment.php

Поля запроса
Название Описание Тип
pg_merchant_id
required
Идентификатор мерчанта в PayBox.money string
pg_recurring_profile
required
Идентификатор рекуррентного профиля. Был получен мерчантом при создании профиля рекуррентных платежей.
Пример: 1234
integer
pg_description
required
Описание товара или услуги. Отображается покупателю в процессе платежа. Передается в кодировке pg_encoding.
Пример: Описание платежа
string
pg_salt
required
Случайная строка
Пример: some random string
string
pg_sig
required
Подпись запроса string
pg_order_id Идентификатор платежа в системе мерчанта. Рекомендуется поддерживать уникальность этого поля
Пример: 1234
string
pg_amount Сумма платежа в валюте pg_currency. Является необязательным параметром. В случае если не была передана сумма, в качестве суммы для повторения платежа, будет использовано значение первоначального платежа.
Пример: 100
string
pg_result_url URL для сообщения о результате платежа. Вызывается после платежа в случае успеха или неудачи. Если параметр не указан, то берется из настроек мерчанта. Если параметр установлен равным пустой строке, то PayBox.money не сообщает мерчанту о результате платежа.
Пример: http://site.kz/result
string
pg_request_method GET, POST или XML – метод вызова скриптов мерчанта Check URL, Result URL, для передачи информации от платежного гейта.
Пример: POST
string
Параметры ответа

В случае успеха пользователь будет перенаправлен на страницу оплаты. В случае если мерчантом переданы не все параметры, необходимые для создания платежной транзакции (платежная система, телефон пользователя и параметры, необходимые для выбранной платежной системы), они запрашиваются у пользователя на сайте paybox.money.


Получение статуса платежа

*Not found - Получение статуса платежа *

Запрос

curl --location --request POST 'https://api.paybox.money/get_status.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_payment_id=12345' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status.php;{{paybox_merchant_id}};12345;00102;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>error</pg_status>
    <pg_error_code>340</pg_error_code>
    <pg_error_description>Транзакция не найдена</pg_error_description>
</response>

Partial - Получение статуса платежа

Запрос

curl --location --request POST 'https://api.paybox.money/get_status.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_payment_id=4567617' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status.php;{{paybox_merchant_id}};4567617;00102;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>4567617</pg_payment_id>
    <pg_transaction_status>partial</pg_transaction_status>
    <pg_can_reject>0</pg_can_reject>
    <pg_testing_mode>1</pg_testing_mode>
    <pg_captured>0</pg_captured>
    <pg_create_date>2020-05-21 18:44:21</pg_create_date>
    <pg_salt>u1aHmP4QyTxUqzXz</pg_salt>
    <pg_sig>574a9d2e4783cb3d5ea443e1cc4f9434</pg_sig>
</response>

Ok - Получение статуса платежа

Запрос

curl --location --request POST 'https://api.paybox.money/get_status.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_payment_id=4567775' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status.php;{{paybox_merchant_id}};4567775;00102;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>4567775</pg_payment_id>
    <pg_transaction_status>ok</pg_transaction_status>
    <pg_can_reject>1</pg_can_reject>
    <pg_testing_mode>1</pg_testing_mode>
    <pg_captured>0</pg_captured>
    <pg_card_pan>5483-18XX-XXXX-0293</pg_card_pan>
    <pg_card_id>205</pg_card_id>
    <pg_card_hash>e5b78033320bb1de831439cbc9ec543a</pg_card_hash>
    <pg_create_date>2020-06-01 16:58:40</pg_create_date>
    <pg_salt>OX1MwChiToQFR1Fy</pg_salt>
    <pg_sig>8fec63c0e02d3d8f98d9eff2d4f6c226</pg_sig>
</response>

Мерчант может запрашивать PayBox.money о статусе любого платежа, инициированного мерчантом. Это может быть полезно, например, в случае если вызов Result URL не был получен мерчантом из-за временного сбоя связи, а покупатель уже был передан на Success URL, однако статус транзакции мерчанту еще не известен.

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_payment_id' => 12345,
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'get_status.php');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/get_status.php

Поля запроса
Название Описание Тип
pg_merchant_id
required
Идентификатор мерчанта в PayBox.money. Выдается при подключении. string
pg_payment_id
required
Внутренний идентификатор платежа в системе PayBox.money
если отправлена вместе с полем pg_order_id, то поле pg_order_id будет проигнорировано.
Пример: 12345
integer
pg_order_id Идентификатор платежа в системе мерчанта. Будьте внимательны, при запросе по order_id мерчант должен самостоятельно следить за уникальностью данного параметра иначе будет выдана информация для последнего платежа с данным order_id для данного мерчанта.
Пример: 00102
string
pg_salt
required
Случайная строка
Пример: some random string
string
pg_sig
required
Подпись запроса string
Параметры ответа
Название Описание Тип
pg_status Показывает результат выполнения запроса string
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money. Служит ключом для всей дальнейшей работы с транзакцией integer
pg_transaction_status Статус платежа string
pg_can_reject 0 или 1 – может ли платеж быть отменен. Значение 1 возможно только если статус платежа равен ok и платежная система предоставляет возможность отзыва платежа. В этом случае мерчант может вызвать revoke.php. integer
pg_testing_mode Enum:0 1
0 - платеж в боевом режиме 1 - платеж в тестовом режиме
integer
pg_captured Enum:0 1
Передается только в случае успешной оплаты банковской картой и показывает, был ли произведен клиринг в момент авторизации (что зависит только от настроек мерчанта). Если значение этого поля равно 0, мерчанта должен в последующем дать команду на клиринг или дождаться когда PayBox.money сделает это сам.
integer
pg_card_pan Маскированный номер карты (часть цифр номера карты скрыты). Этот параметр передается только в случае успешной оплаты банковской картой. string
pg_card_id ID карты integer
pg_card_hash Хеш маскированной PAN карты string
pg_create_date Дата и время создания платежной транзакции datetime
pg_salt Случайная строка string
pg_sig Подпись запроса string


Балансом мобильного

PayBox предлагает возможность оплачивать заказ/услугу с баланса мобильного телефона, если мобильный оператор плательщика поддерживает данную возможность. Доступные мобильные операторы:

Tele2 (TELE2KZT)
Altel (ALTELKZT)
Beeline (BEELINEKZT)
Activ (ACTIVKZT)
Kcell (KCELLKZT)

Инициализация платежа

Инициализация платежа

Запрос

curl --location --request POST 'https://api.paybox.money/init_payment.php' \
--form 'pg_order_id=23' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_amount=25' \
--form 'pg_description=test' \
--form 'pg_salt=molbulak' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'init_payment.php;25;test;{{paybox_merchant_id}};23;molbulak;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>4567788</pg_payment_id>
    <pg_redirect_url>https://api.paybox.money/pay.html?customer=498333170d6a895148c57c53ffb18287</pg_redirect_url>
    <pg_redirect_url_type>need data</pg_redirect_url_type>
    <pg_salt>bdwLavL9lg6It91b</pg_salt>
    <pg_sig>709633e91387c56ac6fb7cb33d1e07d8</pg_sig>
</response>

При прямой передаче данных от мерчанта в PayBox.money мерчант должен посылать данные на init_payment.php.

Можно передавать произвольные дополнительные параметры, имена которых не начинаются на pg_. Все эти параметры будут переданы на pg_check_url и pg_result_url.

Имена дополнительных параметров мерчанта должны быть уникальны.

После получение параметра pg_redirect_url пользователя перенаправляют на платежную страницу где плательщик завершает платеж.

В случае успеха пользователь будет перенаправлен на страницу оплаты.

В случае если мерчантом переданы не все параметры, необходимые для создания платежной транзакции (платежная система, телефон пользователя и параметры, необходимые для выбранной платежной системы), они запрашиваются у пользователя на сайте paybox.money.

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_amount' => 10,
    'pg_salt' => 'some random string',
    'pg_order_id'=> '00102',
    'pg_description' => 'Ticket',
    'pg_result_url' => 'http://site.kz/result'
];

// $request['pg_testing_mode'] = 1; //add this parameter to request for testing payments

//if you pass any of your parameters, which you want to get back after the payment, then add them. For example:
// $request['client_name'] = 'My Name';
// $request['client_address'] = 'Earth Planet';

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'init_payment.php');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/init_payment.php

Поля запроса
Название Описание Тип
pg_order_id
required
Идентификатор платежа в системе мерчанта. Рекомендуется поддерживать уникальность этого поля.
Пример: 00102
string
pg_merchant_id
required
Идентификатор мерчанта в PayBox.money. Выдается при подключении. integer
pg_amount
required
Сумма платежа в валюте pg_currency.
Пример: 10
number
pg_description
required
Описание товара или услуги. Отображается покупателю в процессе платежа.
Пример: Ticket
string
pg_salt
required
Случайная строка
Пример: some random string
string
pg_sig
required
Подпись запроса string
pg_currency Валюта, в которой указана сумма. KZT, USD, EUR. В случае выбора покупателем способа платежа в другой валюте, производится пересчет по курсу ЦБ на день платежа. См. в разделе Справочник валют
Пример: KZT
string
pg_check_url URL для проверки возможности платежа. Вызывается перед платежом, если платежная система предоставляет такую возможность. Если параметр не указан, то берется из настроек мерчанта. Если параметр установлен равным пустой строке, то проверка возможности платежа не производится. string
pg_result_url URL для сообщения о результате платежа. Вызывается после платежа в случае успеха или неудачи. Если параметр не указан, то берется из настроек мерчанта. Если параметр установлен равным пустой строке, то PayBox.money не сообщает мерчанту о результате платежа. string
pg_request_method GET, POST или XML – метод вызова скриптов мерчанта Check URL, Result URL, для передачи информации от платежного гейта.
Пример: POST
string
pg_success_url url, на который отправляется пользователь в случае успешного платежа (только для online систем) string
pg_failure_url url, на который отправляется пользователь в случае неуспешного платежа (только для online систем) string
pg_success_url_method GET – кнопка, которая сабмитится методом GET. POST – кнопка, которая сабмитится методом POST. Если выбран метод GET или POST, то страница с подтверждением оплаты показывается пользователю на сайте paybox.money, и предлагается нажать кнопку, чтобы вернуться на сайт мерчанта.
Пример: GET
string
pg_failure_url_method GET – кнопка, которая сабмитится методом GET. POST – кнопка, которая сабмитится методом POST. Если выбран метод GET или POST, то страница с сообщением о неудавшейся оплате показывается пользователю на сайте paybox.money, и предлагается нажать кнопку, чтобы вернуться на сайт мерчанта.
Пример: GET
string
pg_state_url URL скрипта на сайте мерчанта, куда перенаправляется покупатель для ожидания ответа от платежной системы.
Пример: http://site.kz/state
string
pg_state_url_method GET – кнопка, которая сабмитится методом GET.
POST – кнопка, которая сабмитится методом POST.
AUTOGET – 302 редирект. См. Автоматическая передача информации, п.1.
AUTOPOST – форма, которая автоматически сабмитится. См. Автоматическая передача информации, п.2.
Если выбран метод GET или POST, то страница с сообщением о неудавшейся оплате показывается пользователю на сайте paybox.money, и предлагается нажать кнопку, чтобы вернуться на сайт мерчанта.
Если выбран метод AUTOGET или AUTOPOST, то страница с сообщением о неудавшейся оплате не показывается пользователю, и пользователь сразу передается мерчанту.
Пример: GET
string
pg_site_url URL сайта мерчанта для показа покупателю ссылки, по которой он может вернуться на сайт мерчанта после создания счета. Применяется для offline ПС (наличные).
Пример: http://site.kz/return
string
pg_payment_system Идентификатор платёжной системы. Этот параметр передается только если выбор платежной системы совершается на сайте мерчанта. Если параметр не указан, то выбор ПС совершается на сайте PayBox.money. Enum:"TELE2KZT" "ALTELKZT" "BEELINEKZT" "KCELLKZT" "ACTIVKZT"
Пример: TELE2KZT
string
pg_lifetime Default: "86400"
Время (в секундах) в течение которого платеж должен быть завершен, в противном случае заказ при проведении платежа PayBox.money откажет платежной системе в проведении. Этот параметр контролируется PayBox.money, а также, если платежная система поддерживает такую возможность, и платежной системой. Минимально допустимое значение: 300 секунд (5 минут). Максимально допустимое значение: 604800 секунд (7 суток). В случае выхода за пограничные значения будет присвоено минимальное или максимальное значение, соответственно.
Пример: 86400
integer
pg_user_phone Телефон пользователя (начиная с кода страны), необходим для идентификации покупателя. Если не указан, выбор будет предложен пользователю на сайте платежного гейта.
Пример: 77777777777
string
pg_user_contact_email Контактный адрес электронной почты пользователя. Если указан, на этот адрес будут высылаться уведомления об изменении статуса транзакции.
Пример: mail@customer.kz
string
pg_user_ip IP-адрес клиента. Необходим для разбора спорных ситуаций в случае подозрения на мошенничество. Параметр можно не передавать при передаче информации через браузер пользователя, в этом случае будет записан тот IP, с которого пользователь перешёл на страницу инициализации платежа.
Пример: 127.0.0.1
string
pg_postpone_payment Создание платежа с отложенной оплатой если в этом параметре передано «1». В таком случае покупатель будет перенаправлен на страницу с информацией о том, что ему было выслано письмо со ссылкой на страницу для продолжения проведения платежа. Если этот параметр присутствует в запросе, то должен быть указан также pg_user_contact_email, иначе пользователь будет перенаправлен на уточнение платежных параметров, где он сможет, указать email и попробовать отложить платеж ещё раз.
Пример: 0
integer
pg_language Язык платежных страниц на сайте PayBox.money и (если возможно) платежных систем. "en", "ru"
Пример: ru
string
pg_testing_mode Создание платежа в тестовом режиме.
Пример: 1
integer
pg_user_id ID пользователя в системе мерчанта.
Пример: 123
integer
pg_recurring_start Флаг, принимает значение 0 или 1. Подробное описание см. в разделе Рекуррентные платежи. Для использования данного параметра Вам следует обратиться к своему менеджеру.
Пример: 1
integer
pg_recurring_lifetime Время на продолжении которого мерчант рассчитывает использовать профиль рекуррентных платежей. Минимально допустимое значение 1 (1 месяц). Максимально допустимое значение: 156 (13 лет). В случае выхода за пограничные значения будет присвоено минимальное или максимальное значение, соответственно. Подробное описание см. в разделе Рекуррентные платежи. Для использования данного параметра Вам следует обратиться к своему менеджеру.
Пример: 156
integer
pg_param1 Дополнительный параметр 1
Пример: Дополнительная информация
string
pg_param2 Дополнительный параметр 2
Пример: Дополнительная информация
string
pg_param3 Дополнительный параметр 3
Пример: Дополнительная информация
string
pg_auto_clearing Если 1 клиринг будет происходить сразу, в случае 0 необходимо сделать ручной клиринг. Подробное описание см. в разделе Запрос на клиринг транзакций по банковским картам. Для использования данного параметра Вам следует обратиться к своему менеджеру.
Пример: 1
integer
Параметры ответа
Название Описание Тип
pg_status Показывает результат выполнения запроса string
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money. Служит ключом для всей дальнейшей работы с транзакцией integer
pg_redirect_url URL для перенаправления пользователя. Может быть как на сайте paybox.money, так и на сайте платежной системы string
pg_redirect_url_type Тип страницы, на которую происходит перенаправление. Возможные значения:
need data – диалог с покупателем с целью уточнения параметров: платежной системы, номера телефона, обязательных для данной платежной системы параметров;
payment system – страница сайта платежной системы либо страница с инструкциями оплаты через данную платежную систему. Страница с инструкциями может располагаться как на сайте paybox.money, так и на сайте мерчанта.

В случае получения мерчантом ответа с pg_redirect_url_type=”need data”, мерчант может не перенаправлять покупателя по полученному URL, а уточнить недостающие параметры у себя на сайте. В этом случае после уточнения параметров и повторного запроса на создание платежной транзакции будет создана новая транзакция
string
pg_salt Случайная строка string
pg_sig Подпись запроса string


Оплата с мобильного

Платёж в большинстве случаев проходит OTP-верификацию. Т.е. для совершения платежа требуется подтверждение. Но по особым договоренностям есть возможность отключить OTP-верификацию.

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_payment_id' => 12345,
    'pg_abonent_phone' => 77077777777,
    'pg_payment_system_code' => 'ALTELKZT',
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'pay');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);

Если в ответе pg_status равен need_approve PayBox.money отправит SMS сообщение на номер указанный в pg_abonent_phone с OTP кодом. Для продолжения мерчанту необходимо запросить данный код у плательщика.

URL запроса

POST https://api.paybox.money/mfs/pay

Поля запроса
Название Описание Тип
pg_merchant_id
required
Идентификатор мерчанта в системе PayBox.money. string
pg_payment_id
required
Внутренний идентификатор платежа в системе PayBox.money
Пример: 12345
integer
pg_abonent_phone
required
Телефон покупателя с баланса которого снимутся деньги.
Пример: 77077777777
string
pg_payment_system_code Уникальный код мобильного оператора. Enum:"TELE2KZT" "ALTELKZT" "BEELINEKZT" "KCELLKZT" "ACTIVKZT"
Пример: ALTELKZT
string
pg_salt
required
Случайная строка
Пример: some random string
string
pg_sig
required
Подпись запроса string


Подтверждение платежа

Для подтверждение платежа отправляется след запрос:

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_payment_id' => 12345,
    'pg_approval_code' => 0077587,
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'approve');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/mfs/approve

Поля запроса
Название Описание Тип
pg_merchant_id
required
Идентификатор магазина в системе PayBox.money. integer
pg_payment_id
required
Внутренний идентификатор платежа в системе PayBox.money.
Пример: 12345
integer
pg_approval_code
required
Одноразовый OTP код отправленный SMS сообщением на номер плательщика.
Пример: 0077587
integer
pg_salt
required
Случайная строка
Пример: some random string
string
pg_sig
required
Подпись запроса string


Запрос на повторную отправку SMS кода

Мерчант может еще раз запрашивать повторную отправку SMS кода.

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_payment_id' => 12345,
    'pg_abonent_phone' => 77077777777,
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'resend_otp');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/mfs/resend_otp

Поля запроса
Название Описание Тип
pg_merchant_id
required
Идентификатор магазина в системе PayBox.money. integer
pg_payment_id
required
Идентификатор платежа в системе PayBox.money.
Пример: 12345
integer
pg_abonent_phone
required
Телефон покупателя с баланса которого снимутся деньги.
Пример: 77077777777
string
pg_salt
required
Случайная строка
Пример: some random string
string
pg_sig
required
Подпись запроса string


Проверка номера по MNP

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_abonent_phone' => 77077777777,
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'check_mnp');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/mfs/check_mnp

Поля запроса
Название Описание Тип
pg_merchant_id
required
Идентификатор магазина в системе PayBox.money. integer
pg_abonent_phone
required
Номер телефона абонента
Пример: 77077777777
string
pg_salt
required
Случайная строка
Пример: some random string
string
pg_sig
required
Подпись запроса string


Запрос на check_url магазина. Проверка возможности совершить платеж.

Пример отрицательного ответа магазина

Запрос

curl --location --request POST '{{check_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=10' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_ps_amount=5' \
--form 'pg_ps_full_amount=5' \
--form 'pg_payment_system=EPAYWEBKZT' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <status>rejected</status>
    <pg_description>Платеж не разрешен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>

Пример положительного ответа магазина

Запрос

curl --location --request POST '{{check_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=10' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_ps_amount=5' \
--form 'pg_ps_full_amount=5' \
--form 'pg_payment_system=EPAYWEBKZT' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <status>ok</status>
    <pg_description>Платеж разрешен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>

Перед тем как принять деньги от покупателя по счету, платежный гейт может вызвать скрипт мерчанта Check URL с помощью метода Request Method.

PayBox.money передает информацию о номере и свойствах заказа и ожидает ответа. Отсутствие ответа за указанное время воспринимается как отказ от платежа.

Вызов скрипта Check URL происходит только в случае, если такая опция была включена в настройках мерчанта.

Ответ на check_url от мерчанта

Если Check URL определен пустым в момент инициализции платежа или не указан в момент инициализации платежа, а в настройках мерчанта установлен пустым, то шаг проверки возможности совершить платеж пропускается и считается, что мерчант согласен принять платеж.

Название Описание Тип
pg_order_id Идентификатор заказа в системе мерчант
Пример: 123456789
string
pg_payment_id Внутренний идентификатор платежа в системе PayBox.money.
Пример: 12345
integer
pg_amount Сумма выставленного счета (в валюте pg_currency), совпадает с pg_amount в момент инициализации платежа.
Пример: 10
number
pg_currency Валюта выставленного счета, совпадает с pg_currency в момент инициализации платежа.
Пример: KZT
string
pg_ps_currency Валюта, в которой был произведен платеж в платежной системе. Поле может отсутствовать в случае неудачного платежа
Пример: KZT
string
pg_ps_amount Сумма счета (в валюте pg_ps_currency), выставленного в платежной системе.
Пример: 5
number
pg_ps_full_amount Полная сумма (в валюте pg_ps_currency), которую заплатит покупатель с учетом всех комиссий.
Пример: 5
number
pg_payment_system Идентификатор платежной системы
Пример: EPAYWEBKZT
string
Параметры мерчанта Все поля, переданные с веб-сайта мерчант, не имеющие префикса pg_ string
pg_salt Случайная строка
Пример: some random string
string
pg_sig Подпись запроса string


Запрос на result_url магазина. Результат платежа

Пример положительного ответа магазина

Запрос

curl --location --request POST '{{result_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_payment_system=EPAYWEBKZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=1' \
--form 'pg_payment_date=2019-01-01 12:00:00' \
--form 'pg_can_reject=1' \
--form 'pg_user_phone=7077777777777' \
--form 'pg_user_contact_email=mail@customer.kz' \
--form 'pg_testing_mode=1' \
--form 'pg_captured=0' \
--form 'pg_card_pan=5483-18XX-XXXX-0293' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <status>ok</status>
    <pg_description>Заказ оплачен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>

Пример отрицательного ответа магазина

Запрос

curl --location --request POST '{{result_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_payment_system=EPAYWEBKZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=1' \
--form 'pg_payment_date=2019-01-01 12:00:00' \
--form 'pg_can_reject=1' \
--form 'pg_user_phone=7077777777777' \
--form 'pg_user_contact_email=mail@customer.kz' \
--form 'pg_testing_mode=1' \
--form 'pg_captured=0' \
--form 'pg_card_pan=5483-18XX-XXXX-0293' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <status>rejected</status>
    <pg_description>Платеж отменен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>

После приема денег от клиента или при невозможности совершить платеж PayBox.money вызывает Result URL мерчанта и передает на него методом Request Method информацию о результате платежа.

При получении данного запроса мерчант должен произвести необходимые действия для передачи товара или услуги покупателю, в случае если платеж был успешным. Если pg_can_reject равно 1 и мерчант не может принять платеж (например, бронь на билеты истекла), он обязан ответить со статусом rejected, и PayBox.money отзовет платеж. В этом случае поле pg_description из ответа мерчанта показывается пользователю как причина отказа.

Если сервер мерчанта недоступен в момент вызова Result URL или ответ от сервера был со статусом 500, PayBox.money будет предпринимать повторные попытки его вызвать каждые полчаса в течение 2 часов, даже если время жизни счета pg_lifetime истечет.

Если первая попытка вызова Result URL оказалась не успешной, то платеж не отменяется, и в последующих вызовах Result URL не позволяет мерчанту отказаться от платежа.

Мерчант должен быть готов к тому, что Result URL будет вызван повторно для одного и того же платежа. Ответы на повторные вызовы должны совпадать с первоначальным ответом, даже если время жизни транзакции pg_lifetime истекло.

Ответ на result_url от мерчанта

Статус rejected может быть возвращен мерчантом только в случае, когда во входящем запросе от гейта был указан параметр pg_can_reject равный 1, в противном случае, вне зависимости от ответа мерчанта, платеж будет считаться совершенным. Если мерчант отказался от платежа (ответил rejected), покупатель перенаправляется на Failure URL, иначе – на Success URL.

Название Описание Тип
pg_order_id Идентификатор заказа в системе мерчанта
Пример: 123456789
string
pg_payment_id Внутренний идентификатор платежа в системе PayBox.money.
Пример: 12345
integer
pg_currency Валюта выставленного счета, совпадает с pg_currency в момент инициализации платежа.
Пример: KZT
string
pg_ps_currency Валюта, в которой был произведен платеж в платежной системе. Поле может отсутствовать в случае неудачного платежа
Пример: KZT
string
pg_payment_system Идентификатор платежной системы
Пример: EPAYWEBKZT
string
pg_description Описание платежа
Пример: Покупка в интернет магазине Site.kz
string
pg_result Результат платежа. 1 – успех, 0 – неудача.
Пример: 1
integer
pg_payment_date Дата и время совершения платежа в формате YYYY-MM-DD HH:MM:SS.
Пример: 2019-01-01 12:00:00
datetime
pg_can_reject 1 – платеж можно откатить назад (например, Банковские карты), 0 – платеж безотзывный.
Пример: 1
integer
pg_user_phone Телефон покупателя (указанный при инициализации платежа)
Пример: 7077777777777
string
pg_user_contact_email Email покупателя (указанный при инициализации платежа)
Пример: mail@customer.kz
string
pg_testing_mode Тестовый режим. 1 - тестовый, 0 - боевой.
Пример: 1
integer
pg_captured Передается только в случае успешной оплаты банковской картой и показывает, был ли произведен клиринг в момент авторизации (что зависит только от настроек мерчанта). Если значение этого поля равно 0, мерчант должен в последующем дать команду на клиринг (см. раздел Запрос на клиринг транзакций по банковским картам) или дождаться когда PayBox.money сделает это сам.
Пример: 0
integer
pg_card_pan Маскированный номер карты (часть цифр номера карты скрыты). Этот параметр передается только в случае успешной оплаты банковской картой
Пример: 5483-18XX-XXXX-0293
string
Параметры мерчанта Все поля, переданные с веб-сайта мерчант, не имеющие префикса pg_ string
pg_salt Случайная строка
Пример: some random string
string
pg_sig Подпись запроса string


Через чекаут

Чтобы использовать данный вид создания платежа вам следует обратиться к своему менеджеру.

Чекаут (всплывающая форма оплаты) дает возможность создания платежа на странице вашего сайта с помощью токена, который вам может предоставить личный менеджер. Платеж осуществляется через всплывающее окно, которое вызывается при нажатии на кнопку покупателем

Сценарий платежа

  1. Покупатель формирует заказ на вашем сайте
  2. Покупатель нажимает на кнопку покупки товара
  3. Ваш сайт ининциализирует чекаут
  4. PayBox.money вызывает всплывающее окно, где и происходит процесс платежа
  5. В случае успешного платежа или ошибки ваш сайт получает соответствующее уведомление

Подключение чекаута

Для использования чекаута на своем сайте, мерчант должен подключить следующий скрипт:

  <script>
    (function (p, a, y, b, o, x) {
        o = p.createElement(a);
        x = p.getElementsByTagName(a)[0];
        o.async = 1;
        o.src = 'https://widget.paybox.money/v1/paybox/pbwidget.js?' + 1 * new Date();
        x.parentNode.insertBefore(o, x);
    })(document, 'script');
  </script>

Далее при нажатии на кнопку оплаты вызвать метод создания платежа. Минимальная конфигурация:

 function pay(amount) {
        var data = {
            token: Ваш токен,
            payment: {
                amount: amount,
                description: 'Описание заказа',
            },
            successCallback: function (payment) {
                console.log(payment) // Данные о платеже
            },
            errorCallback: function (payment) {
                console.log(payment) // Данные о платеже
            }
        }

        var paybox = new PayBox(data);
        paybox.create();
    }
<button onclick="pay(100)">Оплатить</button>

Полная конфигурация:

function pay(amount) {
    var data = {
      token: "Ваш токен",
      payment: {
        order: "1",
        amount: "200",
        currency: "KZT",
        description: "Описание заказа",
        expires_at: "2020-12-12 00:00:00",
        param1: "string",
        param2: "string",
        param3: "string",
        test: 1,  // testing mode
        options: {
          callbacks: {
            result_url: "https://my-domain.com/result",
            check_url: "https://my-domain.com/check"
          },
          custom_params: {},
          user: {
            email: "user@test.com",
            phone: "77777777777",
          }
        }
      },
      successCallback: function (payment) {
          //...
      },
      errorCallback: function (payment) {
          //...
      }
    }

    var paybox = new PayBox(data);
    paybox.create();
  }

Получение статуса платежа. После оплаты покупателем, ваш сайт получает уведомление через коллбэки, которые передаются в параметрах:

successCallback: function (payment) {
      // при успешном платеже
      alert('Заказ номер ' + payment.order + ' успешно оплачен')
  },
  errorCallback: function (payment) {
      // при неуспешном платеже
      alert('Произошла ошибка при попытке оплаты заказа номер ' + payment.order)
  }

Demo

Пример как работает виджет вы можете посмотреть

[newman gif](https://paybox.money/gifs/checkout.gif)

Двухэтапным платежом

Механика двух-этапного платежа заключается в том, что мерчант сначала производит авторизацию(блокирование) средств на карте пользователя, затем производит клиринг(списание) с карты.

В случае, если мерчант не вызвал метод клиринга в течение 3-х дней с момента авторизации, PayBox.Money делает клиринг автоматически

Инициализация платежа

Инициализация платежа

Запрос

curl --location --request POST 'https://api.paybox.money/init_payment.php' \
--form 'pg_order_id=23' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_amount=25' \
--form 'pg_description=test' \
--form 'pg_salt=molbulak' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'init_payment.php;25;test;{{paybox_merchant_id}};23;molbulak;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>4567788</pg_payment_id>
    <pg_redirect_url>https://api.paybox.money/pay.html?customer=498333170d6a895148c57c53ffb18287</pg_redirect_url>
    <pg_redirect_url_type>need data</pg_redirect_url_type>
    <pg_salt>bdwLavL9lg6It91b</pg_salt>
    <pg_sig>709633e91387c56ac6fb7cb33d1e07d8</pg_sig>
</response>

При прямой передаче данных от магазина в PayBox.money мерчант должен посылать данные на init_payment.php.

Можно передавать произвольные дополнительные параметры, имена которых не начинаются на pg_. Все эти параметры будут переданы на pg_check_url и pg_result_url.

Имена дополнительных параметров мерчанта должны быть уникальны.

После получение параметра pg_redirect_url пользователя перенаправляют на платежную страницу где плательщик завершает платеж.

В случае успеха пользователь будет перенаправлен на страницу оплаты.

В случае если мерчантом переданы не все параметры, необходимые для создания платежной транзакции (платежная система, телефон пользователя и параметры, необходимые для выбранной платежной системы), они запрашиваются у пользователя на сайте paybox.money.

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_amount' => 10,
    'pg_salt' => 'some random string',
    'pg_order_id'=> '00102',
    'pg_description' => 'Ticket',
    'pg_result_url' => 'http://site.kz/result'
];

// $request['pg_testing_mode'] = 1; //add this parameter to request for testing payments

//if you pass any of your parameters, which you want to get back after the payment, then add them. For example:
// $request['client_name'] = 'My Name';
// $request['client_address'] = 'Earth Planet';

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'init_payment.php');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/init_payment.php

Поля запроса
Название Описание Тип
pg_order_id
required
Идентификатор платежа в системе мерчанта. Рекомендуется поддерживать уникальность этого поля.
Пример: 00102
string
pg_merchant_id
required
Идентификатор мерчанта в PayBox.money. Выдается при подключении. integer
pg_amount
required
Сумма платежа в валюте pg_currency.
Пример: 10
number
pg_description
required
Описание товара или услуги. Отображается покупателю в процессе платежа.
Пример: Ticket
string
pg_salt
required
Случайная строка
Пример: some random string
string
pg_sig
required
Подпись запроса string
pg_currency Валюта, в которой указана сумма. KZT, USD, EUR. В случае выбора покупателем способа платежа в другой валюте, производится пересчет по курсу ЦБ на день платежа. См. в разделе Справочник валют
Пример: KZT
string
pg_check_url URL для проверки возможности платежа. Вызывается перед платежом, если платежная система предоставляет такую возможность. Если параметр не указан, то берется из настроек мерчанта. Если параметр установлен равным пустой строке, то проверка возможности платежа не производится. string
pg_result_url URL для сообщения о результате платежа. Вызывается после платежа в случае успеха или неудачи. Если параметр не указан, то берется из настроек мерчанта. Если параметр установлен равным пустой строке, то PayBox.money не сообщает мерчанту о результате платежа. string
pg_request_method GET, POST или XML – метод вызова скриптов мерчанта Check URL, Result URL, для передачи информации от платежного гейта.
Пример: POST
string
pg_success_url url, на который отправляется пользователь в случае успешного платежа (только для online систем) string
pg_failure_url url, на который отправляется пользователь в случае неуспешного платежа (только для online систем) string
pg_success_url_method GET – кнопка, которая сабмитится методом GET. POST – кнопка, которая сабмитится методом POST. Если выбран метод GET или POST, то страница с подтверждением оплаты показывается пользователю на сайте paybox.money, и предлагается нажать кнопку, чтобы вернуться на сайт мерчанта.
Пример: GET
string
pg_failure_url_method GET – кнопка, которая сабмитится методом GET. POST – кнопка, которая сабмитится методом POST. Если выбран метод GET или POST, то страница с сообщением о неудавшейся оплате показывается пользователю на сайте paybox.money, и предлагается нажать кнопку, чтобы вернуться на сайт магазина.
Пример: GET
string
pg_state_url URL скрипта на сайте магазина, куда перенаправляется покупатель для ожидания ответа от платежной системы.
Пример: http://site.kz/state
string
pg_state_url_method GET – кнопка, которая сабмитится методом GET.
POST – кнопка, которая сабмитится методом POST.
AUTOGET – 302 редирект. См. Автоматическая передача информации, п.1.
AUTOPOST – форма, которая автоматически сабмитится. См. Автоматическая передача информации, п.2.
Если выбран метод GET или POST, то страница с сообщением о неудавшейся оплате показывается пользователю на сайте paybox.money, и предлагается нажать кнопку, чтобы вернуться на сайт магазина.
Если выбран метод AUTOGET или AUTOPOST, то страница с сообщением о неудавшейся оплате не показывается пользователю, и пользователь сразу передается магазину.
Пример: GET
string
pg_site_url URL сайта мерчанта для показа покупателю ссылки, по которой он может вернуться на сайт мерчанта после создания счета. Применяется для offline ПС (наличные).
Пример: http://site.kz/return
string
pg_payment_system Идентификатор платёжной системы. Этот параметр передается только если выбор платежной системы совершается на сайте мерчанта. Если параметр не указан, то выбор ПС совершается на сайте PayBox.money.
Пример: EPAYWEBKZT
string
pg_lifetime Default: "86400"
Время (в секундах) в течение которого платеж должен быть завершен, в противном случае заказ при проведении платежа PayBox.money откажет платежной системе в проведении. Этот параметр контролирует PayBox,money а также, если платежная система поддерживает такую возможность, и платежной системой. Минимально допустимое значение: 300 секунд (5 минут). Максимально допустимое значение: 604800 секунд (7 суток). В случае выхода за пограничные значения будет присвоено минимальное или максимальное значение, соответственно.
Пример: 86400
integer
pg_user_phone Телефон пользователя (начиная с кода страны), необходим для идентификации покупателя. Если не указан, выбор будет предложен пользователю на сайте платежного гейта.
Пример: 77777777777
string
pg_user_contact_email Контактный адрес электронной почты пользователя. Если указан, на этот адрес будут высылаться уведомления об изменении статуса транзакции.
Пример: mail@customer.kz
string
pg_user_ip IP-адрес клиента. Необходим для разбора спорных ситуаций в случае подозрения на мошенничество. Параметр можно не передавать при передаче информации через браузер пользователя, в этом случае будет записан тот IP, с которого пользователь перешёл на страницу инициализации платежа.
Пример: 127.0.0.1
string
pg_postpone_payment Создание платежа с отложенной оплатой если в этом параметре передано «1». В таком случае покупатель будет перенаправлен на страницу с информацией о том, что ему было выслано письмо со ссылкой на страницу для продолжения проведения платежа. Если этот параметр присутствует в запросе, то должен быть указан также pg_user_contact_email, иначе пользователь будет перенаправлен на уточнение платежных параметров, где он сможет, указать email и попробовать отложить платеж ещё раз.
Пример: 0
string
pg_language Язык платежных страниц на сайте PayBox.money и (если возможно) платежных систем. "en", "ru"
Пример: ru
string
pg_testing_mode Создание платежа в тестовом режиме.
Пример: 1
integer
pg_user_id ID пользователя в системе мерчанта.
Пример: 123
integer
pg_recurring_start Флаг, принимает значение 0 или 1. Подробное описание см. в разделе Рекуррентные платежи. Для использования данного параметра Вам следует обратиться к своему менеджеру.
Пример: 1
integer
pg_recurring_lifetime Время на продолжении которого мерчант рассчитывает использовать профиль рекуррентных платежей. Минимально допустимое значение 1 (1 месяц). Максимально допустимое значение: 156 (13 лет). В случае выхода за пограничные значения будет присвоено минимальное или максимальное значение, соответственно. Подробное описание см. в разделе Рекуррентные платежи. Для использования данного параметра Вам следует обратиться к своему менеджеру.
Пример: 156
integer
pg_receipt_positions[0][count] Количество товара.
Пример: 2
integer
pg_receipt_positions[0][name] Наименование товара
Пример: Коврик для мыши
string
pg_receipt_positions[0][tax_type] Тип налога.
Пример: 3
integer
pg_receipt_positions[0][price] Цена за 1 ед. товара.
Пример: 1000
number
pg_param1 Дополнительный параметр 1
Пример: Дополнительная информация
string
pg_param2 Дополнительный параметр 2
Пример: Дополнительная информация
string
pg_param3 Дополнительный параметр 3
Пример: Дополнительная информация
string
pg_auto_clearing Если 1 клиринг будет происходить сразу, в случае 0 необходимо сделать ручной клиринг. Подробное описание см. в разделе Запрос на клиринг транзакций по банковским картам. Для использования данного параметра Вам следует обратиться к своему менеджеру.
Пример: 1
integer
Параметры ответа
Название Описание Тип
pg_status Показывает результат выполнения запроса string
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money. Служит ключом для всей дальнейшей работы с транзакцией integer
pg_redirect_url URL для перенаправления пользователя. Может быть как на сайте paybox.money, так и на сайте платежной системы string
pg_redirect_url_type Тип страницы, на которую происходит перенаправление. Возможные значения:
need data – диалог с покупателем с целью уточнения параметров: платежной системы, номера телефона, обязательных для данной платежной системы параметров;
payment system – страница сайта платежной системы либо страница с инструкциями оплаты через данную платежную систему. Страница с инструкциями может располагаться как на сайте paybox.money, так и на сайте мерчанта.

В случае получения мерчантом ответа с pg_redirect_url_type=”need data”, мерчант может не перенаправлять покупателя по полученному URL, а уточнить недостающие параметры у себя на сайте. В этом случае после уточнения параметров и повторного запроса на создание платежной транзакции будет создана новая транзакция
string
pg_salt Случайная строка string
pg_sig Подпись запроса string


Запрос на check_url магазина. Проверка возможности совершить платеж.

Пример отрицательного ответа магазина

Запрос

curl --location --request POST '{{check_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=10' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_ps_amount=5' \
--form 'pg_ps_full_amount=5' \
--form 'pg_payment_system=EPAYWEBKZT' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <status>rejected</status>
    <pg_description>Платеж не разрешен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>

Пример положительного ответа магазина

Запрос

curl --location --request POST '{{check_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=10' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_ps_amount=5' \
--form 'pg_ps_full_amount=5' \
--form 'pg_payment_system=EPAYWEBKZT' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <status>ok</status>
    <pg_description>Платеж разрешен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>

Перед тем как принять деньги от покупателя по счету, платежный гейт может вызвать скрипт мерчанта Check URL с помощью метода Request Method.

PayBox.money передает информацию о номере и свойствах заказа и ожидает ответа. Отсутствие ответа за указанное время воспринимается как отказ от платежа.

Вызов скрипта Check URL происходит только в случае, если такая опция была включена в настройках мерчанта.

Ответ на check_url от мерчанта

Если Check URL определен пустым в момент инициализации платежа или не указан в момент инициализации платежа, а в настройках мерчанта установлен пустым, то шаг проверки возможности совершить платеж пропускается и считается, что мерчант согласен принять платеж.

Название Описание Тип
pg_order_id Идентификатор заказа в системе мерчанта
Пример: 123456789
string
pg_payment_id Внутренний идентификатор платежа в системе PayBox.money.
Пример: 12345
integer
pg_amount Сумма выставленного счета (в валюте pg_currency), совпадает с pg_amount в момент инициализации платежа.
Пример: 10
number
pg_currency Валюта выставленного счета, совпадает с pg_currency в момент инициализации платежа.
Пример: KZT
string
pg_ps_currency Валюта, в которой был произведен платеж в платежной системе. Поле может отсутствовать в случае неудачного платежа
Пример: KZT
string
pg_ps_amount Сумма счета (в валюте pg_ps_currency), выставленного в платежной системе.
Пример: 5
integer
pg_ps_full_amount Полная сумма (в валюте pg_ps_currency), которую заплатит покупатель с учетом всех комиссий.
Пример: 5
integer
pg_payment_system Идентификатор платежной системы
Пример: EPAYWEBKZT
string
Параметры мерчанта Все поля, переданные с веб-сайта мерчанта, не имеющие префикса pg_ string
pg_salt Случайная строка
Пример: some random string
string
pg_sig Подпись запроса string


Запрос на result_url магазина. Результат платежа

Пример отрицательного ответа магазина

Запрос

curl --location --request POST '{{result_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_payment_system=EPAYWEBKZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=1' \
--form 'pg_payment_date=2019-01-01 12:00:00' \
--form 'pg_can_reject=1' \
--form 'pg_user_phone=7077777777777' \
--form 'pg_user_contact_email=mail@customer.kz' \
--form 'pg_testing_mode=1' \
--form 'pg_captured=0' \
--form 'pg_card_pan=5483-18XX-XXXX-0293' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <status>rejected</status>
    <pg_description>Платеж отменен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>

Пример положительного ответа магазина

Запрос

curl --location --request POST '{{result_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_currency=KZT' \
--form 'pg_ps_currency=KZT' \
--form 'pg_payment_system=EPAYWEBKZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=1' \
--form 'pg_payment_date=2019-01-01 12:00:00' \
--form 'pg_can_reject=1' \
--form 'pg_user_phone=7077777777777' \
--form 'pg_user_contact_email=mail@customer.kz' \
--form 'pg_testing_mode=1' \
--form 'pg_captured=0' \
--form 'pg_card_pan=5483-18XX-XXXX-0293' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <status>ok</status>
    <pg_description>Заказ оплачен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>

После приема денег от клиента или при невозможности совершить платеж PayBox.money вызывает Result URL мерчанта и передает на него методом Request Method информацию о результате платежа.

При получении данного запроса мерчант должен произвести необходимые действия для передачи товара или услуги покупателю, в случае если платеж был успешным. Если pg_can_reject равно 1 и мерчант не может принять платеж (например, бронь на билеты истекла), он обязан ответить со статусом rejected, и PayBox.money отзовет платеж. В этом случае поле pg_description из ответа мерчанта показывается пользователю как причина отказа.

Если сервер мерчанта недоступен в момент вызова Result URL или ответ от сервера был со статусом 500, PayBox.money будет предпринимать повторные попытки его вызвать каждые полчаса в течение 2 часов, даже если время жизни счета pg_lifetime истечет.

Если первая попытка вызова Result URL оказалась не успешной, то платеж не отменяется, и в последующих вызовах Result URL не позволяет мерчанту отказаться от платежа.

Мерчант должен быть готов к тому, что Result URL будет вызван повторно для одного и того же платежа. Ответы на повторные вызовы должны совпадать с первоначальным ответом, даже если время жизни транзакции pg_lifetime истекло.

Ответ на result_url от мерчанта

Статус rejected может быть возвращен мерчантом только в случае, когда во входящем запросе от гейта был указан параметр pg_can_reject равный 1, в противном случае, вне зависимости от ответа мерчанта, платеж будет считаться совершенным. Если мерчант отказался от платежа (ответил rejected), покупатель перенаправляется на Failure URL, иначе – на Success URL.

Название Описание Тип
pg_order_id Идентификатор заказа в системе мерчанта
Пример: 123456789
string
pg_payment_id Внутренний идентификатор платежа в системе PayBox.money.
Пример: 12345
integer
pg_currency Валюта выставленного счета, совпадает с pg_currency в момент инициализации платежа.
Пример: KZT
string
pg_ps_currency Валюта, в которой был произведен платеж в платежной системе. Поле может отсутствовать в случае неудачного платежа
Пример: KZT
string
pg_payment_system Идентификатор платежной системы
Пример: EPAYWEBKZT
string
pg_description Описание платежа
Пример: Покупка в интернет магазине Site.kz
string
pg_result Результат платежа. 1 – успех, 0 – неудача.
Пример: 1
integer
pg_payment_date Дата и время совершения платежа в формате YYYY-MM-DD HH:MM:SS.
Пример: 2019-01-01 12:00:00
datetime
pg_can_reject 1 – платеж можно откатить назад (например, Банковские карты), 0 – платеж безотзывный.
Пример: 1
integer
pg_user_phone Телефон покупателя (указанный при инициализации платежа)
Пример: 7077777777777
string
pg_user_contact_email Email покупателя (указанный при инициализации платежа)
Пример: mail@customer.kz
string
pg_testing_mode Тестовый режим. 1 - тестовый, 0 - боевой.
Пример: 1
integer
pg_captured Передается только в случае успешной оплаты банковской картой и показывает, был ли произведен клиринг в момент авторизации (что зависит только от настроек мерчанта). Если значение этого поля равно 0, мерчант должен в последующем дать команду на клиринг (см. раздел Запрос на клиринг транзакций по банковским картам) или дождаться когда PayBox.money сделает это сам.
Пример: 0
integer
pg_card_pan Маскированный номер карты (часть цифр номера карты скрыты). Этот параметр передается только в случае успешной оплаты банковской картой
Пример: 5483-18XX-XXXX-0293
string
Параметры мерчанта Все поля, переданные с веб-сайта мерчанта, не имеющие префикса pg_ string
pg_salt Случайная строка
Пример: some random string
string
pg_sig Подпись запроса string


Запрос на клиринг платежа

Магазин может самостоятельно запрашивать клиринг у банка через PayBox.money, если в банке настроено проведение платежей в два шага – авторизация и клиринг. В случае соответствующей настройки системы, после проведения транзакции, транзакция будет авторизована, но не рассчитана. Время максимальной задержки списания равно 5 дней и может регулироваться на стороне PayBox.money от 1 до 5 дней.

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_payment_id' => 12345,
    'pg_clearing_amount'=> 10,
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'do_capture.php');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/do_capture.php

Поля запроса
Название Описание Тип
pg_merchant_id
required
Идентификатор мерчанта в PayBox.money. Выдается при подключении. string
pg_payment_id
required
Внутренний идентификатор платежа в системе PayBox.money.
Пример: 12345
integer
pg_clearing_amount
required
Сумма клиринга. Если не указать то возврат будет полной суммы.
Пример: 10
number
pg_salt
required
Случайная строка
Пример: some random string
string
pg_sig
required
Подпись запроса string
Параметры ответа
Название Описание Тип
pg_status Показывает результат выполнения запроса. ok, если запрос принят на обработку. По результату будет вызван Capture URL магазина.
error в любом другом случае.
string
pg_error_description Описание ошибки в случае pg_status равно error string
pg_salt Случайная строка string
pg_sig Подпись запроса string


Получение статуса платежа

Partial - Получение статуса платежа

Запрос

curl --location --request POST 'https://api.paybox.money/get_status.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_payment_id=4567617' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status.php;{{paybox_merchant_id}};4567617;00102;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>4567617</pg_payment_id>
    <pg_transaction_status>partial</pg_transaction_status>
    <pg_can_reject>0</pg_can_reject>
    <pg_testing_mode>1</pg_testing_mode>
    <pg_captured>0</pg_captured>
    <pg_create_date>2020-05-21 18:44:21</pg_create_date>
    <pg_salt>u1aHmP4QyTxUqzXz</pg_salt>
    <pg_sig>574a9d2e4783cb3d5ea443e1cc4f9434</pg_sig>
</response>

Ok - Получение статуса платежа

Запрос

curl --location --request POST 'https://api.paybox.money/get_status.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_payment_id=4567775' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status.php;{{paybox_merchant_id}};4567775;00102;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>4567775</pg_payment_id>
    <pg_transaction_status>ok</pg_transaction_status>
    <pg_can_reject>1</pg_can_reject>
    <pg_testing_mode>1</pg_testing_mode>
    <pg_captured>0</pg_captured>
    <pg_card_pan>5483-18XX-XXXX-0293</pg_card_pan>
    <pg_card_id>205</pg_card_id>
    <pg_card_hash>e5b78033320bb1de831439cbc9ec543a</pg_card_hash>
    <pg_create_date>2020-06-01 16:58:40</pg_create_date>
    <pg_salt>OX1MwChiToQFR1Fy</pg_salt>
    <pg_sig>8fec63c0e02d3d8f98d9eff2d4f6c226</pg_sig>
</response>

Мерчант может запрашивать PayBox.money о статусе любого платежа, инициированного мерчантом. Это может быть полезно, например, в случае если вызов Result URL не был получен мерчантом из-за временного сбоя связи, а покупатель уже был передан на Success URL, однако статус транзакции мерчанту еще не известен.

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_payment_id' => 12345,
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'get_status.php');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/get_status.php

Поля запроса
Название Описание Тип
pg_merchant_id
required
Идентификатор мерчанта в PayBox.money. Выдается при подключении. string
pg_payment_id
required
Внутренний идентификатор платежа в системе PayBox.money
если отправлена вместе с полем pg_order_id, то поле pg_order_id будет проигнорировано.
Пример: 12345
integer
pg_order_id Идентификатор платежа в системе мерчанта. Будьте внимательны, при запросе по order_id мерчант должен самостоятельно следить за уникальностью данного параметра иначе будет выдана информация для последнего платежа с данным order_id для данного мерчанта
Пример: 00102
string
pg_salt
required
Случайная строка
Пример: some random string
string
pg_sig
required
Подпись запроса string
Параметры ответа
Название Описание Тип
pg_status Показывает результат выполнения запроса string
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money. Служит ключом для всей дальнейшей работы с транзакцией integer
pg_transaction_status Статус платежа string
pg_can_reject 0 или 1 – может ли платеж быть отменен. Значение 1 возможно только если статус платежа равен ok и платежная система предоставляет возможность отзыва платежа. В этом случае мерчант может вызвать revoke.php. integer
pg_testing_mode Enum:0 1
0 - платеж в боевом режиме 1 - платеж в тестовом режиме
integer
pg_captured Enum:0 1
Передается только в случае успешной оплаты банковской картой и показывает, был ли произведен клиринг в момент авторизации (что зависит только от настроек мерчанта). Если значение этого поля равно 0, мерчант должен в последующем дать команду на клиринг или дождаться когда PayBox.money сделает это сам.
integer
pg_card_pan Маскированный номер карты (часть цифр номера карты скрыты). Этот параметр передается только в случае успешной оплаты банковской картой. string
pg_card_id ID карты integer
pg_card_hash Хеш маскированной PAN карты string
pg_create_date Дата и время создания платежной транзакции datetime
pg_salt Случайная строка string
pg_sig Подпись запроса string


Общие запросы

Получение статуса платежа

Получение статуса платежа

Запрос

curl --location --request POST 'https://api.paybox.money/get_status.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_payment_id=12345' \
--form 'pg_order_id=00102' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status.php;{{paybox_merchant_id}};00102;12345;some random string;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>4567617</pg_payment_id>
    <pg_transaction_status>partial</pg_transaction_status>
    <pg_can_reject>0</pg_can_reject>
    <pg_testing_mode>1</pg_testing_mode>
    <pg_captured>0</pg_captured>
    <pg_create_date>2020-05-21 18:44:21</pg_create_date>
    <pg_salt>u1aHmP4QyTxUqzXz</pg_salt>
    <pg_sig>574a9d2e4783cb3d5ea443e1cc4f9434</pg_sig>
</response>

Мерчант может запрашивать PayBox.money о статусе любого платежа, инициированного мерчантом. Это может быть полезно, например, в случае если вызов Result URL не был получен мерчантом из-за временного сбоя связи, а покупатель уже был передан на Success URL, однако статус транзакции мерчанту еще не известен.

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_payment_id' => 12345,
    'pg_order_id' => 00102,
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'get_status.php');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/get_status.php

Поля запроса
Название Описание Тип
pg_merchant_id
required
Идентификатор мерчанта в PayBox.money. Выдается при подключении. integer
pg_payment_id Внутренний идентификатор платежа в системе PayBox.money
если отправлена вместе с полем pg_order_id, то поле pg_order_id будет проигнорировано.
Пример: 12345
integer
pg_order_id
required
Идентификатор платежа в системе мерчанта. Будьте внимательны, при запросе по order_id мерчант должен самостоятельно следить за уникальностью данного параметра иначе будет выдана информация для последнего платежа с данным order_id для данного мерчанта.
Пример: 00102
string
pg_salt
required
Случайная строка
Пример: some random string
string
pg_sig
required
Подпись запроса string
Параметры ответа
Название Описание Тип
pg_status Показывает результат выполнения запроса string
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money. Служит ключом для всей дальнейшей работы с транзакцией integer
pg_transaction_status Статус платежа string
pg_can_reject 0 или 1 – может ли платеж быть отменен. Значение 1 возможно только если статус платежа равен ok и платежная система предоставляет возможность отзыва платежа. В этом случае мерчант может вызвать revoke.php. integer
pg_testing_mode Enum:0 1
0 - платеж в боевом режиме 1 - платеж в тестовом режиме
integer
pg_captured Enum:0 1
Передается только в случае успешной оплаты банковской картой и показывает, был ли произведен клиринг в момент авторизации (что зависит только от настроек мерчанта). Если значение этого поля равно 0, магазин должен в последующем дать команду на клиринг или дождаться когда PayBox.money сделает это сам.
integer
pg_card_pan Маскированный номер карты (часть цифр номера карты скрыты). Этот параметр передается только в случае успешной оплаты банковской картой. string
pg_card_id ID карты integer
pg_card_hash Хеш маскированной PAN карты string
pg_create_date Дата и время создания платежной транзакции datetime
pg_salt Случайная строка string
pg_sig Подпись запроса string


Отмена платежа до оплаты (cancel)

Мерчант может отменить выставленный, но ещё не оплаченный счёт. После совершения этой операции PayBox.money будет отказывать в проведении платежа на этапе проверки возможности проведения платежа (если ПС поддерживает этот запрос). Кроме того, производится аннулирование счёта в тех ПС, которые поддерживают эту операцию. Таким образом, отмена счёта не гарантирует невозможность его оплаты во всех ПС.

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_payment_id' => 12345,
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'cancel.php');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/cancel.php

Поля запроса
Название Описание Тип
pg_merchant_id
required
Идентификатор мерчанта в системе PayBox.money string
pg_payment_id
required
Внутренний идентификатор платежа в системе PayBox.money
Пример: 12345
integer
pg_salt
required
Случайная строка
Пример: some random string
string
pg_sig
required
Подпись запроса string
Параметры ответа
Название Описание Тип
pg_status Показывает результат выполнения запроса string
pg_error_code Код ошибки integer
pg_error_description Описание ошибки в случае pg_status равно error string
pg_salt Случайная строка string
pg_sig Подпись запроса string


Отмена платежа после оплаты (revoke)

Мерчант может отменить успешно завершившийся платеж, если платежная система это позволяет (например, Банковские карты). В этом случае деньги возвращаются покупателю. Вернуть можно как полную сумму платежа, так и часть суммы. Можно делать несколько частичных возвратов до тех пор, пока общая сумма возвратов не достигнет суммы первоначального платежа. Отозвать платеж можно как из личного кабинета мерчанта, так и в автоматическом режиме путем вызова скрипта.

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_payment_id' => 12345,
    'pg_refund_amount'=> 50,
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'revoke.php');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/revoke.php

Поля запроса
Название Описание Тип
pg_merchant_id
required
Идентификатор мерчанта в PayBox.money. Выдается при подключении. string
pg_payment_id
required
Внутренний идентификатор платежа в системе PayBox.money.
Пример: 12345
integer
pg_refund_amount Сумма возврата. Если параметр не передан или передан 0, то возвращается вся сумма.
Пример: 50
number
pg_salt
required
Случайная строка
Пример: some random string
string
pg_sig
required
Подпись запроса string
Параметры ответа
Название Описание Тип
pg_status Показывает результат выполнения запроса string
pg_error_code Код ошибки integer
pg_error_description Описание ошибки в случае pg_status равно error string
pg_salt Случайная строка string
pg_sig Подпись запроса string


Выплата

В этом разделе описана механика, когда PayBox.Money выплачивает деньги на банковскую карту пользователя

Внимание!

Выплаты будут доступны для магазина только после разрешения личного менеджера и применения соответствующих настроек на стороне PayBox.Money

Выплаты не могут быть тестовыми. Тестирование производится только выплатой определенной суммы на боевую карту

На несохранненную карту

Данный метод генерирует страницу, на которой получатель вводит pan своей карты. Далее PayBox.Money производит выплату на эту карту

Выплата на несохранненную карту

Для использования данных запросов Вам следует обратиться к своему менеджеру.

Для выплаты в качестве secret_key используется

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_amount' => 10,
    'pg_order_id'=> 1234,
    'pg_description' => 'Описание платежа',
    'pg_post_link' => 'http://site.kz/post',
    'pg_back_link' => 'http://site.kz/back',
    'pg_order_time_limit' => '2020-12-31 12:00:00',
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'reg2nonreg');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);

В случае успешного ответа, пользователя необходимо перенаправить на URL, указанный в параметре pg_redirect_url. Отобразится страница для ввода данных карты, на которой нужно совершить платеж

URL запроса

POST https://api.paybox.money/api/reg2nonreg

Headers
Content-Type Value
Content-Type application/x-www-form-urlencoded
Поля запроса
Название Описание Тип
pg_merchant_id
required
Merchant ID в системе PayBox.money. integer
pg_order_id
required
ID заказа в системе мерчанта. Рекомендуется уникальное, монотонно возрастающее значение.
Пример: 1234
integer
pg_amount
required
Сумма перевода.
Пример: 10
number
pg_description
required
Описание платежа
Пример: Описание платежа
string
pg_back_link
required
URL, на который перенаправляется пользователь, в случае успешной оплаты
Пример: http://site.kz/back
string
pg_post_link
required
Url на который отправляется ответ о статусе платежа string
pg_order_time_limit
required
Лимит времени на проведение платежа.
Пример: 2020-12-31 12:00:00
datetime
pg_salt
required
Случайная строка, состоящая из произвольных цифр и латинских букв
Пример: some random string
string
pg_sig
required
Подпись запроса string
pg_user_id ID пользователя в системе мерчанта
Пример: 1
string
pg_user_email Email пользователя в системе мерчанта
Пример: mail@customer.kz
string
Параметры ответа
Название Описание Тип
pg_status Показывает результат выполнения запроса string
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money. Служит ключом для всей дальнейшей работы с транзакцией integer
pg_merchant_id Идентификатор мерчанта в системе PayBox.money integer
pg_redirect_url URL для на которую необходим редирект string
pg_salt Случайная строка string
pg_sig Подпись запроса string


Post link запрос для мерчанта

Ответ на result_url от мерчанта

<?xml version="1.0" encoding="UTF-8"?>
<pg_status>ok</pg_status>  

В случае правильного ввода платеж отменяется и заблокированная сумма моментально возвращается на карточку пользователя, а сама карта считается успешно добавленной в систему.

В случае превышения попыток ввода, либо по истечению выделенного времени платеж отменяется и заблокированная сумма моментально возвращается на карточку пользователя.

В случае успешного добавления карты, в параметре pg_xml будет XML следующего вида:

При этом pg_type будет равен confirm.

Сервер мерчанта должен ответить статусом 200

URL запроса

POST {{post_link}}

Headers
Content-Type Value
Content-Type application/x-www-form-urlencoded
Поля запроса
Название Описание Тип
pg_type Тип транзакции string
pg_payment_id ID транзакции в системе PayBox.money. integer
pg_order_id ID заказа в системе мерчанта string
pg_card_3ds Признак наличия 3ds на карте. integer
pg_card_hash Маскированный PAN карты string
pg_card_id ID сохраненной карты. integer
pg_user_id ID пользователя в системе мерчанта. integer
pg_status Статус операции. Enum:ok, error string
pg_card_month Месяц срока действия карты string
pg_card_year Год срока действия карты string
pg_salt Случайная строка, состоящая из произвольных цифр и латинских букв.
Пример: some random string
string
pg_sig Подпись запроса string


На сохранненную карту

Для работы этого метода мерчант должен предварительно сохранить карту пользователя(см. раздел "Сохранение карт").

После мерчант этим методом производит выплату на эту карту

Выплата на сохранненную карту

Для использования данных запросов Вам следует обратиться к своему менеджеру.

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_amount' => 10,
    'pg_order_id'=> 1234,
    'pg_user_id' => 1234,
    'pg_card_id_to' => 1234,
    'pg_description' => 'Описание платежа',
    'pg_post_link' => 'http://site.kz/post',
    'pg_back_link' => 'http://site.kz/back',
    'pg_order_time_limit' => '2020-12-31 12:00:00',
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'reg2reg');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/api/reg2reg

Поля запроса
Название Описание Тип
pg_amount
required
Сумма перевода.
Пример: 10
number
pg_merchant_id
required
Merchant ID в системе PayBox.money integer
pg_order_id
required
ID заказа в системе мерчанта. Рекомендуется уникальное, монотонно возрастающее значение.
Пример: 1234
integer
pg_user_id
required
ID пользователя в системе .
Пример: 1234
integer
pg_card_id_to
required
ID карты на которую нужно перевести деньги (возвращается при регистрации карты).
Пример: 1234
integer
pg_description
required
Описание платежа
Пример: Описание платежа
string
pg_post_link
required
Url на который отправляется ответ о статусе платежа
Пример: http://site.kz/post
string
pg_back_link
required
URL, на который перенаправляется пользователь, в случае успешной оплаты
Пример: http://site.kz/back
string
pg_order_time_limit
required
Лимит времени на проведение платежа.
Пример: 2020-12-31 12:00:00
datetime
pg_salt
required
Случайная строка, состоящая из произвольных цифр и латинских букв
Пример: some random string
string
pg_sig
required
Подпись запроса string
Параметры ответа
Название Описание Тип
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money. Служит ключом для всей дальнейшей работы с транзакцией integer
pg_merchant_id Идентификатор мерчанта в системе PayBox.money. integer
pg_status Статус платежа string
pg_order_id Идентификатор заказа в системе мерчанта string
pg_balance Баланс мерчанта в системе PayBox.money number
pg_card_hash Карта, на которую был совершен платеж string
pg_card_id Идентификатор карты получателя integer
pg_payment_amount Сумма платежа number
pg_payment_date Дата и время проведения платежа datetime
pg_salt Случайная строка, состоящая из произвольных цифр и латинских букв string
pg_sig Подпись запроса string


Post link запрос для мерчанта

Ответ на result_url от мерчанта

<?xml version="1.0" encoding="UTF-8"?>
<pg_status>ok</pg_status>  

В случае правильного ввода платеж отменяется и заблокированная сумма моментально возвращается на карточку пользователя, а сама карта считается успешно добавленной в систему.

В случае превышения попыток ввода, либо по истечению выделенного времени платеж отменяется и заблокированная сумма моментально возвращается на карточку пользователя.

В случае успешного добавления карты, в параметре pg_xml будет XML следующего вида:

При этом pg_type будет равен confirm.

Сервер мерчанта должен ответить статусом 200

URL запроса

POST {{post_link}}

Headers
Content-Type Value
Content-Type application/x-www-form-urlencoded
Поля запроса
Название Описание Тип
pg_type Тип транзакции string
pg_payment_id ID транзакции в системе PayBox.money. integer
pg_order_id ID заказа в системе мерчанта string
pg_card_3ds Признак наличия 3ds на карте. integer
pg_card_hash Маскированный PAN карты string
pg_card_id ID сохраненной карты. integer
pg_user_id ID пользователя в системе мерчанта. integer
pg_status Статус операции. Enum:ok, error string
pg_card_month Месяц срока действия карты string
pg_card_year Год срока действия карты string
pg_salt Случайная строка, состоящая из произвольных цифр и латинских букв.
Пример: some random string
string
pg_sig Подпись запроса string


P2P переводы

Для работы с методами P2P требуется PCI DCC сертификат

P2P перевод

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_order_id' => 1234,
    'pg_amount' => 100,
    'pg_user_id' => 12341,
    'pg_description' => 'Описание платежа',
    'pg_pan' => 4405645000006150,
    'pg_cvc' => 653,
    'pg_year' => 25,
    'pg_month' => 09,
    'pg_payment_to' => 4405645000006150,
    'pg_from_name' => 'Testov test',
    'pg_post_link' => 'http://site.kz/post',
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'p2p');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/api/p2p

Поля запроса
Название Описание Тип
pg_merchant_id
required
Merchant ID в системе PayBox.money. integer
pg_order_id
required
ID заказа в системе мерчанта. Рекомендуется уникальное, монотонно возрастающее значение.
Пример: 1234
integer
pg_amount
required
Сумма перевода.
Пример: 100
number
pg_user_id
required
ID пользователя в системе мерчанта.
Пример: 12341
integer
pg_description
required
Описание товара или услуги. Отображается покупателю в процессе платежа. Передается в кодировке pg_encoding.
Пример: Описание платежа
string
pg_pan
required
Номер карты отправителя.
Пример: 4405645000006150
integer
pg_cvc
required
Трёхзначный код проверки подлинности карты.
Пример: 653
integer
pg_year
required
Срок действия карты (год) yy
Пример: 25
string
pg_month
required
Срок действия карты (месяц) mm
Пример: 09
string
pg_payment_to
required
Номер карты получателя.
Пример: 4405645000006150
integer
pg_from_name
required
Имя отправителя (на карте)
Пример: Testov test
string
pg_post_link
required
Url на который отправляется ответ о статусе платежа
Пример: http://site.kz/post
string
pg_salt
required
Случайная строка, состоящая из произвольных цифр и латинских букв
Пример: some random string
string
pg_sig
required
Подпись запроса string
Параметры ответа
Название Описание Тип
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money. Служит ключом для всей дальнейшей работы с транзакцией integer
pg_merchant_id Идентификатор мерчанта в системе PayBox.money. integer
pg_status Статус платежа string
pg_order_id Идентификатор заказа в системе мерчанта string
pg_approval_code AC операции string
pg_reference RRN операции string
pg_payment_amount Сумма платежа number
pg_payment_date Дата и время проведения платежа datetime
pg_salt Случайная строка, состоящая из произвольных цифр и латинских букв string
pg_sig Подпись запроса string


P2P перевод 3ds

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_payment_id' => 1234,
    'pg_md' => '',
    'pg_pares' => '',
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'p2p_secure');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/api/p2p_secure

Поля запроса
Название Описание Тип
pg_merchant_id
required
Merchant ID в системе PayBox.money. integer
pg_payment_id
required
ID транзакции в системе PayBox.money
Пример: 1234
integer
pg_md
required
Параметр из ответа на предыдущий запрос string
pg_pares
required
Параметр из ответа на предыдущий запрос string
pg_salt
required
Случайная строка, состоящая из произвольных цифр и латинских букв
Пример: some random string
string
pg_sig
required
Подпись запроса string
Параметры ответа
Название Описание Тип
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money. Служит ключом для всей дальнейшей работы с транзакцией integer
pg_merchant_id Идентификатор мерчанта в системе PayBox.money integer
pg_status Статус платежа string
pg_order_id Идентификатор заказа в системе мерчанта string
pg_approval_code AC операции string
pg_reference RRN операции string
pg_payment_amount Сумма платежа number
pg_payment_date Дата и время проведения платежа datetime
pg_salt Случайная строка, состоящая из произвольных цифр и латинских букв string
pg_sig Подпись запроса string


P2P перевод с баланса

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_order_id' => 1234,
    'pg_amount' => 100,
    'pg_payment_to' => 4405645000006150,
    'pg_description' => 'Описание платежа',
    'pg_post_link' => 'http://site.kz/post',
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'p2p2nonreg');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/api/p2p2nonreg

Поля запроса
Название Описание Тип
pg_merchant_id
required
Merchant ID в системе PayBox.money string
pg_order_id
required
ID заказа в системе мерчанта. Рекомендуется уникальное, монотонно возрастающее значение
Пример: 1234
string
pg_amount
required
Сумма перевода.
Пример: 100
number
pg_payment_to
required
Номер карты получателя.
Пример: 4405645000006150
integer
pg_description
required
Описание платежа
Пример: Описание платежа
string
pg_post_link
required
Url на который отправляется ответ о статусе платежа
Пример: http://site.kz/post
string
pg_salt
required
Случайная строка, состоящая из произвольных цифр и латинских букв
Пример: some random string
string
pg_sig
required
Подпись запроса string
pg_user_id ID пользователя в системе мерчанта
Пример: 1234
string
Параметры ответа
Название Описание Тип
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money. Служит ключом для всей дальнейшей работы с транзакцией integer
pg_merchant_id Идентификатор мерчанта в системе PayBox.money. integer
pg_order_id Идентификатор заказа в системе мерчанта string
pg_status Статус платежа string
pg_balance Баланс мерчанта в системе Paybox number
pg_payment_amount Сумма платежа number
pg_payment_date Дата и время проведения платежа datetime
pg_salt Случайная строка, состоящая из произвольных цифр и латинских букв string
pg_sig Подпись запроса string


P2P перевод с баланса (на зарубежные карты)

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_order_id' => 1234,
    'pg_amount' => 100,
    'pg_payment_to' => 4405645000006150,
    'pg_description' => 'Описание платежа',
    'pg_post_link' => 'http://site.kz/post',
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'p2p2nonreg_foreign');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/api/p2p2nonreg_foreign

Поля запроса
Название Описание Тип
pg_merchant_id
required
Merchant ID в системе PayBox.money. integer
pg_order_id
required
ID заказа в системе мерчанта. Рекомендуется уникальное, монотонно возрастающее значение
Пример: 1234
string
pg_amount
required
Сумма перевода.
Пример: 100
number
pg_payment_to
required
Номер карты получателя.
Пример: 4405645000006150
integer
pg_description
required
Описание платежа
Пример: Описание заказа
string
pg_post_link
required
Url на который отправляется ответ о статусе платежа
Пример: http://site.kz/post
string
pg_salt
required
Случайная строка, состоящая из произвольных цифр и латинских букв
Пример: some random string
string
pg_sig
required
Подпись запроса string
pg_user_id ID пользователя в системе мерчанта.
Пример: 1234
integer
pg_reg_country Страна проживания получателя
Пример: Russia
string
pg_reg_city Город проживания получателя
Пример: Moscow
string
pg_reg_address Адресс проживания получателя
Пример: address
string
pg_first_name Имя получателя
Пример: Test
string
pg_last_name Фамилия получателя
Пример: Testov
string
pg_doc_number Номер документа получателя
Пример: 1234
string
Параметры ответа
Название Описание Тип
pg_status Показывает результат выполнения запроса string
pg_error_code Код ошибки integer
pg_error_description Описание ошибки в случае pg_status равно error string
pg_salt Случайная строка string
pg_sig Подпись запроса string


На банкомат

Данный метод делает специальный запрос, после которого, пользователю на телефонный номер отправятся два смс с паролями.

Для получения наличных в банкомате, пользователю необходимо ввести указанные пароли, а также сумму, которую он намеревается вывести.

У пользователя есть 24 часа, чтобы снять наличные в банкомате, иначе операция завершиться с ошибкой, после чего сумма, указанная для снятия, снова вернется на баланс мерчанта в системе PayBox.Money.

Метод не содержит никаких коллбэков. Мерчант должен сам опрашивать PayBox.Money о статусе операции. Ниже будет описана рекомендуемая механика платежа.

Первая проверка статуса операции (снял ли пользователь сумму с банкомата или нет) произойдет три часа спустя, после инициации платежа. Если сумма с банкомата не снята, вторая попытка произойдет еще три часа спустя, этот повторяющийся процесс будет происходит в течении 24 часов после инициации платежа (всего PayBox будет запрашивать статус 8 раз).

Исходя из вышенаписанного, мерчант не должен проводить опрос статуса не чаще одного раза в три часа.

Запрос на формирование платежа

Пример успешного запроса

Запрос

curl --location --request POST 'https://api.paybox.money/api/cbc/check' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_phone=7073175200' \
--form 'pg_amount=2000' \
--form 'pg_order_id=00102' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'check;2000;{{paybox_merchant_id}};00102;7073175200;some random string;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="UTF- 8"?>
<response>
    <pg_payment_id>765432</pg_payment_id>
    <pg_merchant_id>500001</pg_merchant_id>
    <pg_order_id>1234</pg_order_id>
    <pg_status>ok</pg_status>
    <pg_salt>yNSdZrM1pIA4NjRU5Csdm0L3NC92PZpo</pg_salt>
    <pg_sig>6304300d2a1d5d35cfbdc37ae8490c81</pg_sig>
</response>

Пример неуспешного запроса

Запрос

curl --location --request POST 'https://api.paybox.money/api/cbc/check' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_phone=7073175200' \
--form 'pg_amount=2000' \
--form 'pg_order_id=00102' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'check;2000;{{paybox_merchant_id}};00102;7073175200;some random string;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <pg_status>error</pg_status>
    <pg_error_code>101</pg_error_code>
    <pg_error_description>Empty merchant</pg_error_description>
    <pg_salt>yNSdZrM1pIA4NjRU5Csdm0L3NC92PZpo</pg_salt>
    <pg_sig>6304300d2a1d5d35cfbdc37ae8490c81</pg_sig>
</response>

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id' => $pg_merchant_id,
    'pg_phone' => '7073175200',
    'pg_amount' => '2000',
    'pg_order_id' => '00102',
    'pg_salt' => 'some random string'
];


//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'check');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/api/cbc/check

Поля запроса
Название Описание Тип
pg_merchant_id
required
Merchant ID в системе PayBox.money. integer
pg_phone Телефон пользователя для получения кода (только номера Казахстанских операторов сотовой связи), значение без кода страны.
Пример: 7073175200
integer
pg_amount
required
Сумма выплаты.
Должна быть суммой кратной 2000KZT, если сумма меньше или равно 4000KZT, и кратной 1000 KZT, если сумма
больше 4000KZT
number
Пример: 2000
pg_order_id
required
ID заказа в системе мерчанта
Пример: 00102
string
pg_salt
required
Случайная строка, состоящая из произвольных цифр и латинских букв
Пример: some random string
string
pg_sig
required
Подпись запроса string
Параметры ответа
Название Описание Тип
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox. Служит ключом для всей дальнейшей работы с транзакцией integer
pg_merchant_id Идентификатор мерчанта в системе PayBox integer
pg_order_id Идентификатор заказа в системе мерчанта string
pg_status Статус транзакции string
pg_error_code Показывает код ошибки в случае ошибки string
pg_error_description Показывает описание ошибки в случае ошибки string
pg_salt Случайная строка, состоящая из произвольных цифр и латинских букв string
pg_sig Подпись запроса string


Запрос на вывод средств

Пример неуспешного запроса

Запрос

curl --location --request POST 'https://api.paybox.money/api/cbc/exec' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_payment_id=486456456' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'exec;{{paybox_merchant_id}};486456456;some random string;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="UTF-8"?>
<response>
<pg_status>error</pg_status>
<pg_error_code>101</pg_error_code>
<pg_error_description>Empty merchant</pg_error_description>
<pg_salt>yNSdZrM1pIA4NjRU5Csdm0L3NC92PZpo</pg_salt>
<pg_sig>6304300d2a1d5d35cfbdc37ae8490c81</pg_sig>
</response>

Пример успешного запроса

Запрос

curl --location --request POST 'https://api.paybox.money/api/cbc/exec' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_payment_id=486456456' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'exec;{{paybox_merchant_id}};486456456;some random string;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="UTF- 8"?>
<response>
    <pg_payment_id>765432</pg_payment_id>
    <pg_merchant_id>500001</pg_merchant_id>
    <pg_status>ok</pg_status>
    <pg_salt>yNSdZrM1pIA4NjRU5Csdm0L3NC92PZpo</pg_salt>
    <pg_sig>6304300d2a1d5d35cfbdc37ae8490c81</pg_sig>
</response>

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id' => $pg_merchant_id,
    'pg_phone' => '7073175200',
    'pg_amount' => '2000',
    'pg_order_id' => '00102',
    'pg_salt' => 'some random string'
];


//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'exec');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/api/cbc/exec

Поля запроса
Название Описание Тип
pg_merchant_id
required
Merchant ID в системе PayBox.money. integer
pg_payment_id ID транзакции в системе PayBox.money.
Пример: 486456456
integer
pg_salt
required
Случайная строка, состоящая из произвольных цифр и латинских букв
Пример: some random string
string
pg_sig
required
Подпись запроса string
Параметры ответа
Название Описание Тип
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox. Служит ключом для всей дальнейшей работы с транзакцией integer
pg_merchant_id Идентификатор мерчанта в системе PayBox integer
pg_status Статус транзакции string
pg_error_code Показывает код ошибки в случае ошибки string
pg_error_description Показывает описание ошибки в случае ошибки string
pg_salt Случайная строка, состоящая из произвольных цифр и латинских букв string
pg_sig Подпись запроса string


Запрос на статуса по операции

Пример успешного запроса

Запрос

curl --location --request POST 'https://api.paybox.money/api/cbc/status' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_payment_id=486456456' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'status;{{paybox_merchant_id}};486456456;some random string;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="UTF- 8"?> <response>
<pg_payment_id>765432</pg_payment_id>
<pg_merchant_id>500001</pg_merchant_id>
<pg_order_id>1234</pg_order_id>
<pg_status>success</pg_status>
<pg_salt>yNSdZrM1pIA4NjRU5Csdm0L3NC92PZpo</pg_salt>
<pg_sig>6304300d2a1d5d35cfbdc37ae8490c81</pg_sig>
</response>

Пример неуспешного запроса

Запрос

curl --location --request POST 'https://api.paybox.money/api/cbc/status' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_payment_id=486456456' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'status;{{paybox_merchant_id}};486456456;some random string;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="UTF-8"?>
<response>
<pg_status>error</pg_status>
<pg_error_code>75</pg_error_code>
 <pg_error_description> Истекло время исполнения перевода, получатель не снял деньги</pg_error_description>
 <pg_salt>yNSdZrM1pIA4NjRU5Csdm0L3NC92PZpo</pg_salt>
 <pg_sig>6304300d2a1d5d35cfbdc37ae8490c81</pg_sig>
</response>

Пример неопределенного запроса

Запрос

curl --location --request POST 'https://api.paybox.money/api/cbc/status' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_payment_id=486456456' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'status;{{paybox_merchant_id}};486456456;some random string;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="UTF- 8"?> <response>
<pg_payment_id>765432</pg_payment_id>
<pg_merchant_id>500001</pg_merchant_id>
<pg_order_id>1234</pg_order_id>
<pg_status>process</pg_status>
<pg_salt>yNSdZrM1pIA4NjRU5Csdm0L3NC92PZpo</pg_salt>
<pg_sig>6304300d2a1d5d35cfbdc37ae8490c81</pg_sig>
</response>

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id' => $pg_merchant_id,
    'pg_phone' => '7073175200',
    'pg_amount' => '2000',
    'pg_order_id' => '00102',
    'pg_salt' => 'some random string'
];


//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'exec');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/api/cbc/status

Поля запроса
Название Описание Тип
pg_merchant_id
required
Merchant ID в системе PayBox.money. integer
pg_payment_id ID транзакции в системе PayBox.money.
Пример: 486456456
integer
pg_salt
required
Случайная строка, состоящая из произвольных цифр и латинских букв
Пример: some random string
string
pg_sig
required
Подпись запроса string
Параметры ответа
Название Описание Тип
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox. Служит ключом для всей дальнейшей работы с транзакцией integer
pg_merchant_id Идентификатор мерчанта в системе PayBox integer
pg_status Статус транзакции (process, success, error string
pg_error_code Показывает код ошибки в случае ошибки string
pg_error_description Показывает описание ошибки в случае ошибки string
pg_salt Случайная строка, состоящая из произвольных цифр и латинских букв string
pg_sig Подпись запроса string


Сохранение карт

Базовая механика сохранения карт. Далее сохраненные карты можно использовать как для оплат, так и для выплат

Добавление карты

Добавление карты

Запрос

curl --location --request POST 'https://api.paybox.money/v1/merchant/{{paybox_merchant_id}}/cardstorage/add' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_user_id=1234' \
--form 'pg_post_link={{post_link}}' \
--form 'pg_back_link=http://site.kz/back' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'add;http://site.kz/back;{{paybox_merchant_id}};{{post_link}};some random string;1234;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_payment_id>12345</pg_payment_id>
    <pg_merchant_id>1234</pg_merchant_id>
    <pg_order_id/>
    <pg_redirect_url>https://api.paybox.money/v1/merchant/1234/cardstorage/view?pg_payment_id=ee4f2b59ad667949a1143353543</pg_redirect_url>
    <pg_status>ok</pg_status>
    <pg_type>init</pg_type>
    <pg_salt>4vXEfz6S</pg_salt>
    <pg_sig>3f3bb687c0d4b8c8331eb797e1d20a75</pg_sig>
</response>

[newman gif](/flow/cardsave/add.svg)

Далее необходимо открыть iframe на странице оплаты (URL iframe pg_redirect_url из запроса, после чего пользователю откроется интерфейс для ввода следующих карточных данных:

Если на карте есть 3DSecure, произойдет перенаправление на страницу банка эмитента карты, где пользователю будет предложено ввести 3ds пароль. В случае правильного ввода пароля происходят три вещи: а) сумма платежа (от 1 до 100) блокируется на карте пользователя; б) платеж отменяется и указанная сумма моментально возвращается на карточку пользователя; в) карта добавляется в систему.

Если 3DSecure нет, деньги блокируются на карте, после чего пользователю дается 20 минут или 3 попытки для ввода следующей информации о платеже:

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_user_id' => 1234,
    'pg_post_link' => 'http://site.kz/post',
    'pg_back_link' => 'http://site.kz/back',
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'add');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/v1/merchant/{{paybox_merchant_id}}/cardstorage/add

Headers
Content-Type Value
Content-Type application/x-www-form-urlencoded
Поля запроса
Название Описание Тип
pg_merchant_id
required
Идентификатор мерчанта в системе PayBox.money. integer
pg_user_id
required
ID пользователя в системе мерчанта.
Пример: 1234
integer
pg_post_link
required
URL для сообщения о результате. string
pg_back_link
required
URL для перенаправления пользователя после добавления карты.
Пример: http://site.kz/back
string
pg_salt
required
Случайная строка, состоящая из произвольных цифр и латинских букв.
Пример: some random string
string
pg_sig
required
Подпись запроса string
pg_order_id ID заказа в системе мерчанта, уникальное значение
Пример: 12345
string
Параметры ответа
Название Описание Тип
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money. Служит ключом для всей дальнейшей работы с транзакцией integer
pg_merchant_id Идентификатор мерчанта в системе PayBox.money integer
pg_order_id Идентификатор заказа в системе мерчанта string
pg_status Показывает результат выполнения запроса string
pg_redirect_url URL который необходимо вызвать в iframe или произвести перенаправление (redirect) string
pg_type Тип транзакции string
pg_salt Случайная строка string
pg_sig Подпись запроса string


Удаление карты

Удаление карты

Запрос

curl --location --request POST 'https://api.paybox.money/v1/merchant/{{paybox_merchant_id}}/cardstorage/remove' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_user_id=1234' \
--form 'pg_card_id=93' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'remove;93;{{paybox_merchant_id}};some random string;1234;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <card>
        <pg_status>deleted</pg_status>
        <pg_merchant_id>1234</pg_merchant_id>
        <pg_card_id/>
        <pg_card_hash/>
        <deleted_at>2020-07-28 09:45:51</deleted_at>
    </card>
    <pg_salt>3wOIeVEc</pg_salt>
    <pg_sig>5b8c60b26ee1addc9956ebc8426353e6</pg_sig>
</response>

[newman gif](/flow/cardsave/remove.svg)

Получаем pg_card_id из Post link запроса и pg_user_id для удаление карт делаем следующий запрос.

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_user_id' => 1234,
    'pg_card_id' => 1234,
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'remove');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/v1/merchant/{{paybox_merchant_id}}/cardstorage/remove

Поля запроса
Название Описание Тип
pg_merchant_id
required
Идентификатор мерчанта в системе PayBox.money. integer
pg_user_id
required
ID пользователя в системе мерчанта.
Пример: 1234
integer
pg_card_id
required
ID карты.
Пример: 93
integer
pg_salt
required
Случайная строка, состоящая из произвольных цифр и латинских букв.
Пример: some random string
string
pg_sig
required
Подпись запроса string
Параметры ответа
Название Описание Тип
pg_status Показывает результат выполнения запроса string
pg_merchant_id Идентификатор мерчанта в системе PayBox.money integer
pg_card_id ID карты integer
pg_card_hash Маскированный PAN карты string
deleted_at Дата удаления карты datetime
pg_salt Случайная строка string
pg_sig Подпись запроса string


Получение списка карт

Получение списка карт

Запрос

curl --location --request POST 'https://api.paybox.money/v1/merchant/{{paybox_merchant_id}}/cardstorage/list' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_user_id=1234' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'list;{{paybox_merchant_id}};some random string;1234;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <card>
        <pg_status>success</pg_status>
        <pg_merchant_id>1234</pg_merchant_id>
        <pg_card_id>56</pg_card_id>
        <pg_recurring_profile_id>317</pg_recurring_profile_id>
        <pg_card_hash>5101-45XX-XXXX-7898</pg_card_hash>
        <pg_card_hhash>2163f971d73a8c928a7d739fb2732ee1</pg_card_hhash>
        <created_at>2019-07-19 06:03:08</created_at>
    </card>
    <card>
        <pg_status>success</pg_status>
        <pg_merchant_id>1234</pg_merchant_id>
        <pg_card_id>93</pg_card_id>
        <pg_recurring_profile_id>331</pg_recurring_profile_id>
        <pg_card_hash>4003-03XX-XXXX-5378</pg_card_hash>
        <pg_card_hhash>5d90a02298685b8e2787b68863c8ae2a</pg_card_hhash>
        <created_at>2019-08-22 12:45:41</created_at>
    </card>
    <pg_salt>0reqSARN</pg_salt>
    <pg_sig>4cdff2e2e7f54bd4f3cde31dcac9155c</pg_sig>
</response>

[newman gif](/flow/cardsave/list.svg)

По пользователю pg_user_id получаем список карт со следующим запросом.

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_user_id' => 1234,
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'list');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/v1/merchant/{{paybox_merchant_id}}/cardstorage/list

Поля запроса
Название Описание Тип
pg_merchant_id
required
Идентификатор мерчанта в системе PayBox.money. integer
pg_user_id
required
ID пользователя в системе мерчанта.
Пример: 1234
integer
pg_salt
required
Случайная строка, состоящая из произвольных цифр и латинских букв.
Пример: some random string
string
pg_sig
required
Подпись запроса string
Параметры ответа
Название Описание Тип
card
pg_statusПоказывает результат выполнения запросаstring
pg_merchant_idИдентификатор мерчанта в системе PayBox.moneyinteger
pg_card_idID картыinteger
pg_card_hashМаскированный PAN картыstring
pg_card_hhashХеш маскированной PAN картыstring
pg_recurring_profile_idИдентификатор профиля рекуррентных платежейstring
created_atДата добавления картыdatetime
pg_saltСлучайная строкаstring
pg_sigПодпись запросаstring
object


Post link запрос для магазина

Ответ на post_link от мерчанта

<?xml version="1.0" encoding="UTF-8"?>
<pg_status>ok</pg_status>  

В случае правильного ввода платеж отменяется и заблокированная сумма моментально возвращается на карточку пользователя, а сама карта считается успешно добавленной в систему.

В случае превышения попыток ввода, либо по истечению выделенного времени платеж отменяется и заблокированная сумма моментально возвращается на карточку пользователя.

В случае успешного добавления карты, в параметре pg_xml будет XML следующего вида:

При этом pg_type будет равен confirm.

Сервер мерчанта должен ответить статусом 200

URL запроса

POST {{post_link}}

Headers
Content-Type Value
Content-Type application/x-www-form-urlencoded
Поля запроса
Название Описание Тип
pg_type Тип транзакции string
pg_payment_id ID транзакции в системе PayBox.money. integer
pg_order_id ID заказа в системе мерчанта string
pg_card_3ds Признак наличия 3ds на карте string
pg_card_hash Маскированный PAN карты string
pg_card_id ID сохраненной карты. integer
pg_user_id ID пользователя в системе мерчанта. integer
pg_status Статус платежа string
pg_card_month Месяц срока действия карты string
pg_card_year Год срока действия карты string
pg_salt Случайная строка, состоящая из произвольных цифр и латинских букв.
Пример: some random string
string
pg_sig Подпись запроса string


Дополнительно

Формирование подписи

Любые сообщения (запросы и ответы) между PayBox.money и мерчантом подписываются. Для формирования подписи необходимо конкатенировать с разделителем ;

  1. имя вызываемого скрипта (от последнего / до конца или ?)

  2. все поля сообщения в алфавитном порядке, включая случайную строку pg_salt, состоящую из произвольного количества цифр и латинских букв, при этом: a. к вложенным тегам это правило применяется рекурсивно (только XML) b. поля с одинаковыми именами берутся в том порядке, в котором они присутствуют в сообщении

  3. и платежный пароль secret_key, который задается в настройках магазина и известен только мерчанту и PayBox.money.

От полученной в результате конкатенации строки необходимо вычислить md5 и добавить в запрос или ответ в качестве дополнительного параметра pg_sig. MD5 хэш записывается в виде шестнадцатеричной строки в нижнем регистре (32 символа).

Любая сторона может добавлять в запрос или ответ дополнительные параметры, не указанные в документации. Эти параметры также участвуют в вычислении подписи. Сообщение не подписывается, и соответственно поля pg_salt и pg_sig отсутствуют только в одном случае – когда PayBox.money не смог идентифицировать мерчанта и поэтому не знает его secret_key. В таком случае поле pg_error_code (числовой код ошибки) принимает значение 101. Полный список возможных значений поля pg_error_code см. в разделе Справочник кодов ошибок.

Тестовые карты

Все новые мерчанты первоначально находятся в тестовом режиме, затем после завершения тестирования и отправки мерчантом в PayBox.money подписанного Акта о подключении (его можно распечатать по ссылке https://www.paybox.money/admin/documents.php) администрация PayBox.money переводит мерчант в рабочий режим.

В тестовом режиме можно использовать только тестовые платежные методы, а в рабочем режиме, наоборот, оплата тестовыми платежными методами невозможна.

После перехода мерчанта в рабочий режим можно создавать отдельные транзакции в тестовом режиме, передавая параметр pg_testing_mode в запросах на создание платежа и на получение списка платежных методов. Значение pg_testing_mode=1 включает тестовый режим для одной конкретной транзакции. Если сам мерчант находится в тестовом режиме, то значение переданного флага pg_testing_mode не имеет значения. Включение и выключение тестового режима в настройках мерчанта осуществляется только администрацией PayBox.money.

После создания транзакции никаких автоматических действий с ней не происходит. Для того, чтобы протестировать дальнейшее прохождение транзакции нужно зайти в административную панель, и войти в транзакцию. Далее управлять ее действиями с помощью тестовых кнопок.

В тестовом платежном методе возможно тестирование клиринга, PSI DSS, длинной записи и рекуррентных платежей. При оплате через тестовый карточный платежный метод требуется ввести номер карты. Можете использовать настоящую карту (списания не происходит), подобрать номер карты (по правилу луна), а так же использовать тестовые карты. Тестовые карты не валидируют модуль фрод мониторинга.

Список тестовых карт:

Карты без 3ds:

Номер карты Срок действия CVV
4405 6450 0000 6150 09-2025 653
5483 1850 0000 0293 09-2025 343
3775 1450 0009 951 09-2025 3446

Карты с 3ds:

Номер карты Срок действия CVV 3ds код
4405 6450 0000 6371 12-2016 292 test1
4405 6450 0000 6374 12-2016 292 test1
4003 0350 0000 5378 12-2025 323 secure1
5101 4500 0000 7898 12-2025 454 Master1

Securebox

Secure Box - антифрод система, с помощью которой можно выявлять и пресекать мошенническую деятельность до проведения платежа. Антифрод система позволяет снизить количество мошеннических операций, повысить конверсию и количество успешных транзакций.

Если вы уже интегрированы с PayBox.money, дополнительные доработки не нужны. Для корректной работы сервиса необходимо передавать следующие параметры:

"pg_user_ip": "192.168.1.1",
"pg_user_email": "email@example.com",
"pg_user_phone": "+77773332211"
pg_user_phone

Телефон плательщика либо телефон привязанный (указанный при регистрации) к ID личного кабинета или аккаунта или номер кошелька плательщика

Цифры, в формате 89686810502 или 87001234567

Центр Учета Ставок

Согласно требованиям законодательства Республики Казахстан (подпункт 9, пункта 1 статьи 12 Закона о платежах и платежных системах) все платежи Букмекерских контор и Тотализаторов должны фиксироваться в Центре Учета Ставок (ЦУС) Подробнее на официальном сайте https://meao.kz

Paybox.money реализует полную интеграцию с ЦУС Казахстан по учету ставок, а также предоставляет полученные данные от ЦУС в ответе. Букмекеру необходимо передавать в запросах дополнительные параметры pg_cus_auth_type и pg_cus_auth_value В которых передаются ID кошелька ЦУС или номер телефона игрока. С данным параметрами автоматически проводятся запросы в ЦУС для авториации и учета ставок. В случае, отсутствия даных параметров в запросе, Paybox.money автоматически пользователя на официальный сайт ЦУС Казахстан для регистрации, а после продолжит выполнение платежного сценария.

Получение списка платежных систем

Получение списка платежных систем

Запрос

curl --location --request POST 'https://api.paybox.money/ps_list.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'ps_list.php;{{paybox_merchant_id}};some random string;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_system>
        <pg_name>EPAYWEBKZT</pg_name>
        <pg_description>Банковские карты Visa, MasterCard, American Express</pg_description>
        <pg_payment_scenario>online</pg_payment_scenario>
        <pg_category>bankcard</pg_category>
        <pg_amount_to_pay_currency>KZT</pg_amount_to_pay_currency>
        <pg_payment_system_id>9</pg_payment_system_id>
    </pg_payment_system>
    <pg_payment_system>
        <pg_name>KAZPOSTYANDEX</pg_name>
        <pg_description>Электронные деньги Яндекс</pg_description>
        <pg_payment_scenario>offline</pg_payment_scenario>
        <pg_category>wallet</pg_category>
        <pg_amount_to_pay_currency>KZT</pg_amount_to_pay_currency>
        <pg_payment_system_id>23</pg_payment_system_id>
    </pg_payment_system>
    <pg_payment_system>
        <pg_name>ATFECOMKZT</pg_name>
        <pg_description>Банковские карты Visa, MasterCard, American Express</pg_description>
        <pg_payment_scenario>online</pg_payment_scenario>
        <pg_category>bankcard</pg_category>
        <pg_amount_to_pay_currency>KZT</pg_amount_to_pay_currency>
        <pg_payment_system_id>101</pg_payment_system_id>
    </pg_payment_system>
    <pg_payment_system>
        <pg_name>QIWIWALLETKZT</pg_name>
        <pg_description/>
        <pg_payment_scenario>online</pg_payment_scenario>
        <pg_category>cash</pg_category>
        <pg_amount_to_pay_currency>KZT</pg_amount_to_pay_currency>
        <pg_payment_system_id>119</pg_payment_system_id>
    </pg_payment_system>
    <pg_payment_system>
        <pg_name>DEMIRBANKKGS</pg_name>
        <pg_description>Банковские карты Visa, MasterCard, American Express</pg_description>
        <pg_payment_scenario>online</pg_payment_scenario>
        <pg_category>bankcard</pg_category>
        <pg_amount_to_pay_currency>KGS</pg_amount_to_pay_currency>
        <pg_payment_system_id>126</pg_payment_system_id>
    </pg_payment_system>
    <pg_payment_system>
        <pg_name>YANDEXCHECKOUTTHKZT</pg_name>
        <pg_description/>
        <pg_payment_scenario>online</pg_payment_scenario>
        <pg_category>wallet</pg_category>
        <pg_amount_to_pay_currency>KZT</pg_amount_to_pay_currency>
        <pg_payment_system_id>127</pg_payment_system_id>
    </pg_payment_system>
    <pg_payment_system>
        <pg_name>ELSOMCHECKOUTKGS</pg_name>
        <pg_description/>
        <pg_payment_scenario>online</pg_payment_scenario>
        <pg_category>wallet</pg_category>
        <pg_amount_to_pay_currency>KZT</pg_amount_to_pay_currency>
        <pg_payment_system_id>128</pg_payment_system_id>
    </pg_payment_system>
    <pg_salt>3fofHqBpK4I62oEA</pg_salt>
    <pg_sig>d81a43b839ee1e66c6707600d0856f60</pg_sig>
</response>

Если мерчант хочет, чтобы покупатель совершал выбор платежной системы на сайте мерчанта, он может либо самостоятельно вывести список доступных платежных систем и рассчитать окончательную цену для каждой ПС с учетом комиссий на основе имеющихся в договоре данных, либо получать актуальную информацию о списке доступных платежных систем и комиссиях в автоматическом режиме. В последнем случае магазину необходимо использовать прямой запрос к PayBox.money, описанный ниже.

Генерация подписи:

$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'ps_list.php');
array_push($request, $secret_key); //add your secret key (you can take it in your personal cabinet on paybox system)

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.paybox.money/ps_list.php

Поля запроса
Название Описание Тип
pg_merchant_id
required
Идентификатор мерчанта в системе PayBox.money. integer
pg_salt
required
Случайная строка
Пример: some random string
string
pg_sig
required
Подпись запроса string
Параметры ответа
Название Описание Тип
pg_status Показывает результат выполнения запроса string
pg_payment_system
pg_nameИмя платежной системыstring
pg_descriptionОписание системы, можно показывать пользователюstring
pg_payment_scenarioEnum:offline, online
Сценарий приема платежа может быть offline или online
string
pg_categoryКатегория платежной системы для удобства вывода списка ПС на стороне мерчантаstring
pg_amount_to_pay_currencyВалюта платежной системыstring
object
pg_salt Случайная строка string
pg_sig Подпись запроса string