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

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

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

Любые сообщения (запросы и ответы) между 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 подписанного Акта о подключении администрация PayBox.money переводит мерчант в рабочий режим.

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

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

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

В качестве имени карте нужно указывать от 2 слов в английской раскладке.

Пароль для 3-D Secure проверки: 12345678
Список тестовых карт:

Номер карты CVV Срок действия Результат по карте
4444444444446666 123 2024/12 Блокировка по лимиту
4111111111111111 123 2024/12 Запрос успешно обработан
4563960122001999 347 2024/12 Общая ошибка
5555555555555557 123 2024/12 Банк-эмитент не смог провести авторизацию 3dsecure-карты
5555555555555599 123 2024/12 Запрос успешно обработан
4444444444444422 123 2024/12 Общая ошибка
4444444411111111 123 2024/12 Общая ошибка
4444444499999999 123 2024/12 Ошибка связи 3DS

Тестовые номера телефонов

Механика мобильной коммерции подразумевает тестирование в рамках ряда операторов.
Ниже будут предоставлены номера и соответствующие им OTP коды для проведения тестов

Список номеров:

Оператор Номер телефона OTP код
Кселл +77017777777 111111
Актив +77027777777 111111
Теле2 +77037777777 111111
Алтел +77047777777 111111

Изменения

Изменение Дата
Изменились тестовые карты 18.11.2021
Описание статусов платежей для метода get_status2.php 25.11.2021
Добавил поля по ОФД для возвратов 02.12.2021
Добавил receipt_positions в чекаут 02.12.2021
Добавил информацию о авторизации в result url 02.12.2021
Добавил спецификацию для выплат на IBAN 03.12.2021
Заменил get_status на get_status2 07.12.2021
Добавил информацию о новых параметрах при ошибках платежа: pg_error_code, pg_error_description для отправки на failrure_url. Добавил информацию о скидке в callback result: pg_discount_percent, pg_discount_amount 07.12.2021
Добавил описание статусов для синхронных операций по выплатам на карты 27.12.2021
Перенес рекуррентные платежи в устаревшие сценарии
Добавлен новый сценарий "Безакцептное списание"
12.01.2022
Исправил формат ответа на check_url 13.01.2022

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

Вопросы и предложения отправляйте по адресу: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.

При передаче данных через браузер пользователя в PayBox.money, мерчант направить пользователя с данными данные на 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_payment_method Значение - Метод платежа
wallet - Электронные деньги
internetbank - Интернет-банкинг
other - Терминалы
bankcard - Банковские карты
cash - Точки приема платежей
mobile_commerce - Мобильная коммерция

Пример: mobile_commerce
string
pg_timeout_after_payment Определяет время закрытия страницы с платежом в секундах
Пример: 10
integer
Параметры ответа
Название Описание Тип
pg_status Показывает результат выполнения запроса
СтатусОписание
okЗапрос прошел успешно
errorЗапрос прошел с ошибкой
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 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>rejected</pg_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 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_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 от мерчанта

Если 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_ 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_amount=500' \
--form 'pg_currency=KZT' \
--form 'pg_net_amount=482.5' \
--form 'pg_ps_amount=500' \
--form 'pg_ps_full_amount=500' \
--form 'pg_ps_currency=KZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=0' \
--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}}' \
--form 'pg_payment_method=bankcard'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>rejected</pg_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_amount=500' \
--form 'pg_currency=KZT' \
--form 'pg_net_amount=482.5' \
--form 'pg_ps_amount=500' \
--form 'pg_ps_full_amount=500' \
--form 'pg_ps_currency=KZT' \
--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}}' \
--form 'pg_payment_method=bankcard'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_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 на стороне мерчанта должен быть общедоступным, без авторизации.

Если сервер мерчанта недоступен в момент вызова Result URL или ответ от сервера был не со статусом 200, 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_amount Сумма выставленного счета в валюте pg_currency
Пример: 500
string
pg_currency Валюта выставленного счета, совпадает с pg_currency в момент инициализации платежа
Пример: KZT
string
pg_net_amount Сумма счета (в валюте `pg_ps_currency), выставленного в ПС. Поле может отсутствовать в случае неудачного платежа
Пример: 482.5
string
pg_ps_amount Полная сумма (в валюте pg_ps_currency), которую заплатил покупатель с учетом всех комиссий. Поле может отсутствовать в случае неудачного платежа.
Пример: 500
string
pg_ps_full_amount Полная сумма (в валюте pg_ps_currency), которую заплатил покупатель с учетом всех комиссий. Поле может отсутствовать в случае неудачного платежа


Пример: 500
string
pg_ps_currency Валюта, в которой был произведен платеж в платежной системе. Поле может отсутствовать в случае неудачного платежа
Пример: KZT
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_id Опциональный параметр. ID карты для оплаты сохраненной картой
Пример: 1234
string
pg_card_pan Маскированный номер карты (часть цифр номера карты скрыты). Этот параметр передается только в случае успешной оплаты банковской картой
Пример: 5483-18XX-XXXX-0293
string
Параметры мерчанта Все поля, переданные с веб-сайта мерчанта, не имеющие префикса pg_ string
pg_salt Случайная строка
Пример: some random string
string
pg_sig Подпись запроса string
pg_discount_percent Информация о проценте скидки, отправляется если скидка присутствует
Пример: 1.0
string
pg_discount_amount Информация о сумме скидки, отправляется если скидка присутствует
Пример: 5
string
pg_payment_method Метод платежа
ЗначениеМетод платежа
walletЭлектронные деньги
internetbankИнтернет-банкинг
otherТерминалы
bankcardБанковские карты
cashТочки приема платежей
mobile_commerceМобильная коммерция

Пример: bankcard
string
pg_card_exp Дата истечения срока карты
Пример: 03/23
string
pg_card_owner Имя держателя карты
Пример: Ivan Ivanov
string
pg_card_brand Код бренда карты
Пример: VI
string


Возврат покупателя на сайт мерчанта

После завершения платежа в 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}} или {{failure_url}}

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


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

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

Запрос

curl --location --request POST 'https://api.paybox.money/get_status2.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_payment_id=4567617' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status2.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_status2.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_payment_id=4567775' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status2.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_status2.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_status2.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 Показывает результат выполнения запроса
СтатусОписание
okЗапрос прошел успешно
errorЗапрос прошел с ошибкой
string
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money Служит ключом для всей дальнейшей работы с транзакцией integer
pg_transaction_status Статус платежа
СтатусОписание
partialНовый платеж
pendingОжидание плательщика или платежной системы
refundedПо платежу прошел возврат
revokedПо платежу прошла отмена
okПлатеж успешно завершен
failedПлатеж в ошибке
incompleteИстекло время жизни платежа
string
pg_testing_mode Enum:0 1
0 - платеж в боевом режиме 1 - платеж в тестовом режиме
integer
pg_create_date Дата и время создания платежной транзакции datetime
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_failure_code Код ошибки integer
pg_failure_description Описание ошибки string
pg_amount Сумма заказа number
pg_currency Валюта заказа string
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.

При передаче данных через браузер пользователя в PayBox.money, мерчант направить пользователя с данными данные на 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 Показывает результат выполнения запроса
СтатусОписание
okЗапрос прошел успешно
errorЗапрос прошел с ошибкой
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 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>rejected</pg_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 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

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

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

Check URL на стороне мерчанта должен быть общедоступным, без авторизации.

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_ 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_amount=500' \
--form 'pg_currency=KZT' \
--form 'pg_net_amount=482.5' \
--form 'pg_ps_amount=500' \
--form 'pg_ps_full_amount=500' \
--form 'pg_ps_currency=KZT' \
--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}}' \
--form 'pg_payment_method=bankcard'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_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_amount=500' \
--form 'pg_currency=KZT' \
--form 'pg_net_amount=482.5' \
--form 'pg_ps_amount=500' \
--form 'pg_ps_full_amount=500' \
--form 'pg_ps_currency=KZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=0' \
--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}}' \
--form 'pg_payment_method=bankcard'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>rejected</pg_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 на стороне мерчанта должен быть общедоступным, без авторизации.

Если сервер мерчанта недоступен в момент вызова Result URL или ответ от сервера был не со статусом 200, 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_amount Сумма выставленного счета в валюте pg_currency, совпадает с pg_amount в момент инициализции
Пример: 500
string
pg_currency Валюта выставленного счета, совпадает с pg_currency в момент инициализации платежа.
Пример: KZT
string
pg_net_amount Сумма (в валюте pg_currency), которая будет перечислена магазину, в случае успешного завершения платежа
Пример: 482.5
string
pg_ps_amount Сумма счета (в валюте `pg_ps_currency), выставленного в ПС. Поле может отсутствовать в случае неудачного платежа.
Пример: 500
string
pg_ps_full_amount Полная сумма (в валюте pg_ps_currency), которую заплатил покупатель с учетом всех комиссий. Поле может отсутствовать в случае неудачного платежа.
Пример: 500
string
pg_ps_currency Валюта, в которой был произведен платеж в платежной системе. Поле может отсутствовать в случае неудачного платежа
Пример: KZT
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_id Опциональный параметр. ID карты для оплаты сохраненной картой
Пример: 1234
string
pg_card_pan Маскированный номер карты (часть цифр номера карты скрыты). Этот параметр передается только в случае успешной оплаты банковской картой
Пример: 5483-18XX-XXXX-0293
string
Параметры мерчанта Все поля, переданные с веб-сайта мерчанта, не имеющие префикса pg_ string
pg_salt Случайная строка
Пример: some random string
string
pg_sig Подпись запроса string
pg_payment_method Метод платежа
ЗначениеМетод платежа
walletЭлектронные деньги
internetbankИнтернет-банкинг
otherТерминалы
bankcardБанковские карты
cashТочки приема платежей
mobile_commerceМобильная коммерция

