Перейти к основному содержанию

Документация

  Общие положения

- Во всех запросах и ответах следует использовать кодировку UTF8

- Для работы вам потребуется получить номер мерчанта ('merchantId'), доступный в клиентском интерфейсе, а так же сгенерировать и задать секретный ключ ('sharedsec'), что так же можно сделать из клиентского интерфейса. Обратите внимание, что секретный ключ ни в каком виде не должен покидать вашего сервера. В случае если он передаётся как часть HTML или каким-либо образом используется в JavaScript, это является проблемой безопасности и даёт злоумышленнику возможность делать вызовы к платёжной системе от вашего имени.

- Для корректной обработки транзакций вам необходимо реализовать обработчики двух URL - один для возвращения пользователя на ваш сайт, другой для приёма уведомлений (webhook/callback) о состоянии транзакций, их можно задать на вкладке "Интеграция" клиентского интерфейса.

  Оплата через API форм {#forms-api}

Для оплаты через API форм вам необходимо на своём сайте сгенерировать форму следующего вида:

<form action="https://secure.orcompany.ru/Pay" method="POST"> 
<input type="hidden" name="merchantId" value="812" />  
<input type="hidden" name="price" value="12.34" /> 
<input type="hidden" name="orderId" value="325GVD" /> 
<input type="hidden" name="customValue1" value="client value 1" /> 
<input type="hidden" name="customValue2" value="client value 2" />  
<input type="hidden" name="customValue3" value="client value 3" /> 
<input type="hidden" name="sign" value="d41d8cd98f00b204e9800998ecf8427e" /> 
<input type="submit" value="Оплатить" /> 
</form>
Поле Обязательное поле Описание
merchantIdДаId мерчанта
price Да Сумма платежа. Обязательна к передаче в текущей версии системы.
orderIdДа Уникальный номер заказа в системе Продавца.
signДа Контрольная подпись данных о платеже. Методику подсчёта см. ниже
customValue1НетПоля для клиентских данных, которые могут использоваться для прикрепления различного рода информации к данным Платежа и Плательщика. Для передачи идентификатора заказа рекомендуется использовать параметр order_id
customValue2Нет
customValue3Нет
customName1НетВидимые пользователю наименования клиентских данных. Если эти поля отсутствуют, пользователю они не показываются
customName2Нет
customName3Нет
extra_*НетДополнительные поля для передачи в уведомлении. Должны иметь вид 'extra_[A-Za-z0-9_]+'
customer_emailДа Email пользователя
customer_phoneНетТелефон пользователя
Подсчёт поля sign {#sign}

Контрольная сумма вычисляется от всех присутствующих документированных полей запроса, перечисленных в алфавитном порядке и sharedsec (уникальный кода, который знает только платёжная система и Продавец) и разделённых символом “-”. например:

sign = sha256(email + "-" + merchantId + "-" + orderId + "-" + price + "-" + sharedsec)
Пример генерации поля sign и формирования формы на PHP #{sign-php}
				
<?php
function calc_sign($secret, $fields)
{
        ksort($fields);
        $secret_t = '';
        foreach($fields as $key => $val)
        {
                $secret_t = $secret_t . '-' . $val;
        }
        $secret_t = substr($secret_t, 1) . '-' . $secret;
        return hash("sha256", $secret_t);
}

function generate_form($secret, $fields)
{
        $sign = calc_sign($secret, $fields);
        $form = "";
        foreach($fields as $key => $val)
        {
                $form = $form . '<input type="hidden" name="'.$key.'" value="' . htmlspecialchars($val) . '"/>'."\n";
        }
        $form = $form . '<input type="hidden" name="sign" value="'.$sign.'"/>';
        return $form;
}

$f = generate_form("123", $values = array(
   "email" => "user@example.com",
   "merchantId" => "1",
   "orderId" => "123",
   "price" => "123.00",
));
echo $f;
?>
Пример генерации поля sign на языке C\# {#sign-csharp}
public static string Calculate(string secret, IDictionary<string, string> values)
{
    using (var sha256 = System.Security.Cryptography.SHA256.Create())
        return BitConverter.ToString(sha256.ComputeHash(Encoding.UTF8.GetBytes(string.Join("-", values.OrderBy(x => x.Key, StringComparer.Ordinal).Select(x => x.Value)) + "-" + secret))).ToLower().Replace("-", "");
}


Calculator.Calculate("123", new Dictionary<string, string>
{
   ["email"] = "user@example.com",
   ["merchantId"] = "1",
   ["orderId"] = "123",
   ["price"] = "123.00",
}); 
Отмена транзакции (refund) (#refund)
 **POST** '/api/transactions'
'''json
{
  "payment":
  {
      "orderId": "123321",
      "action": "reversal"
  },
  "target":
  {
      "transaction": "43913ddc000c4d3990fddbd3980c1725"
  }
}
'''

'200':
'''json
{
  "id": "43913ddc000c4d3990fddbd3980c1725"
}
'''
 

Отмена будет совершена в асинхронном режиме, ожидайте получение callback-вызова

Создание транзакции на повторное списание (rebill) {#rebill}
**POST** '/api/transactions'
{
  "payment":
  {
      "orderId": "123321",
      "action": "pay",
      "price": "10"
  },
  "target":
  {
      "rebill": "43913ddc000c4d3990fddbd3980c1725"
  }
}

'200':
{
  "id": "43913ddc000c4d3990fddbd3980c1725"
}

'400' Bad request:
{
  "error": "Invalid request"
}

			 

В поле 'rebill' необходимо указать Id ранее проведённой успешной транзакции на списание средств с карты. Транзакция будет совершена в асинхронном режиме, ожидайте получение callback-вызова

Создание транзакции по известному номеру карты {#create-transaction-with-known-card}

Следует использовать ТОЛЬКО если номер карты был получен ЛИЧНО от клиента на бумаге без участия вашего веб-сайта. Ввод номера карты на вашем сайте без прохождения процедуры сертификации PCI-DSS недопустим.

**POST** '/api/transactions'

{
  "payment":
  {
      "orderId": "123321",
      "action": "payout",
      "price": "10"
  },
  "customerInfo":
  {
    "email": "user@example.com",
    "phone": "+79001234567"
  },
  "target":
  {
      "knownCardNumber": "4012888888881881"
  }
}


'200':

{
  "id": "43913ddc000c4d3990fddbd3980c1725"
}

'400' Bad request:
{
  "error": "Invalid request"
}
				
				

Транзакция будет совершена в асинхронном режиме, ожидайте получение callback-вызов

Создание выплаты на мобильный телефон {#create-transaction-to-mobile-phone}
**POST** '/api/transactions'

{
  "payment":
  {
      "orderId": "123321",
      "action": "payout",
      "price": "10"
  },
  "customerInfo":
  {
    "email": "user@example.com",
    "phone": "+79001234567"
  },
  "target": "phone"
}

'200':
{
  "id": "43913ddc000c4d3990fddbd3980c1725"
}

'400' Bad request:
{
  "error": "Invalid request"
}
					
				

Транзакция будет совершена в асинхронном режиме, ожидайте получение callback-вызов

Блокировка (предавторизация) средств с последующим списанием {#preauth}

Предавторизация производится аналогично обычной покупке как через API форм, так и через REST. Необходимо в поле 'action' передать значение 'preauth'. После того как придёт уведомление об успехе предавторизации полученый вв нём Id транзакции можно использовать для полного или частичного списания через REST API, используя этот номер в качесве значения для 'target'->'preauth':

**POST** '/api/transactions'
{
  "payment":
  {
      "orderId": "123321",
      "action": "pay",
      "price": "10"
  },
  "target":
  {
      "preauth": "43913ddc000c4d3990fddbd3980c1725"
  }
}

'200':
{
  "id": "43913ddc000c4d3990fddbd3980c1725"
}

'400' Bad request:
{
  "error": "Invalid request"
}
				
				

Для отказа от блокировки средств:

**POST** '/api/transactions'
{
  "payment":
  {
      "orderId": "123321",
      "action": "reversal"
  },
  "target":
  {
      "preauth": "43913ddc000c4d3990fddbd3980c1725"
  }
}
				
				

Транзакция будет совершена в асинхронном режиме, ожидайте получение callback-вызов

Уведомления о статусе транзакций {#notifications}

Уведомления высылаются на указанный в клиентском интерфейсе 'CallbackUrl' в теле POST-запроса с 'Content-Type: application/x-www-urlencoded'. В качестве ответа обработчик должен вернуть HTTP-код '200' и тело ответа 'OK'.

Для подтверждения того, что уведомление пришло именно от системы Orcompany необходимо проверять значение поля 'sign', являющегося SHA256-суммой от значений всех параметров запроса, отсортированных алфавитно по именам и 'SharedSec', разделённых символом '-'.

В зависимости от значения 'object_type' уведомления бывают следующих видов:
- 'card_binding' - привязка карты
- 'transaction' - транзакция

Пример проверки 'sign' на языке PHP {#sign-check-php}
function check_sign($secret, $req)
{
        $sign = $req['sign'];
        unset($req['sign']);
        $to_hash = '';
        if (!is_null($req) && is_array($req)) {
                ksort($req);
                $to_hash = implode('-', $req);
        }

        $to_hash = $to_hash .'-'. $secret;
        $calculated_sign = hash('sha256', $to_hash);
        return $calculated_sign == $sign;
}

check_sign("123", $_POST);
				
Пример проверки `sign` на языке C\# {#sign-check-csharp}
public static string Calculate(string secret, IDictionary<string, string> values)
{
    using (var sha256 = System.Security.Cryptography.SHA256.Create())
        return BitConverter.ToString(sha256.ComputeHash(Encoding.UTF8.GetBytes(string.Join("-", 
values.OrderBy(x => x.Key, StringComparer.Ordinal).Select(x => x.Value)) + "-" + secret))).ToLower().Replace("-", "");
}

public static bool CheckSign(string secret, HttpRequest request)
{
    var sign = request.Form["sign"];
    if(string.IsNullOrWhiteSpace(sign))
    	return false;
    return sign ==
        Calculate(secret, request.Form.Keys.Where(k => k != "sign").ToDictionary(k => k, k => request.Form[k]));
}	
				
Уведомления о привязках карт {#notification-card}
ПолеПримерОписание
card_binding38467cb0-da73-4755-84da-2acb7f638a59Идентификационный номер привязки
card_holderVASILY PUPKINДержатель карты
card_number123456XXXXXX7890Номер карты
card_expiration_year18Год срока действия карты
card_expiration_month9Месяц срока действия карты
statussuccessСтатус привязки
Уведомления о транзакциях {#notification-transaction}
ПолеПримерОписание
transaction05991602ed7c47d996ca7ab119b07f66ID транзакции в системе
statussuccess, failedСтатус операции
actionpay, payoutДействие (покупка или выплата на карту)
merchantId42Id мерчанта
price12.34Сумма платежа. Обязательна к передаче в текущей версии системы.
orderId1234ORУникальный номер заказа в системе Продавца.
customer_emailuser@example.comEmail пользователя
customer_phone+71234567890Телефон пользователя
  Номера карт для проверки работоспособности в sandbox-режиме

Следует использовать имя держателя "CARD HOLDER" и Cvv "123".

Для проведения успешных транзакций используйте любой валидный номер карты (например 4929509947106878), для неуспешных - 4485913187374384