Перед началом работы с платежным шлюзом магазин настраивает параметры для выбора способов взаимодействия.

Параметры настройки магазина.

1. Инициализация платежа
2. Переход пользователя от магазина на платежный шлюз
3. Осуществление платежа/отказ от оплаты
4. Возвращение в магазин

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

Магазин осуществляет POST или GET запрос на платежный шлюз по адресу:

• https://engine.4pay.by/create/.
• https://gateway-sandbox-4pay.dev-4p.by/create/ ("песочница")
• https://gateway-test-4pay.dev-4p.by/create/ (тестовая среда)

со следующими обязательными и опциональными полями:

Параметры инициализации платежа.

Пример формы для вызова инициализации платежа.

<form method="POST" action="https://engine.4pay.by/create/">
    <input type="hidden" name="ap_storeid" value="57003"/>
    <input type="hidden" name="ap_order_num" value="1234"/>
    <input type="hidden" name="ap_amount" value="1000"/>
    <input type="hidden" name="ap_currency" value="BYN"/>
    <input type="hidden" name="ap_client_dt" value="1466602065"/>
    <input type="hidden" name="ap_invoice_desc" value="Телевизор марки Горизонт"/>
    <input type="hidden" name="ap_test" value="0"/>
    <input type="hidden" name="ap_signature" value="dab4a472561b49c355a80379f0a96a7efe2269bb7cc45b48ce9e587b6c2415de"/>
    <input type="submit" value="Оплатить">
</form>

2. Переход пользователя от магазина на платежный шлюз.

В случае корректности параметров Шлюз создает платеж и отправляет посетителя на страницу платежа. Если заказ создать не удалось, пользователю будет показана страница с ошибкой. Пример адреса для перенаправления пользователя: https://engine.4pay.by/1dd6-a5be-9077-1b80-e5da-ca81-1d0e-5726/

3. Осуществление платежа/отказ от оплаты.

На странице платежа пользователь вводит данные карты, либо отказывается от платежа.

4. Возвращение в магазин.

В зависимости от результата платежа пользователь будет возвращен:

• В случае успешного платежа на success url. При этом с помощью метода из success method будет осуществлена передача пераметров платежа в формате, указанным в success data format. Также будет осуществлен вызов result url, при этом методом result method будут переданы параметры для оповещения платежа в формате, указанным в result data format. Если в качестве result method указан email, то уведомление о платеже будет отправлено по электронной почте.
• В случае отказа от платежа/невозможности платежа на cancel url. При этом с помощью метода из cancel method будет осуществлена передача пераметров платежа в формате, указанным в cancel data format.

Пример адреса перенаправления пользователя после оплаты: http://testshop.tld/success/?ap_storeid=57003&ap_order_num=776175&ap_test=true&result=success&up_btn_name=super%21&ap_signature=dab4a472561b49c355a80379f0a96a7efe2269bb7cc45b48ce9e587b6c2415de

Параметры перенаправления.

Извещение о результатах оплаты или сторнировании оплаченного в ЕРИП счета.

Пример формы для вызова инициализации платежа.

{"ap_storeid":57003,"ap_order_num":776175,"ap_test":true,"ap_operation_status":"success","up_btn_name":"super","ap_signature":"ac9afb894a07a92fde3bc8638f475b1e3d6ca6f1780d1a711f11ba77f61236579"}

ap_storeid=57003&ap_order_num=776175&ap_test=true&ap_operation_status=cancel&up_btn_name=super%21&ap_signature=ac9afb894a07a92fde3bc8638f475b1e3d6ca6f1780d1a711f11ba77f61236579 

Хеш-сумма сообщения – последовательность байтов в шестнадцатиричном виде (0-9, A-F или a-f), рассчитанная хеш-функцией, указанной в конфигурации магазина.

Применяемые алгоритмы:

• SHA512 – по умолчанию;
• SHA256.

Алгоритм формирования:

1. Все поля сообщения в алфавитном порядке (сортировка по имени параметра) следования склеиваются в одну строку;
2. Далее в конец строки добавляется секретное слово точки обслуживания (Secret1 для запроса или Secret2 для ответа). Символ ";" является разделителем между параметрами, в конце и начале строки разделитель не ставится;
3. По полученной на предыдущем этапе строке выбранной хеш-функцией рассчитывается хеш-сумма;
4. Результат расчета является значением данного параметра. Сам порядок следования параметров в сообщении не регламентирован. Содержимое поля ap_signature не помещается в строку, по которой производится расчет хеш-суммы.

Пример формирования подписи:

