Developers

API and connection documentation

Вспомогательные запросы:

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

Если магазин хочет, чтобы покупатель совершал выбор платежной системы на сайте магазина, он может либо самостоятельно вывести список доступных платежных систем и рассчитать окончательную цену для каждой ПС с учетом комиссий на основе имеющихся в договоре данных, либо получать актуальную информацию о списке доступных платежных систем и комиссиях в автоматическом режиме. В последнем случае магазину необходимо использовать прямой запрос к PayBox’у, описанный ниже. Магазин подает запрос на http://www.paybox.money/ps_list.php или https://www.paybox.money/ps_list.php, параметры передаются одним из методов прямого запроса Максимальное время ожидания ответа – 30 секунд. Список параметров запроса:
Параметр Значение по умолчанию Описание
pg_merchant_id (string[16]) идентификатор продавца
pg_amount (decimal) сумма счета в системе продавца в валюте pg_currency.
pg_currency KZT (string[3]) валюта счета
pg_testing_mode 0 Флаг, принимает значение 0 или 1.
pg_salt Случайная строка
pg_sig Подпись

Пример GET запроса:

https://api.paybox.money/ps_list.php?pg_salt=123&pg_merchant_id=456&pg_amount=800.45&pg_currency=K ZT&pg_sig=aec5f9d237952f83bd05c602d287098d

Пример XML запроса (передается POST’ом в параметре pg_xml):


123
456
800.45
KZT
aec5f9d237952f83bd05c602d287098d

Ответ на запрос представляет собой XML (в кодировке utf-8), содержащий список доступных для этого магазина платежных систем и их атрибутов. Атрибутами являются сумма и валюта платежа, имя и описание ПС, а также список дополнительных параметров pg_required, обязательных для данной ПС. На данный момент обязательными полями могут быть поле pg_user_email для MONEYMAIL и BANKCARDPRU, которое передает адрес электронной почты для идентификации в системе платежных системах, pg_alfaclick_client_id для интернет банкинга ALFACLICK.Так же в ответе присутствует список полей, которые можно присылать дополнительно для платежных систем pg_additional. Магазин должен контролировать заполнение этих полей. Если выбрана платежная система, для которой есть обязательное к заполнению поле, но это поле не передано, то оно будет запрошено у покупателя на сайте paybox.money Пример ответа:

9938745
ok

MIXPLATMTS
Оплата со счета мобильного телефона МТС
offline
808.67
RUB
mobile


CASH
Наличные: Евросеть, ОСМП, Элекснет

offline


830.00


RUB

cash

ELECSNET
Elecsnet



EUROSET


Евросеть



QIWI QIWI




WEBMONEYRBANK

Система WebMoney


online

810.35<
/pg_amount_to_pay>

RUB

wallet


YANDEXMONEY

Система Яндекс-деньги

online

812.15


RUB

wallet
73daf9d237952f56bd05c602d2878dc2

В тэге response находится список платежных систем и подпись. Описание каждой платежной системы находится внутри тега pg_payment_system с уникальным идентификатором в атрибуте pg_name – именем платежной системы. Для каждой системы могут быть возвращены параметры:
Параметр Описание
pg_name (string[32]) имя платежной системы
pg_description (string[256]) описание системы, можно показывать пользователю
pg_payment_scenario Сценарий приема платежа: offline или online
pg_amount_to_pay (decimal) сумма, которую заплатит пользователь
pg_amount_to_pay_currency Валюта, которую заплатит пользователь
pg_category Категория платежной системы для удобства вывода списка ПС на стороне магазина. Возможные варианты 'wallet','mobile','cash','internetbank','bankcard','other','bank_side_card'
pg_required (string[32]) имя обязательного для заполнения параметра, если таковой имеется. Если обязательных параметров несколько, то каждый выводится в отдельной тэге pg_required.
pg_additional (string[32]) Не обязательный параметр аналогично pg_required
pg_sub_name (string[32]) имя платежной системы в группе
pg_sub_description (string[256]) описание платежной системы в группе, можно показывать пользователю вместо или в дополнение к pg_description платежной системы
pg_sub_payment_systems контейнер для платежных систем в группе
pg_salt Случайная строка
pg_sig Подпись

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


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