Пример: bankcard
string
pg_card_exp Дата истечения срока карты
Пример: 03/23
string
pg_card_owner Имя держателя карты
Пример: Ivan Ivanov
string
pg_card_brand Код бренда карты
Пример: VI
string


Возврат покупателя на сайт мерчанта

После завершения платежа в 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
pg_error_code Код ошибки. В случае ошибки параметр будет отправляться на pg_failure_url
Пример: 1000
string
pg_error_description Описание ошибки. В случае ошибки параметр будет отправляться на pg_failure_url
Пример: Внутреняя ошибка сервиса
string


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

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

Запрос

curl --location --request POST 'https://api.paybox.money/get_status2.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_payment_id=4567617' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status2.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_status2.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_payment_id=4567775' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status2.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_status2.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_status2.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 Показывает результат выполнения запроса
СтатусОписание
okЗапрос прошел успешно
errorЗапрос прошел с ошибкой
string
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money Служит ключом для всей дальнейшей работы с транзакцией integer
pg_transaction_status Статус платежа
СтатусОписание
partialНовый платеж
pendingОжидание плательщика или платежной системы
refundedПо платежу прошел возврат
revokedПо платежу прошла отмена
okПлатеж успешно завершен
failedПлатеж в ошибке
incompleteИстекло время жизни платежа
string
pg_testing_mode Enum:0 1
0 - платеж в боевом режиме 1 - платеж в тестовом режиме
integer
pg_create_date Дата и время создания платежной транзакции datetime
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_failure_code Код ошибки integer
pg_failure_description Описание ошибки string
pg_amount Сумма заказа number
pg_currency Валюта заказа string
pg_salt Случайная строка 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,
                language: 'ru', // Язык виджета
                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",
          },
          receipt_positions: [
            {
              count: 2,
              name: "Коврик для мыши",
              tax_type: 3,
              price: 1000
            },
            {
              count: 2,
              name: "Розетка",
              tax_type: 3,
              price: 1000
            }
          ]
        }
      },
      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

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

Запрос на 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 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>rejected</pg_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 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_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_ string
pg_salt Случайная строка
Пример: some random string
string
pg_sig Подпись запроса string


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

Запрос на result url приходит методом POST, с заголовком Сontent-type: application/json и телом запроса
Result URL на стороне мерчанта должен быть общедоступным, без авторизации.

Мерчант должен быть готовым к тому, что запрос может быть отправлен несколько раз

Мерчант должен ответить на запрос определенным образом. В ином случае PayBox.Money будет отправлять запрос повторно еще 6 раз.

Текст для ответа на запрос:

{"status": "ok"}

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

{
    "id": 12345,
    "status": {
        "code": "success"
    },
    "order": 1234,
    "amount": "100.00",
    "refund_amount": "0.00",
    "currency": "KZT",
    "description": "Описание заказа",
    "payment_system": "WEBKZT",
    "expires_at": "2022-01-18T05:58:58Z",
    "created_at": "2022-01-17T11:58:58Z",
    "updated_at": "2022-01-17T11:59:07Z",
    "param1": null,
    "param2": null,
    "param3": null,
    "options": {
        "callbacks": {
            "result_url": "",
            "check_url": ""
        },
        "user": {
            "email": "widget@paybox.money",
            "phone": "77"
        },
        "receipt_positions": null
    },
    "salt": "EitR7ZYZvhpioeCU",
    "sig": "05e72b0137c52c1e941c627f42cb1f39"
}

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

{
    "id": 12345,
    "status": {
        "code": "error",
        "error_description": "Истек срок ожидания ввода данных."
    },
    "order": 1234,
    "amount": "100.00",
    "refund_amount": "0.00",
    "currency": "KZT",
    "description": "Описание заказа",
    "expires_at": "2022-04-18T00:00:00Z",
    "created_at": "2022-04-18T07:18:43Z",
    "updated_at": "2022-04-18T07:40:11Z",
    "param1": null,
    "param2": null,
    "param3": null,
    "options": {
        "user": {
            "email": "widget@paybox.money"
        },
        "receipt_positions": null
    },
    "salt": "a71XagJZ6YgBDuV3",
    "sig": "750c72a2b759bd8ea108d8cd56bc98cf"
}

Сохраненной картой с вводом cvc

Данный сценарий подразумевает участие пользователя в процессе оплаты. Пользователь перенаправляется в paybox для ввода cvc и прохождения проверки 3ds

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

Подтвержденные карты помечаются статусом approved, в списке карт

