Общение происходит с помощью postback-запросов (постбеков). После каждого запроса Клиента на ввод или вывод, ему отправляется постбек с результатом операции.

Внимание: Для смены часового пояса при отображении времени в транзакциях, в настройках (путь: Личный кабинет -> Настройки -> Настройки paykassma -> Часовой пояс) через запрос ТП Paykassma выставите требуемый часовой пояс. По умолчанию часовой пояс +08:00 PST Asia/Manila

Прием postback (постбека)

Для принятия постбеков Вам необходимо реализовать отдельный путь, по которому Вы сможете получать постбеки. Они отправляются POST-запросом в JSON-формате.

Сервер Paykassma ожидает ответ в json {"status":"ok"} код ответа 200, в противном случае, при получении отличающегося ответа, Paykassma будет пересылать постбек с определенной периодичностью.

Ввод

Формирование сигнатуры (signature) на стороне клиента

При отправке постбеков 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-формате

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

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

Postback ввода

Тело запроса:

Наименование

Тип

Описание

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) на стороне клиента

Каждый постбек подписывается 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);
}

Postback вывода

Постбек вывода при использовании актуального запроса на вывод "https://api.{URL_server_Paykassma}/v2/withdrawal/create"

Тело запроса:

Наименование

Тип

Описание

string

integer

Доступные статусы вывода:
Processed = 1
Rejected = 5

string

Комментарий, приходит вместе с html тэгами

Уникальный идентификатор присваиваемый центральным банком страны

{
	'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

ok

error receiving

not enough fields

empty postback

incorrect signature

data integrity error

• В случае успеха, ожидаем от клиента http статус - 2XX. 
  Все 200-ые коды обязательно сопровождать "status" = "ok"
• В случае неудачи, ожидаем от клиента http статус отличный от 2XX (в зависимости от ошибки) и сообщение об ошибке.
      Например, error validation (не проходит валидацию), not enough fields (не достаточно полей). 

Постбек вывода при использовании неактуального запроса на вывод "https://api.{URL_server_Paykassma}/withdrawal/manual/create"

Тело запроса:

Наименование

Тип

Описание

id

withdrawal_id

string

ID вывода в системе клиента

wallet_type

string

Тип платёжной системы

wallet_recipient

string

Номер кошелька получателя

wallet_sender

string

Номер кошелька отправителя

account_name

string

Имя держателя аккаунта 

account_number

string

email

string

Электронная почта того, кому выплачивают

double

Сумма вывода. Имеет 2 знака после запятой для всех валют и 8 знаков для криптовалют.

integer

Доступные статусы вывода:
New = 0
Canceled = 2
Processed = 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"
}

Новый формат postback (постбека)

/Вывод

Формирование сигнатуры (signature) на стороне клиента

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

$signature = sha1($postback_access_key . $postback_private_access_key . md5($additionalDataArray->toJson(JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE)));

в функцию sha1 передается строка, склеенная из трех параметров:

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

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

Тело запроса:

{
      "signature":"signature",
      "wallet_type": "paytm_api",
      "amount": 13629,
      "currency_code": "INR",
      "label":"6424468",
      "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_datetime":"2023-06-30 10:59:24",
       "access_key":"access_key",
       "additional_data": 
            [ 
             {
              "activated_datetime":"2023-06-30 13:59:24",
              "exchanger_identifier":"97489343",
              "comment":"",
              "amount":"13628.5",
              "currency_code":"INR",
              "wallet_type":"paytm_api",
              "stockpiling_id":262402,
              "transaction_id":"160028076535305",
              "transaction_type":0,
              "plugin_custom_order_id":"6424468",
              "withdrawal_id":null,
              "withdrawal_status":null,
              "account_number":"",
              "account_name":"",
              "account_email":"",
              "bank_details": 
                {
                     "bank_code":"",
                     "branch_code":"" 
                }
             } 
                {...}
            ]
}

{
      "signature":"fcb57aabb9a7f46cd27f1b4249aeb9912bd49300",
      "wallet_type":"nagad_api",
      "amount":820,
      "currency_code":"BDT",
      "label":"autotest898404792700response_500",
      "converted_amount": 
        {
          "USD":7.56,"INR":620,"IDR":113212.08,"MYR":34.39,"VND":178667.64,"SGD":10,
          "THB":257.14,"NGN":5947.67,"TRY":203.5,"AED":27.75,"CAD":9.93,"AUD":11.07,"BDT":820,"AFN":647.27,
          "ALL":681.27,"AMD":2946.58,"AOA":6231.79,"ARS":2025.9,"AWG":13.62,"AZN":12.84,"BAM":13.17,"BBD":15.11,
          "BGN":13.17,"BHD":2.85,"BIF":21376.13,"BMD":7.56,"BND":10.02,"BOB":52.24,"BRL":36.2,"BSD":7.56,"BTC":0.00025009
         },
      "direction":"outgoing",
      "created_datetime":"2023-07-20 08:09:01",
      "access_key":"Neiwk12Mdk2pdi1Jdi",
      "additional_data": 
       [
        {
          "activated_datetime":"",
          "exchanger_identifier":"",
          "comment":"autotest approve by file",
          "amount":"820",
          "currency_code":"BDT",
          "wallet_type":"nagad_api",
          "stockpiling_id":null,
          "transaction_id":"",
          "transaction_type":null,
          "plugin_custom_order_id":"",
          "withdrawal_id":"autotest984047927037",
          "withdrawal_status":1,
          "account_number":"5632221204",
          "account_name":"autotest983948600573",
          "account_email":"",
          "bank_details":
            {
               "bank_code":null,
               "branch_code":null
             }
        }
       ]
}

Получение информации о ранее отправленном постбеке

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

< Вернуться на главную