Калькулятор комиссии

Протокол POST-API

Платежная платформа PayKeeper с помощью POST-API протокола позволяет провести интеграцию с любой по сложности информационной системой. Это может быть биллинг, кастомизированная CMS, любая малораспространенная CMS (готовые модули для CMS), одностраничный сайт и.т.д.

Интеграция состоит из двух этапов:

1. Вставка формы оплаты

На первом этапе необходимо вставить форму оплаты в сайт. Это можно сделать с помощью <iframe>, либо стандартными средствами языка программирования вашего сервера.

Платёж инициализируется загрузкой формы. Если предполагается, что в дальнейшем сумму оплаты изменить нельзя, то загрузка формы должна быть произведена POST запросом по URL:

http://demo.paykeeper.ru/order/inline/

В эту форму оплаты нужно предварительно передать параметры: сумму заказа, номер заказа, идентификатор плательщика.

  Параметр Назначение  
  clientid Идентификатор пользователя в системе предприятия. Например, логин на сайте, id в базе данных и т.п.  
  sum Сумма заказа в рублях. Допустимы дробные значения  
  orderid Номер заказа в системе предприятия  
  phone Номер телефона пользователя  

Если плательщик должен ввести данные оплаты сам, то необходимо использовать следующий URL:

http://demo.paykeeper.ru/form/inline/

Ниже приведён пример на PHP с передачей параметров в форму:

<?php
  # предполагаются заранее известными значения переменных
  # $client_login, $order_id, $order_sum и $optional_phone
 
  $payment_parameters = http_build_query(array(
                "clientid"=>$client_login,
                "orderid"=>$orderid,
                "sum"=>$order_sum,
                "phone"=>$optional_phone));
  $options = array("http"=>array(
                "method"=>"POST",
                "header"=>
                "Content-type: application/x-www-form-urlencoded",
                "content"=>$payment_parameters
                   ));
  $context = stream_context_create($options);
 
  echo file_get_contents("http://demo.paykeeper.ru/order/inline/",FALSE, $context);
?>

Без передачи параметров в форму код выглядит существенно проще:

<?php
  echo file_get_contents("http://demo.paykeeper.ru/form/inline/");
?>

В этих примерах нужно заменить demo.paykeeper.ru на адрес вашего сервера PayKeeper.

2. Прием информации об оплате

При каждом принятом платеже PayKeeper отправляет POST-запрос на сайт предприятия.

В запросе от PayKeeper будут передаваться следующие данные:

  Параметр Назначение  
  id Уникальный, никогда не повторяющийся номер платежа в PayKeeper  
  sum Сумма платежа в рублях с точностью до сотых. Разделитель – точка  
  clientid Идентификатор клиента. Тот же, что при генерации формы оплаты  
  orderid Номер заказа. Не обязателен  
  key Цифровая подпись запроса, строка из символов a-f и 0-9  

Поле key - цифровая подпись запроса. Она является md5-хешем, который вычисляется от конкатенации параметров 1-4 с добавлением в конец секретного слова. Секретное слово согласовывается при интеграции техническими специалистами обеих сторон.

В ответ на данный запрос должна быть отправлена строка вида:

 OK hash    

где hash вычисляется как md5-хеш от конкатенации поля id запроса и того же секретного слова, а слово «OK» состоит из английских букв O и K. Такой ответ считается подтверждением того, что информационная система предприятия приняла данный платёж. Пример составления ответа на PHP:

  $hash = md5($id.$secret_seed);
  echo "OK $hash";  

В случае, если на запрос не будет получен корректный ответ, PayKeeper будет продолжать попытки сообщить о платеже, повторяя запрос каждую минуту. Если через определённое число попыток (50 по умолчанию) не будет получен корректный ответ, платёж в PayKeeper получит статус «превышено число повторов». Такой платёж можно повторно провести через веб-интерфейс администратора, а также изменить его назначение (поле clientid).

Например, на языке PHP приём оповещений можно реализовать так:

<?php
  $secret_seed = "verysecretseed";
  $id = $_POST['id'];
  $sum = $_POST['sum'];
  $clientid = $_POST['clientid'];
  $orderid = $_POST['orderid'];
  $key = $_POST['key'];
 
  if ($key != md5 ($id . sprintf ("%.2lf", $sum).
                                 $clientid.$orderid.$secret_seed))
  {
      echo "Error! Hash mismatch";
      exit;
  }
 
  if ($orderid == "")
  {
      # Платёж – пополнение счёта, нужно зачислить 
                                    деньги на баланс $clientid
      # ...
  }
  else
  {
      # Оплата заказа $orderid. Выставляем ему статус «оплачено»
      # ... 
  }
  echo "OK ".md5($id.$secret_seed);
?>