[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 Показывает результат выполнения запроса
СтатусОписание
okЗапрос прошел успешно
errorЗапрос прошел с ошибкой
string
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money. Служит ключом для всей дальнейшей работы с транзакцией integer
pg_merchant_id Идентификатор мерчанта в системе PayBox.money integer
pg_order_id Идентификатор заказа в системе мерчанта integer
pg_salt Случайная строка string
pg_sig Подпись запроса string


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

Для проведения оплаты необходимо перенаправить пользователя к PayBox POST-запросом

Перенаправление пользователя POST-запросом:

<html>
<body>
<form action="https://api.paybox.money/v1/merchant/{{paybox_merchant_id}}/card/pay" method="post" id="redirect-form">
<input type="hidden" name="pg_merchant_id" value="{{paybox_merchant_id}}" />
<input type="hidden" name="pg_payment_id" value="12345" />
<input type="hidden" name="pg_salt" value="some random string" />
<input type="hidden" name="pg_sig" value="{{paybox_signature}}" />
</form>

<script type="text/javascript">
document.getElementById('redirect-form').submit();
</script>
</body>
</html>

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

$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_amount=500' \
--form 'pg_currency=KZT' \
--form 'pg_net_amount=482.5' \
--form 'pg_ps_amount=500' \
--form 'pg_ps_full_amount=500' \
--form 'pg_ps_currency=KZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=0' \
--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}}' \
--form 'pg_payment_method=bankcard'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>rejected</pg_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_amount=500' \
--form 'pg_currency=KZT' \
--form 'pg_net_amount=482.5' \
--form 'pg_ps_amount=500' \
--form 'pg_ps_full_amount=500' \
--form 'pg_ps_currency=KZT' \
--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}}' \
--form 'pg_payment_method=bankcard'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_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 на стороне мерчанта должен быть общедоступным, без авторизации.

Если сервер мерчанта недоступен в момент вызова 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_amount Сумма выставленного счета в валюте pg_currency, совпадает с pg_amount в момент инициализции
Пример: 500
string
pg_currency Валюта выставленного счета, совпадает с pg_currency в момент инициализации платежа.
Пример: KZT
string
pg_net_amount Сумма (в валюте pg_currency), которая будет перечислена магазину, в случае успешного завершения платежа
Пример: 482.5
string
pg_ps_amount Сумма счета (в валюте `pg_ps_currency), выставленного в ПС. Поле может отсутствовать в случае неудачного платежа
Пример: 500
string
pg_ps_full_amount Полная сумма (в валюте pg_ps_currency), которую заплатил покупатель с учетом всех комиссий. Поле может отсутствовать в случае неудачного платежа
Пример: 500
string
pg_ps_currency Валюта, в которой был произведен платеж в платежной системе. Поле может отсутствовать в случае неудачного платежа
Пример: KZT
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
pg_payment_method Метод платежа
ЗначениеМетод платежа
walletЭлектронные деньги
internetbankИнтернет-банкинг
otherТерминалы
bankcardБанковские карты
cashТочки приема платежей
mobile_commerceМобильная коммерция

Пример: bankcard
string
pg_card_exp Дата истечения срока карты
Пример: 03/23
string
pg_card_owner Имя держателя карты
Пример: Ivan Ivanov
string
pg_card_brand Код бренда карты
Пример: VI
string


Безакцептное списание

Данный сценарий похож на Сохраненной картой с вводом сvc. Но в случае, когда карта, по которой проходит платеж является подтвержденной, cvc у пользователя не запрашивается.

Подтвержденные карты помечаются статусом approved, в списке карт

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

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

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

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

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

$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 Показывает результат выполнения запроса
СтатусОписание
okЗапрос прошел успешно
errorЗапрос прошел с ошибкой
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/direct

Поля запроса
Название Описание Тип
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
Параметры ответа
Название Описание Тип
pg_status Показывает результат выполнения запроса
СтатусОписание
okЗапрос прошел успешно
errorЗапрос прошел с ошибкой
string
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money Служит ключом для всей дальнейшей работы с транзакцией integer
pg_testing_mode Enum:0 1
0 - платеж в боевом режиме 1 - платеж в тестовом режиме
integer
pg_create_date Дата и время создания платежной транзакции datetime
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_failure_code Код ошибки integer
pg_failure_description Описание ошибки string
pg_amount Сумма заказа number
pg_currency Валюта заказа string
pg_salt Случайная строка string
pg_sig Подпись запроса string


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

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

Запрос

curl --location --request POST '{{result_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=500' \
--form 'pg_currency=KZT' \
--form 'pg_net_amount=482.5' \
--form 'pg_ps_amount=500' \
--form 'pg_ps_full_amount=500' \
--form 'pg_ps_currency=KZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=0' \
--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}}' \
--form 'pg_payment_method=bankcard'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>rejected</pg_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_amount=500' \
--form 'pg_currency=KZT' \
--form 'pg_net_amount=482.5' \
--form 'pg_ps_amount=500' \
--form 'pg_ps_full_amount=500' \
--form 'pg_ps_currency=KZT' \
--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}}' \
--form 'pg_payment_method=bankcard'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_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 на стороне мерчанта должен быть общедоступным, без авторизации.

Если сервер мерчанта недоступен в момент вызова 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_amount Сумма выставленного счета в валюте pg_currency, совпадает с pg_amount в момент инициализции
Пример: 500
string
pg_currency Валюта выставленного счета, совпадает с pg_currency в момент инициализации платежа.
Пример: KZT
string
pg_net_amount Сумма (в валюте pg_currency), которая будет перечислена магазину, в случае успешного завершения платежа
Пример: 482.5
string
pg_ps_amount Сумма счета (в валюте `pg_ps_currency), выставленного в ПС. Поле может отсутствовать в случае неудачного платежа
Пример: 500
string
pg_ps_full_amount Полная сумма (в валюте pg_ps_currency), которую заплатил покупатель с учетом всех комиссий. Поле может отсутствовать в случае неудачного платежа
Пример: 500
string
pg_ps_currency Валюта, в которой был произведен платеж в платежной системе. Поле может отсутствовать в случае неудачного платежа
Пример: KZT
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
pg_payment_method Метод платежа
ЗначениеМетод платежа
walletЭлектронные деньги
internetbankИнтернет-банкинг
otherТерминалы
bankcardБанковские карты
cashТочки приема платежей
mobile_commerceМобильная коммерция

Пример: bankcard
string
pg_card_exp Дата истечения срока карты
Пример: 03/23
string
pg_card_owner Имя держателя карты
Пример: Ivan Ivanov
string
pg_card_brand Код бренда карты
Пример: VI
string


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

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

Tele2
Altel
Beeline
Activ
Kcell

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

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

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

Запрос

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}}' \
--form 'pg_payment_method=mobile_commerce'
# Пример подписи:
'init_payment.php;25;test;{{paybox_merchant_id}};23;KZT;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_site_url URL сайта мерчанта для показа покупателю ссылки, по которой он может вернуться на сайт мерчанта после создания счета. Применяется для offline ПС (наличные).
Пример: http://site.kz/return
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_language Язык платежных страниц на сайте PayBox.money и (если возможно) платежных систем. "en", "ru"
Пример: ru
string
pg_testing_mode Создание платежа в тестовом режиме.
Пример: 1
integer
pg_user_id ID пользователя в системе мерчанта.
Пример: 123
integer
pg_param1 Дополнительный параметр 1
Пример: Дополнительная информация
string
pg_param2 Дополнительный параметр 2
Пример: Дополнительная информация
string
pg_param3 Дополнительный параметр 3
Пример: Дополнительная информация
string
pg_payment_method Значение - Метод платежа
mobile_commerce - Мобильная коммерция