<?php
function formSignature(/* array */ $data)
{
    $string = null;
    ksort($data, SORT_NATURAL);

    foreach ($data as $param => $value)
        $string .= $value . ';';

    $string .=  FOURPAY_SECRET1;
    $key =  hash(FOURPAY_HASH_METHOD, $string);

    return $key;
}
?>

Пример проверки подписи в ответе сервера:

<?php
function checkSignature(/* array */ $data)
{
    if (!isset($data['ap_signature']))
        return false;

    $addSignature = $data['ap_signature'];
    unset($data['ap_signature']);

    ksort($data, SORT_NATURAL);
    $string =  implode(';', $data) . ';' . FOURPAY_SECRET2;

    return hash(FOURPAY_HASH_METHOD, $string) == $addSignature;
}
?>

Поля с датой/время могут быть в следующих форматах:

• UNIX-время;
• YYYY-MM-DDThh:nn:ss.ZZZZZ, где:
  • YYYY-MM-DD – год-месяц-день;
  • hh:nn:ss – часы-минуты-секунды;
  • ZZZZZ – часовой пояс (в формате +hh:nn или –hh:nn), может отсутствовать, при отсутствии используется часовой пояс +03.00.

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

Формат данных — "json", кодовая страница — "uft8". Протокол обмена — "https", метод "POST".
Адрес API:

• https://api.4pay.by/v2/
• https://api-sandbox-4pay.dev-4p.by/v2/ ("песочница")
• https://api-test-4pay.dev-4p.by/v2/ (тестовый режим)

Базовые поля запроса

Создание платежа. Метод Register.

Параметры инициализации платежа.

Поля ответа.

Пример запроса.

{
    "ap_request":"Register",
    "ap_storeid":"600023",
    "ap_operation":"Sale",
    "ap_order_num":"566833",
    "ap_client_dt":"2025-01-31T12:47:40+00:00",
    "ap_amount":"10.01",
    "ap_currency":"BYN",
    "ap_invoice_desc":"Тестовый платеж",
    "ap_proto_ver":"1.3.0",
    "ap_lang":"ru",
    "ap_test":1,
    "ap_signature":"99a38fba8cdda3b651a6b05af86ae3b528f75745bd0d4f11884e3c5bf0b5ba4d59181fd7229d4dea41bf84694a55e6092edebb3bf583a4cc12254c9acf7a0987"
}

Пример ответа.

{
    "ap_storeid":"600023",
    "ap_store_desc":"Shop test",
    "ap_order_num":566833,
    "ap_status":"Success",
    "ap_result_code":0,
    "ap_result_text":"Выполнено успешно",
    "ap_server_dt":"2025-01-31T15:48:13+03:00",
    "ap_test":1,
    "ap_service_id":"a233-c47b-222d-8629-e04b-c82e-a714-7ea6",
    "ap_signature":"f634cff44f6c8cc83538917c1fc09eff3d62d12be14aced625a3d43d9975f3a05b6b01e2c69f454b1c19d2e2d0aa5d616bd69d201e2553671db199a26d356795"
}

Получение данных по операции. Метод OperationInfo.

Параметры запроса.

Поля ответа.

Пример запроса.

{
    "ap_request":"OperationInfo",
    "ap_order_num":"566833",
    "ap_storeid":"600023",
    "ap_client_dt":"2025-01-31T12:48:12+00:00",
    "ap_service_id":"a233-c47b-222d-8629-e04b-c82e-a714-7ea6",
    "ap_test":1,
    "ap_signature":"886204db9788a6ea85b2176cbbb150e96c0aad318a19821e535ba5bce1b5389e9edfb6d0a5f0b0b4954cc487ffc8e9339ba4b2b4a8b24e28257aca3a63509102"
}

Пример ответа.

{
    "ap_storeid":"600023",
    "ap_order_num":566833,
    "ap_operation":"Sale",
    "ap_oper_detail_state":"Preparation",
    "ap_status":"Success",
    "ap_result_code":0,
    "ap_result_text":"Выполнено успешно",
    "ap_server_dt":"2025-01-31T15:50:31+03:00",
    "ap_test":1,
    "ap_service_id":"a233-c47b-222d-8629-e04b-c82e-a714-7ea6",
    "ap_signature":"25b02cc90020fd67994625599f875d8c9ed469029d4be9c465ccc86c4ab7514a8c31a6ec3649b5f683c1e71b1830b0d989db39266e12a8a7e3560abd381e85d9"
}

Регистрация счета для оплаты ЕРИП. Метод EripAddInvoice.

Параметры инициализации платежа.

Поля ответа.

Пример запроса.