Магазин может запрашивать PayBox о статусе любого платежа, инициированного магазином. Это может быть полезно, например, в случае если вызов Result URL не был получен магазином из-за временного сбоя связи, а покупатель уже был передан на Success URL, однако статус транзакции магазину еще не известен. Магазин делает запрос на https://api.paybox.money/get_status.php или https://api.paybox.money/get_status.php, параметры передаются одним из методов прямого запроса (см. Способы прямого взаимодействия между магазином и PayBoxом). Максимальное время ожидания ответа – 30 секунд. Список параметров запроса (все параметры обязательные):

pg_merchant_id Идентификатор магазина
pg_payment_id или pg_order_id Идентификатор платежа в системе магазина или гейта Будьте внимательны, что при запросе по order_id магазин должен самостоятельно следить за уникальностью данного параметра иначе будет выдана информация для последнего платежа с данным order_id для данного магазина
pg_salt Случайная строка
pg_sig Подпись

Пример GET запроса:

https://api.paybox.money/get_status.php?pg_salt=123&pg_merchant_id=456&pg_payment_id=1234567&pg_si g=7f3af9d237952f56bd05c602d2879a3c

Пример XML запроса (передается POST’ом в параметре pg_xml):


123
456
1234567
7f3af9d237952f56bd05c602d2879a3c

Ответ на запрос представляет собой XML вида:


9865
ok
1234567
ok
1

2009-01-12 10:22:30


2009-01-12 10:25:07

RUSSIANSTANDARD>
/pg_payment_system<
CA


527594******4984


022380c107141f7e11f4271d7f6412a715222c32

014318

0

8380d43c7719e6ce48da0c79aa7eb2ba



9865
ok>/pg_status>

1234567


pending


1


2009-01-12 10:22:30


EUROSET,EUROPLAT,QIWI
8380d43c7719e6ce48da0c79aa7eb2ba

Здесь:

pg_status Результат обработки запроса (не путать со статусом платежа). ok, если платеж найден и действительно принадлежит данному магазину. error в любом другом случае.
pg_payment_id Внутренний идентификатор платежа в системе PayBox
pg_transaction_status Статус платежа.
pg_can_reject 0 или 1 – может ли платеж быть отменен. Значение 1 возможно только если статус платежа равен ok и платежная система предоставляет возможность отзыва платежа. В этом случае магазин может вызвать revoke.php как описано в следующем разделе.
pg_create_date Дата и время создания платежной транзакции
pg_result_date Дата и время успешного (ok) или неуспешного (failed) завершения платежа. Это дата вызова Result URL. Поле заполняется только когда статус транзакции равен ok, failed или revoked.
pg_revoke_date Дата и время отмены платежа. Поле заполняется только когда статус транзакции равен revoked.
pg_payment_system Идентификатор платежной системы, через которую прошел (должен пройти) платеж.
pg_accepted_payment_systems Список платежных систем, в которые удалось выставить платеж. Присутствует в случае статуса платежа pendind
pg_card_brand Бренд карты: CA – MasterCard и их продукты, VI – Visa, AX – AmericanExpress. Этот параметр передается только в случае успешной оплаты банковской картой.
pg_card_pan Маскированный номер карты (часть цифр номера карты скрыты). Этот параметр передается только в случае успешной оплаты банковской картой.
pg_card_hash Хешированный номер карты (номер карты, зашифрованный необратимым алгоритмом шифрования). Этот параметр передается только в случае успешной оплаты банковской картой.
pg_auth_code Код авторизации. Этот параметр передается только в случае успешной оплаты банковской картой.
pg_captured 0 или 1. Передается только в случае успешной оплаты банковской картой и показывает, был ли произведен клиринг в момент авторизации (что зависит только от настроек магазина). Если значение этого поля равно 0, магазин должен в последующем дать команду на клиринг (см. раздел Запрос на клиринг транзакций по банковским картам) или дождаться когда Платрон сделает это сам.
pg_overpayment Сумма переплаты в валюте платежной системы. Параметр передается только в случае когда клиент оплатил больше, чем от него ожидалось, и переплата разрешена в настройках магазина. Если оплачено ровно столько, сколько ожидалось, или статус транзакции отличен от ok, этот параметр не передается.
pg_failure_code Также как аналогичное поле в вызове Result URL (см. выше). Присутствует только в случае pg_transaction_status = failed или revoked.
pg_failure_description Также как аналогичное поле в вызове Result URL (см. выше). Присутствует только в случае pg_transaction_status = failed или revoked.
pg_error_description Описание ошибки выполнения запроса в случае pg_status=error (не путать с неудачной оплатой)
pg_salt Случайная строка
pg_sig Подпись