Пример: mobile_commerce
string
Параметры ответа
Название Описание Тип
pg_status Показывает результат выполнения запроса
СтатусОписание
okЗапрос прошел успешно
errorЗапрос прошел с ошибкой
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_status Показывает результат выполнения запроса
СтатусОписание
okСписание прошло успешно
need_approveНеобходимо подтверждение
errorОшибка списания
string
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money. Служит ключом для всей дальнейшей работы с транзакцией integer


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

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

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

$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' => '077587',
    '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 сообщением на номер плательщика.
Пример: 077587
string
pg_salt
required
Случайная строка
Пример: some random string
string
pg_sig
required
Подпись запроса string
Параметры ответа
Название Описание Тип
pg_status

Показывает результат выполнения запроса

СтатусОписание
okСписание прошло успешно
processСписание в процессе. Финальный статус необходимо получить методом запроса статуса
errorОшибка списания
string
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money. Служит ключом для всей дальнейшей работы с транзакцией integer


Запрос на повторную отправку 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


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

Мерчант может запрашивать 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_status2.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_status2.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 Показывает результат выполнения запроса
СтатусОписание
okЗапрос прошел успешно
errorЗапрос прошел с ошибкой
string
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money Служит ключом для всей дальнейшей работы с транзакцией integer
pg_transaction_status Статус платежа
СтатусОписание
partialНовый платеж
pendingОжидание плательщика или платежной системы
refundedПо платежу прошел возврат
revokedПо платежу прошла отмена
okПлатеж успешно завершен
failedПлатеж в ошибке
incompleteИстекло время жизни платежа
string
pg_testing_mode Enum:0 1
0 - платеж в боевом режиме 1 - платеж в тестовом режиме
integer
pg_create_date Дата и время создания платежной транзакции datetime
pg_failure_code Код ошибки integer
pg_failure_description Описание ошибки string
pg_amount Сумма заказа number
pg_currency Валюта заказа 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 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_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 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

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

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

Check URL на стороне мерчанта должен быть общедоступным, без авторизации.

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_ 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_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}}' \
--form 'pg_payment_method=bankcard'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_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_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}}' \
--form 'pg_payment_method=bankcard'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>rejected</pg_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 на стороне мерчанта должен быть общедоступным, без авторизации.

Если сервер мерчанта недоступен в момент вызова Result URL или ответ от сервера был не со статусом 200, 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_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
pg_payment_method Метод платежа
ЗначениеМетод платежа
walletЭлектронные деньги
internetbankИнтернет-банкинг
otherТерминалы
bankcardБанковские карты
cashТочки приема платежей
mobile_commerceМобильная коммерция

Пример: bankcard
string


Двухэтапным способом

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

В случае, если мерчант не вызвал метод клиринга в течение 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 Показывает результат выполнения запроса
СтатусОписание
okЗапрос прошел успешно
errorЗапрос прошел с ошибкой
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 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>rejected</pg_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 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

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

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

Check URL на стороне мерчанта должен быть общедоступным, без авторизации.

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_ 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_amount=500' \
--form 'pg_currency=KZT' \
--form 'pg_net_amount=482.5' \
--form 'pg_ps_amount=500' \
--form 'pg_ps_full_amount=500' \
--form 'pg_ps_currency=KZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=0' \
--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}}' \
--form 'pg_payment_method=bankcard'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>rejected</pg_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_amount=500' \
--form 'pg_currency=KZT' \
--form 'pg_net_amount=482.5' \
--form 'pg_ps_amount=500' \
--form 'pg_ps_full_amount=500' \
--form 'pg_ps_currency=KZT' \
--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}}' \
--form 'pg_payment_method=bankcard'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_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 на стороне мерчанта должен быть общедоступным, без авторизации.