{"ap_request":"EripAddInvoice","ap_storeid":"120037","ap_order_num":"12","ap_client_dt":"Thu, 25 Jan 2018 13:20:41 +0300","ap_proto_ver":"1.3.0","ap_lang":"ru","ap_test":"1","ap_erip_service_no":"0","ap_amount":"10","ap_currency":"933","ap_invoice_desc":"Test Erip","ap_signature":"7bca35a812abcf11289c8881ef22cc6dea7d533ab535559cb653c9542d5649870c443ffc60551200d6f3e2ed4e8b500cf8325ba2ae47cd043d15eb9f06564a03"}

Пример ответа.

{"ap_storeid":"120037","ap_store_desc":"my test","ap_erip_service_no":"37011","ap_erip_invoice_id":"20506","ap_status":"Success","ap_result_code":0,"ap_result_text":"Выполнено успешно","ap_service_id":"0766-7bd7-ef69-7c26-6753-2fe3-b085-972f","ap_server_dt":"2018-01-25T13:46:28+03:00","ap_test":1,"ap_signature":"62e4e1e5df507dd1bfeae5a549707432b8365b5400180826a175352aa62a32266a044a74da06c4b57cab867a2c22391f537256377eb448add8f1a54737f718b8"}

Получение информации о статусе выставленного счета ЕРИП. Метод GetEripInvoiceInfo.

Параметры запроса получения информации о выставленном счете

Поля ответа.

Пример запроса.

{"ap_request":"GetEripInvoiceInfo","ap_client_dt":"2021-10-03T09:15:01+03:00","ap_test":"1","ap_proto_ver":"1.3.0","ap_storeid":"120037","ap_erip_invoice_id":"147","ap_erip_service_no":"23","ap_client_type":"brw","ap_client_inf":"Chrome 49.0.2623.112 (Mac OS X 10.7.2);","ap_client_ver":"1.0","ap_signature":"064d320884831c46f24368249fb1a958bcaafa5c689f5528c8db857068710760aa57b342972b91f09ced8394be4c8e36c8794ff9afcc6fbfc9bc3a98fd01a979"}

Пример ответа.

{"ap_storeid":"120037","ap_erip_invoice_id":"19745424","ap_erip_service_no":"23","ap_erip_invoice_state":"Pending","ap_status":"Success","ap_result_code":0,"ap_result_text":"Выполнено успешно","ap_server_dt":"2021-10-03T12:52:18+03:00","ap_test":1,"ap_service_id":"72ed-4a56-fb70-0bae-ab6b-0bcb-8c0a-66d1","ap_signature":"afd4282850bf1d7e76166e371bcebc04379e8134444039abb6788c8a1ec0316d9d30cef37f674676bf3485c5858de12e0137a5f894f9a4ebc9b618fdbf27f542"}

Документация по другим методам API предоставляется по запросу на 4pay.by.

Параметры уведомления

Пример уведомления.

{"ap_storeid":"100024","ap_order_num":5,"ap_test":1,"ap_notice_type":"EripTrnStatus","ap_erip_trn_state":"Paid","ap_amount":10,"ap_currency":"BYN","ap_erip_service_no":"6","ap_erip_invoice_id":"1207-6-770","ap_erip_trn_id":"173035295","ap_sp_trn_id":"6","ap_signature":"84f2e459c37a109b5194523176e05764523e206bcfaeee0701650779dcf826b0b3d45d2303fa0ccc708f0bb076d1e2dcdbc9f764d92926f5628ba3c00829e676"}

Данная версия протокола предназначена для использования агрегаторами платежей.

Формат данных — "json", кодовая страница — "uft8". Протокол обмена — "https", метод "POST".
Адрес API:

• https://api.4pay.by/v3/
• https://api-sandbox-4pay.dev-4p.by/v3/ ("песочница")
• https://api-test-4pay.dev-4p.by/v3/ (тестовый режим)

Каждое сообщение в системе подписывается с целью проверки целостности передаваемых данных и верификации абонента, сформировавшего сообщение. Непосредственно данные подписи помещаются в http заголовок сообщения. Для данной цели используются параметр http-заголовка «ap-content-signature», содержащий данные индекса ключа и подписи. Параметр «ap-content-signature» может отсутствовать в ответе, если запрос не содержит подписи или подпись некорректна.

Применяемые алгоритмы:

• HMAC-SHA256 – по умолчанию;
• HMAC-SHA512.

Формат подписи – «keyindex».«messageSign», где:

• keyindex – индекс ключа или пары ключей, используемых для подписи;
• messageSign – строка содержащая подпись;
• в качестве разделителя используется символ «.» (точка).

Пример формирования подписи:

