Общение происходит с помощью postback-запросов (постбеков). После каждого запроса Клиента на ввод или вывод, ему отправляется постбек с результатом операции.
Внимание: Для смены часового пояса при отображении времени в транзакциях, в настройках (путь: Личный кабинет -> Настройки -> Настройки paykassma -> Часовой пояс) через запрос ТП Paykassma выставите требуемый часовой пояс. По умолчанию часовой пояс +08:00 PST Asia/Manila
Для принятия постбеков Вам необходимо реализовать отдельный путь, по которому Вы сможете получать постбеки. Они отправляются POST-запросом в JSON-формате.
Сервер Paykassma ожидает ответ в json {"status":"ok"} код ответа 200, в противном случае, при получении отличающегося ответа, Paykassma будет пересылать постбек с определенной периодичностью.
При отправке постбеков Paykassma также отправляет сигнатуру: специально сгенерированную хеш-строку, которая создается с использованием приватного ключа. Сама сигнатура вычисляется следующим образом:
$signature = sha1($postback_access_key . $postback_private_access_key . md5($transactions->toJson(JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE)));
в функцию sha1 передается строка, склеенная из трех параметров:
Параметр | Описание |
$postback_access_key | публичный ключ; |
$postback_private_access_key | приватный ключ; |
хеш от MD5-функции всего массива транзакций в JSON-формате |
В результате выполнения данного кода получается строка, которую невозможно подделать, не имея приватного ключа, который не передается в постбеках.
Клиент может сравнить сгенерированную сигнатуру с полученной сигнатурой от постбека и тем самым убедиться, что данные, которые пришли были реально отправлены, а не подделаны злоумышленником.
Тело запроса:
Наименование | Тип | Описание |
access_key | string | Ключ доступа, указывается в настройках личного кабинета ТП Paykassma |
signature | string | Подпись, по которой происходит проверка подлинности постбека. Внимание: принцип формирование подписи приводится ниже в отдельном пункте. |
label | string | Уникальный ID пользователя в системе клиента |
Stockpiling | object | Сконвертированная во все валюты сумма транзакций, участвующих в накоплении (одна и более транзакции). Конвертация осуществляется на основе открытых данных о курсах валют. Все валюты передаются с точностью до сотых долей, криптовалюты имеют 8 знаков в дробной части (стомиллионная точность). Передается в виде массива. Внимание: описание функционала накопления приводится ниже в отдельном пункте |
stockpiling_id | integer | Уникальный ID накопления |
transactions | array | Передается информация о совершённых транзакциях, учавствующих в накоплении (одна и более). |
Массив transactions:
Наименование | Тип | Описание |
amount | string | Сумма транзакции |
currency_code | string | Код валюты транзакции |
wallet_type | string | Платёжная система, в которой произведена транзакция |
transaction_id | string | Уникальный ID транзакции в Paykassma |
transaction_type | integer | Тип транзакции: 0 = автоматическая, 1 = отладочная, 2 = принудительная |
from | string или “null” | Уникальный идентификатор счета пользователя, с которого пришла оплата (при наличии информации) |
created_datetime | string | Дата создания транзакции |
activated_datetime | string | Дата активации транзакции |
custom_id | string или “null” | Передача полученного от клиента с плагина Идентификатор транзакции в системе Клиента. Внимание: Может быть «null», если параметр custom_transaction_id не был передан ранее. |
{ "access_key":"mrOYReXJphqo7lkL"// "signature":"dfsfrwe3344d", "label":1 "Stockpiling":{ "USD":80, "INR":6008.39, "EUR":72.86 }, "stockpiling_id":18, "transactions":[ { "amount":6008.39, "currency_code":"INR", "wallet_type":"paytm", "transaction_id":"15", "transaction_type":1, "from":85XXXX1369, "created_datetime":"2019-12-18 23:28:45", "activated_datetime":"2019-12-18 23:28:45", "custom_id":"3123123" } ] } |
Каждый постбек подписывается signature, она формируется следующим образом:
$data = [ ... ]; $data['signature'] = generateSignature($data); // return fa0ee1e2acf7f898635ec417491381c0a4f9d35c //send $data like json ... function generateSignature(array $data) { $privateKey = 'yourprivatekey'; ksort($data); $implode = self::multiImplode( ':', $data); return sha1($privateKey . md5($implode)); } function multiImplode($glue, $array): string { $finArray = []; foreach ($array as $val) { $finArray[] = is_array($val) ? self::multiImplode($glue, $val) : $val; } return implode($glue, $finArray); } |
Постбек вывода при использовании актуального запроса на вывод "https:
//api.{URL_server_Paykassma}/v2/withdrawal/create
"
Тело запроса:
Наименование | Тип | Описание |
withdrawal_id | string | Уникальный ID вывода |
status | integer | Доступные статусы вывода: |
comment | string | Комментарий, приходит вместе с html тэгами |
payment_system | string | Платежная система |
amount | double | Сумма |
currency_code | string | Валюта |
label | string | Уникальный идентификатор пользователя, для которого производится вывод |
account_number | string | Номер счета получателя |
account_name | string | Имя получателя счета |
account_email | string | Email получателя счета |
payments_details | JSON | |
payments_provider | string | Поставщик, который осуществляет электронный платеж, выбранным способом оплаты |
bank_details | JSON | |
bank_code | string | Уникальный идентификатор присваиваемый центральным банком страны |
branch_code | string | Код филиала (отделения) банка |
signature | string | Подпись постбека |
{ 'withdrawal_id' : '12345', 'status' : '1', 'comment' : 'comment', 'payment_system' : 'paytm', 'amount' : '1000', 'currency_code' : 'INR', 'label' : '125', 'account_number' : '123456789', 'account_name' : '', 'account_email' : '', 'payments_details': { 'payments_provider' : '', }, 'bank_details': { 'bank_code' : '', 'branch_code' : '', }, 'signature' : 'signature' } |
code | message |
---|---|
200 | ok |
400 | error receiving |
401 | error validation |
404 | not found http exception |
500 | not enough fields |
501 | empty postback |
502 | incorrect signature |
503 | data integrity error |
Постбек вывода при использовании неактуального запроса на вывод "https:
//api.{URL_server_Paykassma}/withdrawal/manual/create
"
Тело запроса:
Наименование | Тип | Описание |
id | integer | Уникальный ID вывода |
withdrawal_id | string | ID вывода в системе клиента |
wallet_type | string | Тип платёжной системы |
wallet_recipient | string | Номер кошелька получателя |
wallet_sender | string | Номер кошелька отправителя |
account_name | string | Имя держателя аккаунта |
account_number | string | Номер счета аккаунта |
string | Электронная почта того, кому выплачивают | |
amount | double | Сумма вывода. Имеет 2 знака после запятой для всех валют и 8 знаков для криптовалют. |
status | integer | Доступные статусы вывода: |
created_at | date | Дата и время создания |
updated_at | date | Дата и время обновления |
failed_reason | string | Причина неудачи. Данный параметр не передается, если статус 1 |
{ "id": 957, "withdrawal_id": "5165837", "wallet_type": "imps", "wallet_recipient": "123", "wallet_sender": "5125124", "account_name": "test", "account_number": "123", "email": "[email protected]" "amount": 1000.00, "status": 1, "created_at": "2021-02-16 12:23:34", "updated_at": "2021-02-26 17:22:43", "failed_reason": "test" "signature": "SIGNATURE" } |
Это новый действующий формат постбека. В отличии от прошлого он имеет одно тело как для ввода, так и для вывода.
Тело запроса:
Название | Тип | Описание | ||
---|---|---|---|---|
signature | строка | Подпись постбека | ||
wallet_type | строка | Тип платежной системы | ||
amount | сумма | Сумма транзакции | ||
currency | строка | Код валюты | ||
label | строка | Идентификатор пользователя | ||
converted_amount | массив | Сконвертированная во все валюты сумма транзакций, участвующих в накоплении (одна и более транзакции). Конвертация осуществляется на основе открытых данных о курсах валют. Все валюты передаются с точностью до сотых долей, криптовалюты имеют 8 знаков в дробной части (стомиллионная точность). Передается в виде массива. Внимание: описание функционала накопления приводится ниже в отдельном пункте Массив сконвертированных сумм во все доступные валюты | ||
direction | строка | Направление транзакции | ||
exchanger_identifier | строка | Уникальный идентификатор счета пользователя, с которого пришел запрос на транзакцию | ||
created_datetime | дата | Дата создания транзакции | ||
comment | строка | Комментарий, приходит вместе с html тэгами | ||
additional_data | массив | Данные от транзакции | ||
activated_datetime | дата | Дата активации транзакции | ||
access_key | строка | Ключ доступа, указывается в настройках личного кабинета ТП Paykassma | ||
stockpiling_id | числовой | Уникальный ID накопления | ||
transaction_id | строка | Уникальный ID транзакции в Paykassma | ||
transaction_type | числовой | Тип транзакции: 0 = автоматическая, 1 = отладочная, 2 = принудительная | ||
plugin_custom_order_id | строка | Уникальный идентификатор транзакции в системе клиента | ||
withdrawal_id | строка | Уникальный ID вывода | ||
withdrawal_status | числовой | Доступные статусы вывода: Processed = 1 Rejected = 5 | ||
account_number | строка | Номер счета получателя | ||
account_name | строка | Имя получателя | ||
account_email | строка | Электронная почта получателя | ||
bank_details | массив | |||
bank_code | строка | Уникальный идентификатор присваиваемый центральным банком страны | ||
branch_code | строка | Код филиала (отделения) банка |
{ "signature": "signature", "wallet_type": "wallet_type", "amount": 0.00, "currency": "INR", "label": "55", "converted_amount": [{ "USD":40.43,"INR":3327,"EUR":40.98,"IDR":625650.25,"MYR":190.71,"VND":988191.07,"SGD":57.43, "THB":1539,"NGN":17640.29,"TRY":751.48,"AED":148.51,"CAD":55.52,"AUD":64,"BDT":4276.41,"AFN":3531.25, "ALL":4807.24,"AMD":16333.46,"AOA":18109.34,"ARS":6179.09,"AWG":72.88,"AZN":68.73,"BAM":80.49,"BBD":80.86, "BGN":80.2,"BHD":15.24,"BIF":83303.64,"BMD":40.43,"BND":57.44,"BOB":279.23,"BRL":211.91,"BSD":40.43,"BTC":0.00209234], "direction": "ingoing", "created_at": "Y-m-d H:i:s +0", "exchanger_identifier": "16644654210253513", "comment": "test", "additional_data": { "activated_at": "Y-m-d H:i:s +0", "access_key": "mrOYReXJphqo7lkL", "stockpiling_id": 12, "transaction_id": "transaction_id", "transaction_type": 1, "plugin_custom_order_id": "plugin_custom_order_id", "withdrawal_id": "withdrawal_id", "withdrawal_status": 1, "account_number": "3143850122", "account_name": "autotest31438501226", "account_email": "[email protected]", "bank_details": [ "bank_code": "123", "branch_code": "321" ] } } |
Система позволяет повторно запросить информацию о постбеке на ввод или вывод, который был отправлен ранее. Подробности см. здесь