Если сервер мерчанта недоступен в момент вызова Result URL или ответ от сервера был не со статусом 200, 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_amount Сумма выставленного счета в валюте pg_currency, совпадает с pg_amount в момент инициализции
Пример: 500
string
pg_currency Валюта выставленного счета, совпадает с pg_currency в момент инициализации платежа.
Пример: KZT
string
pg_net_amount Сумма (в валюте pg_currency), которая будет перечислена магазину, в случае успешного завершения платежа
Пример: 482.5
string
pg_ps_amount Сумма счета (в валюте `pg_ps_currency), выставленного в ПС. Поле может отсутствовать в случае неудачного платежа
Пример: 500
string
pg_ps_full_amount Полная сумма (в валюте pg_ps_currency), которую заплатил покупатель с учетом всех комиссий. Поле может отсутствовать в случае неудачного платежа
Пример: 500
string
pg_ps_currency Валюта, в которой был произведен платеж в платежной системе. Поле может отсутствовать в случае неудачного платежа
Пример: KZT
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
pg_payment_method Метод платежа
ЗначениеМетод платежа
walletЭлектронные деньги
internetbankИнтернет-банкинг
otherТерминалы
bankcardБанковские карты
cashТочки приема платежей
mobile_commerceМобильная коммерция

Пример: bankcard
string
pg_card_exp Дата истечения срока карты
Пример: 03/23
string
pg_card_owner Имя держателя карты
Пример: Ivan Ivanov
string
pg_card_brand Код бренда карты
Пример: VI
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, если запрос принят на обработку.
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_status2.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_payment_id=4567617' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status2.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_status2.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_payment_id=4567775' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status2.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_status2.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_status2.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 Показывает результат выполнения запроса
СтатусОписание
okЗапрос прошел успешно
errorЗапрос прошел с ошибкой
string
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money Служит ключом для всей дальнейшей работы с транзакцией integer
pg_transaction_status Статус платежа
СтатусОписание
partialНовый платеж
pendingОжидание плательщика или платежной системы
refundedПо платежу прошел возврат
revokedПо платежу прошла отмена
okПлатеж успешно завершен
failedПлатеж в ошибке
incompleteИстекло время жизни платежа
string
pg_testing_mode Enum:0 1
0 - платеж в боевом режиме 1 - платеж в тестовом режиме
integer
pg_create_date Дата и время создания платежной транзакции datetime
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_failure_code Код ошибки integer
pg_failure_description Описание ошибки string
pg_amount Сумма заказа number
pg_currency Валюта заказа string
pg_salt Случайная строка string
pg_sig Подпись запроса string


Длинная запись

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

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

*Примечание: как минимум должны быть указаны данные авиабилета (Имя пассажира и номер
билета) и один перелет.

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

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

Запрос

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.

При передаче данных через браузер пользователя в PayBox.money, мерчант направить пользователя с данными данные на 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_payment_method Значение - Метод платежа
wallet - Электронные деньги
internetbank - Интернет-банкинг
other - Терминалы
bankcard - Банковские карты
cash - Точки приема платежей
mobile_commerce - Мобильная коммерция

Пример: mobile_commerce
string
pg_timeout_after_payment Определяет время закрытия страницы с платежом в секундах
Пример: 10
integer
pg_airticket_name
required
Имя пассажира string
pg_airticket_number
required
Номер билета string
pg_airticket_restricted Возвращаемый ли билет (0 – возвращаемый, 1- нет) boolean
pg_airticket_system Система, по которой покупается билет. Например: DATS, SABR string
pg_airticket_agencycode Код туроператора string
pg_airticket_flight1_date
required
Дата вылета, например 2017-07-26 16:00:00 datetime
pg_airticket_flight1_carrier
required
Двух символьный код перевозчика string
pg_airticket_flight1_seatclass
required
Класс: эконом, бизнес и т.д. string
pg_airticket_flight1_from
required
Код аэропорта вылета string
pg_airticket_flight1_to
required
Код аэропорта прилета string
pg_airticket_flight1_stop
required
Означает разрешен ли выезд в город во время ожидания следующего самолета при пересадке. O – разрешен, X - нет string
pg_airticket_flight1_fare
required
Код основного базисного тарифа string
pg_airticket_flight1_number
required
Номер рейса string
pg_airticket_flight2_date Дата вылета, например 2017-07-26 16:00:00 datetime
pg_airticket_flight2_carrier Двух символьный код перевозчика string
pg_airticket_flight2_seatclass Класс: эконом, бизнес и т.д. string
pg_airticket_flight2_from Код аэропорта вылета string
pg_airticket_flight2_to Код аэропорта прилета string
pg_airticket_flight2_stop Означает разрешен ли выезд в город во время
ожидания следующего самолета при пересадке. O –
разрешен, X - нет
string
pg_airticket_flight2_fare Код основного базисного тарифа string
pg_airticket_flight2_number Номер рейса string
pg_airticket_flight3_date Дата вылета, например 2017-07-26 16:00:00 datetime
pg_airticket_flight3_carrier Двух символьный код перевозчика string
pg_airticket_flight3_seatclass Класс: эконом, бизнес и т.д. string
pg_airticket_flight3_from Код аэропорта вылета string
pg_airticket_flight3_to Код аэропорта прилета string
pg_airticket_flight3_stop Означает разрешен ли выезд в город во время
ожидания следующего самолета при пересадке. O –
разрешен, X - нет
string
pg_airticket_flight3_fare Код основного базисного тарифа string
pg_airticket_flight3_number Номер рейса string
pg_airticket_flight4_date Дата вылета, например 2017-07-26 16:00:00 datetime
pg_airticket_flight4_carrier Двух символьный код перевозчика string
pg_airticket_flight4_seatclass Класс: эконом, бизнес и т.д. string
pg_airticket_flight4_from Код аэропорта вылета string
pg_airticket_flight4_to Код аэропорта прилета string
pg_airticket_flight4_stop Означает разрешен ли выезд в город во время
ожидания следующего самолета при пересадке. O –
разрешен, X - нет
string
pg_airticket_flight4_fare Код основного базисного тарифа string
pg_airticket_flight4_number Номер рейса string
Параметры ответа
Название Описание Тип
pg_status Показывает результат выполнения запроса
СтатусОписание
okЗапрос прошел успешно
errorЗапрос прошел с ошибкой
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 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>rejected</pg_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 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_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 от мерчанта

Если 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_ 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_amount=500' \
--form 'pg_currency=KZT' \
--form 'pg_net_amount=482.5' \
--form 'pg_ps_amount=500' \
--form 'pg_ps_full_amount=500' \
--form 'pg_ps_currency=KZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=0' \
--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}}' \
--form 'pg_payment_method=bankcard'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>rejected</pg_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_amount=500' \
--form 'pg_currency=KZT' \
--form 'pg_net_amount=482.5' \
--form 'pg_ps_amount=500' \
--form 'pg_ps_full_amount=500' \
--form 'pg_ps_currency=KZT' \
--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}}' \
--form 'pg_payment_method=bankcard'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_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 на стороне мерчанта должен быть общедоступным, без авторизации.

Если сервер мерчанта недоступен в момент вызова Result URL или ответ от сервера был не со статусом 200, 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_amount Сумма выставленного счета в валюте pg_currency
Пример: 500
string
pg_currency Валюта выставленного счета, совпадает с pg_currency в момент инициализации платежа
Пример: KZT
string
pg_net_amount Сумма счета (в валюте `pg_ps_currency), выставленного в ПС. Поле может отсутствовать в случае неудачного платежа
Пример: 482.5
string
pg_ps_amount Полная сумма (в валюте pg_ps_currency), которую заплатил покупатель с учетом всех комиссий. Поле может отсутствовать в случае неудачного платежа.
Пример: 500
string
pg_ps_full_amount Полная сумма (в валюте pg_ps_currency), которую заплатил покупатель с учетом всех комиссий. Поле может отсутствовать в случае неудачного платежа


Пример: 500
string
pg_ps_currency Валюта, в которой был произведен платеж в платежной системе. Поле может отсутствовать в случае неудачного платежа
Пример: KZT
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_id Опциональный параметр. ID карты для оплаты сохраненной картой
Пример: 1234
string
pg_card_pan Маскированный номер карты (часть цифр номера карты скрыты). Этот параметр передается только в случае успешной оплаты банковской картой
Пример: 5483-18XX-XXXX-0293
string
Параметры мерчанта Все поля, переданные с веб-сайта мерчанта, не имеющие префикса pg_ string
pg_salt Случайная строка
Пример: some random string
string
pg_sig Подпись запроса string
pg_discount_percent Информация о проценте скидки, отправляется если скидка присутствует
Пример: 1.0
string
pg_discount_amount Информация о сумме скидки, отправляется если скидка присутствует
Пример: 5
string
pg_payment_method Метод платежа
ЗначениеМетод платежа
walletЭлектронные деньги
internetbankИнтернет-банкинг
otherТерминалы
bankcardБанковские карты
cashТочки приема платежей
mobile_commerceМобильная коммерция

Пример: bankcard
string
pg_card_exp Дата истечения срока карты
Пример: 03/23
string
pg_card_owner Имя держателя карты
Пример: Ivan Ivanov
string
pg_card_brand Код бренда карты
Пример: VI
string


Возврат покупателя на сайт мерчанта

После завершения платежа в 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}} или {{failure_url}}

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


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

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

Запрос