<?php
function formSignature(/* array */ $data)
{
    $signature =
        ALGO_KEY //1 - HMAC-SHA256, 2-MAC-SHA512
        . '.'
        . hash_hmac('sha256', $data , FOURPAY_SECRET1);

    return $signature;
}
?>

function formSignature(message)
{
    const signature = '1.' //1 - HMAC-SHA256, 2-MAC-SHA512
      + CryptoJS.HmacSHA256(message, FOURPAY_SECRET1).toString(CryptoJS.enc.Hex);
    return signature;
}

Пример проверки подписи в ответе сервера:

<?php

public function checkSignature($data, $signature) : bool
{
    return ($this->formSignature($data) == $signature);
}

?>

Простые типы данных

Идентификаторы

Общие элементы сообщений

Элементы статуса

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

• ap_status;
• ap_result_code;
• ap_result_text.

Элементы финансовой операции

Сумма и валюта операции

Элементы данных пользователя

Структура stName, ФИО пользователя

Структура stAddress, адрес пользователя или организации

Дополнительные типы данных

Структура дополнительной суммы subAmount

Структура дополнительных данных по оплаченному счету АИС ЕРИП

Регистрация счета для оплаты ЕРИП. Метод AddEripInvoice.

Параметры инициализации платежа.

Поля ответа.

Пример запроса.

ap-content-signature: "1.c90851e727d4ca199cb66a7843187aec535b93c665a6267858175e67edbac10c"

{
    "ap_request":"AddEripInvoice",
    "ap_amount":"2.22",
    "ap_currency":933,
    "ap_invoice_desc":"Оплата 2.22",
    "ap_invoice_expire":"2025-01-30T13:12:45.841Z",
    "ap_epos_url_required":1,
    "up_terminal_id":"N5111112",
    "ap_erip_cust_account":"375291111111",
    "ap_erip_service_no":"70",
    "ap_order_num":123,
    "ap_client_dt":"2025-01-29T13:12:45.841Z",
    "ap_client_inf":"GTPOS",
    "ap_client_ver":"5.1.6",
    "ap_proto_ver":"3.5",
    "ap_lang":"ru",
    "ap_store_id":"600060",
    "ap_test":1
}

Пример ответа.

ap-content-signature: "1.52554f36f06504124de4a2287b1fbc6930723ffd2b5963fe1b183be554e28820"

{
    "ap_erip_service_no": "70",
    "ap_erip_invoice_id": "10275-8-379",
    "ap_epos_url": "https://pay.raschet.by/?...",
    "ap_epos_qr": "iVBORw0KGgo....CC",
    "ap_status": "Success",
    "ap_result_code": 0,
    "ap_result_text": "Выполнено успешно",
    "ap_server_dt": "2025-01-29T16:12:48+03:00",
    "ap_test": 1
}

Получение информации о статусе выставленного счета ЕРИП. Метод GetEripInvoiceInfo.

Параметры запроса получения информации о выставленном счете

Поля ответа.

Пример запроса.

ap-content-signature: "1.e716aca5b7ddc0c466db5ed426546fcc197f9ad72b8ffb978cc8739187cbf045"

{
   "ap_request":"GetEripInvoiceInfo",
   "ap_erip_service_no":"70",
   "ap_erip_invoice_id":"380",
   "ap_client_dt":"2025-01-29T14:07:23.599Z",
   "ap_client_inf":"GTPOS",
   "ap_client_ver":"5.1.6",
   "ap_proto_ver":"3.5",
   "ap_store_id":"600060",
   "ap_test":1,
   "up_terminal_id":"N5111112"
}

Примеры ответов.

ap-content-signature: "1.e6ad92feb2ba3395a990b11062dfc087b0b69aae070171f86b216a995e94908a"

{
    "ap_erip_trn_state":"Pending",
    "ap_erip_service_no":"70",
    "ap_erip_invoice_id":"27676845",
    "ap_status":"Success",
    "ap_result_code":0,
    "ap_result_text":"Выполнено успешно",
    "ap_server_dt":"2025-01-29T17:06:45+03:00",
    "ap_test":1
}

ap-content-signature: "1.17ad9еfeb2ba3395a920b11462df7087b0b49aaef7017cf86d216a695e94305b"

{
    "ap_erip_trn_state":"Paid",
    "ap_erip_service_no":"1070",
    "ap_erip_invoice_id":"42486569",
    "ap_erip_trn_id":"5641403970",
    "ap_status":"Success",
    "ap_result_code":0,
    "ap_result_text":"Выполнено успешно",
    "ap_server_dt":"2025-01-27T17:16:28+03:00",
    "ap_test":0
}

Документация по другим методам API предоставляется по запросу.