Все даты записываются в формате YYYY-MM-DD hh:mm:ss.


Запрос на клиринг транзакций по банковским картам

Магазин может самостоятельно запрашивать клиринг у банка через PayBox, если в банке настроено проведение платежей в два шага – авторизация и клиринг. В случае соответствующей настройки системы, после проведения транзакции, транзакция будет авторизована, но не рассчитана. Время максимальной задержки списания равно 5 дней и может регулироваться на стороне PayBox от 1 до 5 дней. Магазин делает запрос на http://api.paybox.money/do_capture.php или https://api.paybox.money/do_capture.php, параметры передаются одним из методов прямого запроса (см. Способы прямого взаимодействия между магазином и PayBoxом). Максимальное время ожидания ответа – 30 секунд. Список параметров запроса:


Пример XML запроса (передается POST’ом в параметре pg_xml):

pg_merchant_id Идентификатор магазина
pg_payment_id Идентификатор платежа
pg_long_record Длинная запись, см. дополнительной документации. Ее можно получить у сотрудников технического отдела.
pg_salt Случайная строка
pg_sig Подпись


123


456


1234567

7f3af9d237952f56bd05c602d2879a3c

Ответ на запрос представляет собой XML вида::

9865 ok 5e1af9d237952f56bd05c602d28704ac

Здесь:

pg_status Результат обработки запроса. ok, если запрос принят на обработку. По результату будет вызван Capture URL магазина. error в любом другом случае.
pg_error_description Описание ошибки в случае pg_status=error
pg_salt Случайная строка
pg_sig Подпись

Отмена платежа (полная или частичная)

Магазин может отменить успешно завершившийся платеж, если платежная система это позволяет (например, Банковские карты). В этом случае деньги возвращаются покупателю. Вернуть можно как полную сумму платежа, так и часть суммы. Можно делать несколько частичных возвратов до тех пор, пока общая сумма возвратов не достигнет суммы первоначального платежа. Отозвать платеж можно как из личного кабинета магазина, так и в автоматическом режиме путем вызова скрипта https://api.paybox.money/revoke.php или https://api.paybox.money/revoke.php. Параметры передаются одним из методов прямого запроса (см. Способы прямого взаимодействия между магазином и PayBoxом). Максимальное время ожидания ответа – 30 секунд. Список параметров запроса (все параметры обязательные):

pg_merchant_id Идентификатор магазина
pg_payment_id Идентификатор платежа
pg_refund_amount Сумма возврата. Если параметр не передан или передан 0, то возвращается вся сумма.
pg_salt Случайная строка
pg_sig Подпись

Пример GET запроса:

https://www.paybox.money/revoke.php?pg_salt=123&pg_merchant_id=456&pg_payment_id=1234567&pg_refun d_amount=800&pg_sig=6dd2a9d237952f56bd05c602d2872af8

Пример XML запроса (передается POST’ом в параметре pg_xml):

<
123
456
1234567
800
6dd2a9d237952f56bd05c602d2872af8

Ответ на запрос представляет собой XML следующего вида в случае успешного выполнения запроса на отмену платежа:


9865
ok
48caf9d237952f56bd05c602d28762da

В случае ошибки:


9865
error
490
this transaction can’t be revoked
4df0f9d237952f56bd05c602d2873ed0

Здесь:

pg_status Результат обработки запроса.
pg_error_code Код ошибки
pg_error_description Описание причины ошибки
pg_salt Случайная строка
pg_sig Подпись