curl --location --request POST 'https://api.paybox.money/get_status2.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_payment_id=4567617' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status2.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_status2.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_payment_id=4567775' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status2.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_status2.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_status2.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 Показывает результат выполнения запроса
СтатусОписание
okЗапрос прошел успешно
errorЗапрос прошел с ошибкой
string
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money Служит ключом для всей дальнейшей работы с транзакцией integer
pg_transaction_status Статус платежа
СтатусОписание
partialНовый платеж
pendingОжидание плательщика или платежной системы
refundedПо платежу прошел возврат
revokedПо платежу прошла отмена
okПлатеж успешно завершен
failedПлатеж в ошибке
incompleteИстекло время жизни платежа
string
pg_testing_mode Enum:0 1
0 - платеж в боевом режиме 1 - платеж в тестовом режиме
integer
pg_create_date Дата и время создания платежной транзакции datetime
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_failure_code Код ошибки integer
pg_failure_description Описание ошибки string
pg_amount Сумма заказа number
pg_currency Валюта заказа string
pg_salt Случайная строка 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 Показывает результат выполнения запроса
СтатусОписание
okЗапрос прошел успешно
errorЗапрос прошел с ошибкой
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_status2.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_payment_id=12345' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status2.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_status2.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_payment_id=4567617' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status2.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_status2.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_payment_id=4567775' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status2.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_status2.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_status2.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 Показывает результат выполнения запроса
СтатусОписание
okЗапрос прошел успешно
errorЗапрос прошел с ошибкой
string
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money Служит ключом для всей дальнейшей работы с транзакцией integer
pg_transaction_status Статус платежа
СтатусОписание
partialНовый платеж
pendingОжидание плательщика или платежной системы
refundedПо платежу прошел возврат
revokedПо платежу прошла отмена
okПлатеж успешно завершен
failedПлатеж в ошибке
incompleteИстекло время жизни платежа
string
pg_testing_mode Enum:0 1
0 - платеж в боевом режиме 1 - платеж в тестовом режиме
integer
pg_create_date Дата и время создания платежной транзакции datetime
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_failure_code Код ошибки integer
pg_failure_description Описание ошибки string
pg_amount Сумма заказа number
pg_currency Валюта заказа string
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_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'get_status2.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_status2.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 Показывает результат выполнения запроса
СтатусОписание
okЗапрос прошел успешно
errorЗапрос прошел с ошибкой
string
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money Служит ключом для всей дальнейшей работы с транзакцией integer
pg_transaction_status Статус платежа
СтатусОписание
partialНовый платеж
pendingОжидание плательщика или платежной системы
refundedПо платежу прошел возврат
revokedПо платежу прошла отмена
okПлатеж успешно завершен
failedПлатеж в ошибке
incompleteИстекло время жизни платежа
string
pg_testing_mode Enum:0 1
0 - платеж в боевом режиме 1 - платеж в тестовом режиме
integer
pg_create_date Дата и время создания платежной транзакции datetime
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_failure_code Код ошибки integer
pg_failure_description Описание ошибки string
pg_amount Сумма заказа number
pg_currency Валюта заказа string
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_receipt_positions[0][count]
Пример: 2
string
pg_receipt_positions[0][name]
Пример: Коврик для мыши
string
pg_receipt_positions[0][tax_type]
Пример: 3
string
pg_receipt_positions[0][price]
Пример: 1000
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_receipt_positions[0][count]
Пример: 2
string
pg_receipt_positions[0][name]
Пример: Коврик для мыши
string
pg_receipt_positions[0][tax_type]
Пример: 3
string
pg_receipt_positions[0][price]
Пример: 1000
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 заказа в системе мерчанта. Рекомендуется уникальное, монотонно возрастающее значение.
Пример: order_1234
string
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 Показывает результат выполнения запроса
СтатусОписание
okЗапрос прошел успешно
errorЗапрос прошел с ошибкой
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 запрос для мерчанта

В случае успешной выплаты, будет вызван URL, указанный в pg_post_link

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

Post link на стороне мерчанта должен быть общедоступным, без авторизации.

URL запроса

POST {{post_link}}

Headers
Content-Type Value
Content-Type application/x-www-form-urlencoded
Поля запроса
Название Описание Тип
pg_payment_id ID транзакции в системе PayBox.money. integer
pg_order_id ID заказа в системе мерчанта string
pg_card_hash Маскированный PAN карты string
pg_status Статус операции. Enum:ok, error string
pg_balance Баланс после проведения платежа string
pg_payment_amount Сумма выплаты string
pg_to_pay Сумма выплаты + комиссия string
pg_merchant_id ID мерчанта string
pg_payment_date Дата выплаты string
pg_salt Случайная строка, состоящая из произвольных цифр и латинских букв.
Пример: some random string
string
pg_sig Подпись запроса string


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

Partial - Платеж создан

Запрос

curl --location --request POST 'https://api.paybox.money/get_status2.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_order_id=00102' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status2.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_status2.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_order_id=00102' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status2.php;{{paybox_merchant_id}};4567775;00102;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>511194</pg_payment_id>
    <pg_transaction_status>ok</pg_transaction_status>
    <pg_can_reject>0</pg_can_reject>
    <pg_captured>1</pg_captured>
    <pg_create_date>2021-08-26 11:52:25</pg_create_date>
    <pg_salt>41F5ZyqcOabTG5u7</pg_salt>
    <pg_sig>34484775bd62986753429d6af57e94eb</pg_sig>
</response>

Pending - Платеж в процессе выплаты

Запрос

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

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>511194</pg_payment_id>
    <pg_transaction_status>ok</pg_transaction_status>
    <pg_can_reject>0</pg_can_reject>
    <pg_captured>1</pg_captured>
    <pg_create_date>2021-08-26 11:52:25</pg_create_date>
    <pg_salt>41F5ZyqcOabTG5u7</pg_salt>
    <pg_sig>34484775bd62986753429d6af57e94eb</pg_sig>
</response>

Failed - Платеж в ошибке

Запрос

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

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>511180</pg_payment_id>
    <pg_transaction_status>failed</pg_transaction_status>
    <pg_can_reject>0</pg_can_reject>
    <pg_captured>0</pg_captured>
    <pg_create_date>2021-08-26 11:53:12</pg_create_date>
    <pg_failure_code>5</pg_failure_code>
    <pg_failure_description>Transaction declined</pg_failure_description>
    <pg_salt>VeJEycvwsTn74VEA</pg_salt>
    <pg_sig>aa65c7786f5cba0cd9e6a452bfbcc7a2</pg_sig>
</response>

Failed - Платеж не найден

Запрос

curl --location --request POST 'https://api.paybox.money/get_status2.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_order_id=00102' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status2.php;{{paybox_merchant_id}};4567775;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>

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

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

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

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

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'get_status2.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_status2.php

Поля запроса
Название Описание Тип
pg_merchant_id
required
Идентификатор мерчанта в PayBox.money. Выдается при подключении. string
pg_order_id
required
Идентификатор платежа в системе мерчанта. Будьте внимательны, при запросе по order_id магазин должен самостоятельно следить за уникальностью данного параметра иначе будет выдана информация для последнего платежа с данным order_id для данного магазина
Пример: 00102
string
pg_salt
required
Случайная строка
Пример: some random string
string
pg_sig
required
Подпись запроса string
Параметры ответа
Название Описание Тип
pg_status Показывает результат выполнения запроса
СтатусОписание
okЗапрос прошел успешно
errorЗапрос прошел с ошибкой
string
pg_payment_id Уникальный идентификатор платежной транзакции в PayBox.money Служит ключом для всей дальнейшей работы с транзакцией integer
pg_transaction_status Статус платежа
СтатусОписание
partialНовый платеж
pendingОжидание плательщика или платежной системы
okПлатеж успешно завершен
failedПлатеж в ошибке
incompleteИстекло время жизни платежа
string
pg_failure_code Код ошибки string
pg_failure_description Описание ошибки string
pg_can_reject Enum:0 1.
Данное поле не показывает важных вещей для выплаты
integer
pg_testing_mode Enum:0 1
0 - платеж в боевом режиме 1 - платеж в тестовом режиме
integer
pg_captured Enum:0 1
Данное поле не показывает важных вещей для выплаты
integer
pg_create_date Дата и время создания платежной транзакции datetime
pg_salt Случайная строка string
pg_sig Подпись запроса string


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

URL запроса

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

Поля запроса
Название Описание Тип
pg_merchant_id
required
Merchant ID в системе Paybox. integer
pg_payment_id ID транзакции в системе Paybox. integer
pg_salt
required
Случайная строка, состоящая из произвольных цифр и латинских букв string
pg_sig
required
Цифровая подпись запроса string
pg_order_id
required
ID заказа в системе продавца. integer
Параметры ответа

Параметры ответа на успешный запрос:

Название Валидация Описание
pg_payment_id integer id транзакции в системе PayBox
pg_merchant_id integer merchant_id в системе PayBox
pg_status string Enum: "success" "error" "process". Статус транзакции. Process - это исключительный вариант только в случае, когда банк некорректно ответил, и мы не финализировали статус перевода на своей стороне
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_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 заказа в системе мерчанта. Рекомендуется уникальное, монотонно возрастающее значение.
Пример: order_1234
string
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_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 Статус запроса
СтатусОписание
okЗапрос завершен успешно
errorЗапрос завершился с ошибкой
processФинальный статус выплаты нужно получить через запрос
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_error_code Код ошибки integer
pg_error_description Описание ошибки string
pg_salt Случайная строка, состоящая из произвольных цифр и латинских букв string
pg_sig Подпись запроса string


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

В случае успешной выплаты, будет вызван URL, указанный в pg_post_link

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

Post link на стороне мерчанта должен быть общедоступным, без авторизации.

URL запроса

POST {{post_link}}

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


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

Partial - Платеж создан

Запрос

curl --location --request POST 'https://api.paybox.money/get_status2.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_order_id=00102' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status2.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_status2.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_order_id=00102' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status2.php;{{paybox_merchant_id}};4567775;00102;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>511194</pg_payment_id>
    <pg_transaction_status>ok</pg_transaction_status>
    <pg_can_reject>0</pg_can_reject>
    <pg_captured>1</pg_captured>
    <pg_create_date>2021-08-26 11:52:25</pg_create_date>
    <pg_salt>41F5ZyqcOabTG5u7</pg_salt>
    <pg_sig>34484775bd62986753429d6af57e94eb</pg_sig>
</response>

Pending - Платеж в процессе выплаты

Запрос

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

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>511194</pg_payment_id>
    <pg_transaction_status>ok</pg_transaction_status>
    <pg_can_reject>0</pg_can_reject>
    <pg_captured>1</pg_captured>
    <pg_create_date>2021-08-26 11:52:25</pg_create_date>
    <pg_salt>41F5ZyqcOabTG5u7</pg_salt>
    <pg_sig>34484775bd62986753429d6af57e94eb</pg_sig>
</response>

Failed - Платеж в ошибке

Запрос

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

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>511180</pg_payment_id>
    <pg_transaction_status>failed</pg_transaction_status>
    <pg_can_reject>0</pg_can_reject>
    <pg_captured>0</pg_captured>
    <pg_create_date>2021-08-26 11:53:12</pg_create_date>
    <pg_failure_code>5</pg_failure_code>
    <pg_failure_description>Transaction declined</pg_failure_description>
    <pg_salt>VeJEycvwsTn74VEA</pg_salt>
    <pg_sig>aa65c7786f5cba0cd9e6a452bfbcc7a2</pg_sig>
</response>

Failed - Платеж не найден

Запрос

curl --location --request POST 'https://api.paybox.money/get_status2.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_order_id=00102' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status2.php;{{paybox_merchant_id}};4567775;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>

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

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

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

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

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'get_status2.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_status2.php

Поля запроса
Название Описание Тип
pg_merchant_id
required
Идентификатор мерчанта в PayBox.money. Выдается при подключении. string
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 Статус платежа
СтатусОписание
partialНовый платеж
pendingОжидание плательщика или платежной системы
okПлатеж успешно завершен
failedПлатеж в ошибке
incompleteИстекло время жизни платежа
string
pg_failure_code Код ошибки string
pg_failure_description Описание ошибки string
pg_can_reject Enum:0 1.
Данное поле не показывает важных вещей для выплаты
integer
pg_testing_mode Enum:0 1
0 - платеж в боевом режиме 1 - платеж в тестовом режиме
integer
pg_captured Enum:0 1
Данное поле не показывает важных вещей для выплаты
integer
pg_create_date Дата и время создания платежной транзакции datetime
pg_salt Случайная строка string
pg_sig Подпись запроса string


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

URL запроса

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

Поля запроса
Название Описание Тип
pg_merchant_id
required
Merchant ID в системе Paybox. integer
pg_payment_id ID транзакции в системе Paybox. integer
pg_salt
required
Случайная строка, состоящая из произвольных цифр и латинских букв string
pg_sig
required
Цифровая подпись запроса string
pg_order_id
required
ID заказа в системе продавца. integer
Параметры ответа

Параметры ответа на успешный запрос:

Название Валидация Описание
pg_payment_id integer id транзакции в системе PayBox
pg_merchant_id integer merchant_id в системе PayBox
pg_status string Enum: "success" "error" "process". Статус транзакции. Process - это исключительный вариант только в случае, когда банк некорректно ответил, и мы не финализировали статус перевода на своей стороне
pg_order_id integer Номер заказа
pg_salt string Случайная строка, состоящая из произвольных цифр и латинских букв
pg_sig string Сигнатура


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

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

Запрос на выплату

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

$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 Статус запроса
СтатусОписание
okЗапрос завершен успешно
errorЗапрос завершился с ошибкой
processФинальный статус выплаты нужно получить через запрос
string
pg_balance Баланс мерчанта в системе Paybox number
pg_payment_amount Сумма платежа number
pg_payment_date Дата и время проведения платежа datetime
pg_error_code Код ошибки integer
pg_error_description Описание ошибки string
pg_salt Случайная строка, состоящая из произвольных цифр и латинских букв string
pg_sig Подпись запроса string


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

Partial - Платеж создан

Запрос

curl --location --request POST 'https://api.paybox.money/get_status2.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_order_id=00102' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status2.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_status2.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_order_id=00102' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status2.php;{{paybox_merchant_id}};4567775;00102;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>511194</pg_payment_id>
    <pg_transaction_status>ok</pg_transaction_status>
    <pg_can_reject>0</pg_can_reject>
    <pg_captured>1</pg_captured>
    <pg_create_date>2021-08-26 11:52:25</pg_create_date>
    <pg_salt>41F5ZyqcOabTG5u7</pg_salt>
    <pg_sig>34484775bd62986753429d6af57e94eb</pg_sig>
</response>

Pending - Платеж в процессе выплаты

Запрос

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

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>511194</pg_payment_id>
    <pg_transaction_status>ok</pg_transaction_status>
    <pg_can_reject>0</pg_can_reject>
    <pg_captured>1</pg_captured>
    <pg_create_date>2021-08-26 11:52:25</pg_create_date>
    <pg_salt>41F5ZyqcOabTG5u7</pg_salt>
    <pg_sig>34484775bd62986753429d6af57e94eb</pg_sig>
</response>

Failed - Платеж в ошибке

Запрос

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

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>511180</pg_payment_id>
    <pg_transaction_status>failed</pg_transaction_status>
    <pg_can_reject>0</pg_can_reject>
    <pg_captured>0</pg_captured>
    <pg_create_date>2021-08-26 11:53:12</pg_create_date>
    <pg_failure_code>5</pg_failure_code>
    <pg_failure_description>Transaction declined</pg_failure_description>
    <pg_salt>VeJEycvwsTn74VEA</pg_salt>
    <pg_sig>aa65c7786f5cba0cd9e6a452bfbcc7a2</pg_sig>