Здесь:

pg_status Результат обработки запроса.
pg_error_code Код ошибки
pg_error_description Описание причины ошибки
pg_salt Случайная строка
pg_sig Подпись

Создание заявки на возврат денег

В случае если платежная система не позволяет вернуть деньги в автоматическом режиме, магазин может создать заявку на полную или частичную отмену успешно завершившегося платежа, если платежная система поддерживает возврат платежа через заявку на возврат. Вернуть можно как полную сумму платежа, так и часть суммы. Можно делать несколько частичных возвратов до тех пор, пока общая сумма возвратов не достигнет суммы первоначального платежа. Отозвать платеж можно как из личного кабинета магазина, так и в автоматическом режиме путем вызова скрипта https://api.paybox.moeny/create_refund_request.php или https://api.paybox.money/create_refund_request.php. Параметры передаются одним из методов прямого запроса (см. Способы прямого взаимодействия между магазином и PayBox). Максимальное время ожидания ответа – 30 секунд. В зависимости от того откуда пришли деньги и через какую систему они будут возвращаться используются разные параметры в запросе:

pg_merchant_id Идентификатор магазина
pg_payment_id Идентификатор платежа
pg_comment Причина возврата денег
pg_refund_amount Сумма возврата в валюте платежной системы. Если параметр не передан или передан 0, то возвращается вся сумма.
pg_salt Случайная строка
pg_sig Подпись

Пример GET запроса:

https://www.paybox.money/create_refund_request.php?pg_salt=sdasdasd&pg_merchant_id=243&pg_payment_i d=1172121&pg_comment=Сюда+вписываем+причину+возврата&pg_refund_amount=100&pg_sig=149b5 b52ab0b5ebfa9693910769bc222

Пример XML запроса (передается POST’ом в параметре pg_xml):


sdasdasd
243
1172121
Сюда вписываем причину возврата
100
149b5b52ab0b5ebfa9693910769bc222

Отмена счёта до оплаты

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

pg_merchant_id Идентификатор магазина
pg_salt Случайная строка
pg_sig Подпись

Пример GET запроса:

https://www.paybox.money/cancel.php?pg_salt=123&pg_merchant_id=456&pg_payment_id=1234567&pg_sig=6 28e300c3204c8ee398d878a5109b520

Пример XML запроса (передается POST’ом в параметре pg_xml):


123
456
1234567
628e300c3204c8ee398d878a5109b520

Ответ на запрос представляет собой XML следующего вида в случае успешного выполнения запроса на отмену платежа:


9865
ok
48caf9d237952f56bd05c602d28762da

В случае ошибки:


9865
error
200
transaction not found
ac08f9d237952f5bc4e5c602d2873481

Здесь:

pg_status Результат обработки запроса.
pg_error_code Код ошибки
pg_error_description Описание причины ошибки
pg_salt Случайная строка
pg_sig Подпись

Ответ «ok» означает, что заявка на отмену счёта принята. Счёт всё же может быть оплачен, если ПС, в которую был выставлен счёт, не поддерживает операции аннулирования счёта и не делает предварительных запросов на подтверждение возможности проведения платежа. Если ПС не поддерживает отмену счёта, но поддерживает возврат денежных средств (например, TRANSCRED), PayBox делает попытку отмены полученного платежа. В этом случае может взиматься дополнительная плата за операцию отмены платежа. Если передан параметр pg_payment_id, то выплата привязывается к транзакции и сумма выплаты не может превышать сумму прямой транзакции, в противном случае будет возвращена ошибка. Можно делать выплату по транзакции не на полную сумму. Или же несколько выплат, до тех пор пока общая сумма выплат не будет превышать сумму прямой транзакции.


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

Для получения списка контрактов с доступными по ним платежными системами нужно обратиться по адресу https://www.paybox.money/moneyback_system_list.php или http://www.paybox.money/moneyback_system_list.php и передать следующие параметры:

Название Описание
pg_saltpg_merchant_id Идентификатор магазина
pg_salt Случайная строка
pg_sig Подпись

Need a consultation?

Send an enquiry and our managers will contact you in 15 minutes.