</response>

Failed - Платеж не найден

Запрос

curl --location --request POST 'https://api.paybox.money/get_status2.php' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_order_id=00102' \
--form 'pg_salt=ijoi894j4ik39lo9' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'get_status2.php;{{paybox_merchant_id}};4567775;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>

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

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

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

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

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'get_status2.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_status2.php

Поля запроса
Название Описание Тип
pg_merchant_id
required
Идентификатор мерчанта в PayBox.money. Выдается при подключении. string
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 Статус платежа
СтатусОписание
partialНовый платеж
pendingОжидание плательщика или платежной системы
okПлатеж успешно завершен
failedПлатеж в ошибке
incompleteИстекло время жизни платежа
string
pg_failure_code Код ошибки string
pg_failure_description Описание ошибки string
pg_can_reject Enum:0 1.
Данное поле не показывает важных вещей для выплаты
integer
pg_testing_mode Enum:0 1
0 - платеж в боевом режиме 1 - платеж в тестовом режиме
integer
pg_captured Enum:0 1
Данное поле не показывает важных вещей для выплаты
integer
pg_create_date Дата и время создания платежной транзакции datetime
pg_salt Случайная строка string
pg_sig Подпись запроса string


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

URL запроса

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

Поля запроса
Название Описание Тип
pg_merchant_id
required
Merchant ID в системе Paybox. integer
pg_payment_id ID транзакции в системе Paybox. integer
pg_salt
required
Случайная строка, состоящая из произвольных цифр и латинских букв string
pg_sig
required
Цифровая подпись запроса string
pg_order_id
required
ID заказа в системе продавца. integer
Параметры ответа

Параметры ответа на успешный запрос:

Название Валидация Описание
pg_payment_id integer id транзакции в системе PayBox
pg_merchant_id integer merchant_id в системе PayBox
pg_status string Enum: "success" "error" "process". Статус транзакции. Process - это исключительный вариант только в случае, когда банк некорректно ответил, и мы не финализировали статус перевода на своей стороне
pg_order_id integer Номер заказа
pg_salt string Случайная строка, состоящая из произвольных цифр и латинских букв
pg_sig string Сигнатура


На банковский счет (IBAN)

Выплата на банковский счет KZT

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

URL запроса

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

Поля запроса
Название Описание Тип
pg_amount
required
Сумма перевода.
Пример: 10
number
pg_merchant_id
required
Merchant ID в системе PayBox.money integer
pg_order_id
required
ID заказа в системе мерчанта. Рекомендуется уникальное, монотонно возрастающее значение.
Пример: 1234
integer
pg_recipient_iban
required
Номер счета IBAN получателя
Пример: KZ123412341234123412
string(20)
pg_recipient_iin
required
ИИН получателя
Пример: 761223455678
string(12)
pg_recipient_name
required
Наименование получателя
Пример: ИВАНОВ ИВАН
string
pg_recipient_kbe
required
КБе получателя
Пример: 19
integer(2)
pg_knp
required
КНП получателя
Пример: 119
integer(3)
pg_bank_bik
required
БИК банка получателя
Пример: KZZSAE
string(6)
pg_description *Описание платежа
Пример: Описание платежа
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_payment_amount Сумма платежа number
pg_payment_date Дата и время проведения платежа datetime
pg_salt Случайная строка, состоящая из произвольных цифр и латинских букв string
pg_sig Подпись запроса string


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

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

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

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

Post link на стороне мерчанта должен быть общедоступным, без авторизации.

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_status Статус операции. Enum:ok, error string
pg_salt Случайная строка, состоящая из произвольных цифр и латинских букв.
Пример: some random string
string
pg_sig Подпись запроса string


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

Ok - Платеж успешен

Запрос

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

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>511194</pg_payment_id>
    <pg_transaction_status>ok</pg_transaction_status>
    <pg_can_reject>0</pg_can_reject>
    <pg_captured>1</pg_captured>
    <pg_create_date>2021-08-26 11:52:25</pg_create_date>
    <pg_salt>41F5ZyqcOabTG5u7</pg_salt>
    <pg_sig>34484775bd62986753429d6af57e94eb</pg_sig>
</response>

Pending - Платеж в процессе выплаты

Запрос

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

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>511194</pg_payment_id>
    <pg_transaction_status>ok</pg_transaction_status>
    <pg_can_reject>0</pg_can_reject>
    <pg_captured>1</pg_captured>
    <pg_create_date>2021-08-26 11:52:25</pg_create_date>
    <pg_salt>41F5ZyqcOabTG5u7</pg_salt>
    <pg_sig>34484775bd62986753429d6af57e94eb</pg_sig>
</response>

Failed - Платеж в ошибке

Запрос

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

Ответ

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>511180</pg_payment_id>
    <pg_transaction_status>failed</pg_transaction_status>
    <pg_can_reject>0</pg_can_reject>
    <pg_captured>0</pg_captured>
    <pg_create_date>2021-08-26 11:53:12</pg_create_date>
    <pg_failure_code>5</pg_failure_code>
    <pg_failure_description>Transaction declined</pg_failure_description>
    <pg_salt>VeJEycvwsTn74VEA</pg_salt>
    <pg_sig>aa65c7786f5cba0cd9e6a452bfbcc7a2</pg_sig>
</response>

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

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

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

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

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'get_status2.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_status2.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_failure_code Код ошибки string
pg_failure_description Описание ошибки string
pg_can_reject Enum:0 1.
Данное поле не показывает важных вещей для выплаты
integer
pg_testing_mode Enum:0 1
0 - платеж в боевом режиме 1 - платеж в тестовом режиме
integer
pg_captured Enum:0 1
Данное поле не показывает важных вещей для выплаты
integer
pg_create_date Дата и время создания платежной транзакции datetime
pg_amount Сумма заказа number
pg_currency Валюта заказа 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_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>

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

Запрос

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>

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

$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_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>

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

Запрос

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>

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

$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/api/balance_status' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'balance_status;{{paybox_merchant_id}};some random string;{{secret_key}}'

Ответ

<?xml version="1.0" encoding="UTF-8"?>
<response>
 <pg_balance>0.00</pg_balance>
 <pg_status>ok</pg_status>
 <pg_salt>osWRT1FtWr</pg_salt>
 <pg_sig>9087fd0c7a26334f53f83f0bd61e6b80</pg_sig>
</response>

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

$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, 'balance_status');
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/balance_status

Поля запроса
Название Описание Тип
pg_merchant_id
required
Merchant ID в системе PayBox.money. integer
pg_salt
required
Случайная строка, состоящая из произвольных цифр и латинских букв
Пример: some random string
string
pg_sig
required
Подпись запроса string
Параметры ответа
Название Описание Тип
pg_balance Баланс number
pg_status Статус запроса string
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_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


Подтверждение 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


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

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

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

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

Запрос

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>approved</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>approved</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 от мерчанта

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

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

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

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

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

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

Post link на стороне мерчанта должен быть общедоступным, без авторизации.

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


Коды ошибок

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