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

Подключение внешнего способа оплаты

Внешний способ оплаты — прокси между формой InSales и платёжной системой. После заказа магазин отправляет покупателя POST-запросом на URL из настроек. О результате платёжная система сообщает редиректом покупателя или запросом со своего сервера. При widget_mode оплата идёт на странице магазина.

Создание способа — POST /admin/payment_gateways.json, тип PaymentGateway::External. Описание полей — в справочнике, PaymentGateway.

Поля создания

Обязательные для внешнего типа: title, type, url, shop_id.

  • url — адрес платёжного сервиса.
  • shop_id — идентификатор магазина в вашей системе.
  • password — секрет подписи. Если поле не передать, в ответе будет сгенерированное значение. Переданное значение сохраняется как есть.
  • send_order — добавить в форму order_json с составом заказа. Это поле входит в подпись, в конец строки.
  • convert_currency — ISO-код валюты списания. Валюта должна быть заведена в магазине: по ней берётся курс. Суммы в order_json и в GET /admin/orders/:id.json остаются в валюте сайта.
  • redirect_to_payment — сразу уводить покупателя на оплату после создания заказа. По умолчанию true.
  • widget_mode — оплата на странице магазина.
  • widget_html_code — HTML и JavaScript виджета на этой странице.
  • add_delivery_variants — разрешить способ для всех вариантов доставки. Без привязанных доставок способ покупателю недоступен.

Пример:

{
  "payment_gateway": {
    "title": "external payment gateway",
    "type": "PaymentGateway::External",
    "description": "text",
    "url": "https://payment.example/transactions/create",
    "shop_id": "123",
    "password": "secret",
    "send_order": true,
    "redirect_to_payment": false,
    "widget_mode": true,
    "widget_html_code": "<div id=\"pay-widget\"></div>",
    "add_delivery_variants": true
  }
}

В ответе 201 приходят password, success_url, fail_url и server_url. Адреса уже содержат id способа:

https://SHOP/payments/external/37/success
https://SHOP/payments/external/37/fail
https://SHOP/payments/external/37/server

Дальше используйте URL из ответа, а не собирайте путь вручную.

Форма на платежный сервис

На url уходит POST. Поля по порядку:

  • shop_id
  • amount — сумма к оплате; при конвертации это уже сумма в convert_currency
  • transaction_id
  • key — ключ заказа
  • description
  • order_id
  • phone
  • email

Если задан convert_currency, следом идут original_currency, convert_currency, original_amount, conversion_rate.

Если send_order истинно, следом идёт order_json.

signature — MD5 от значений этих полей в том же порядке, через ;, и в конце пароль способа:

MD5(shop_id;amount;transaction_id;key;description;order_id;phone;email;password)

Поля конвертации и order_json вставляются перед паролем только когда соответствующая настройка включена.

Возврат покупателя

Успешная оплата — POST на success_url, неуспешная — POST на fail_url. Поля:

  • paid — 1 или 0
  • amount
  • key
  • transaction_id
  • shop_id
  • signature — MD5 от shop_id;amount;transaction_id;key;paid;password

Магазин проверяет подпись, сумму, paid и shop_id. При paid=1 и верных данных заказ помечается оплаченным.

Передавайте поля подписи именно в этом порядке: строка собирается из значений в порядке параметров запроса.

Уведомление с сервера платёжной системы

POST на server_url с теми же полями, что и редирект. Ответ — JSON.

Успех:

{ "status": "ok" }

Ошибка:

{ "status": "error", "errors": ["signature is not valid"] }

Возможные строки в errors:

  • transaction not found
  • data is empty
  • data is not a hash
  • signature is not valid
  • paid params is not valid
  • shop id is not valid
  • amount is not valid

Оплата виджетом на сайте

При widget_mode покупатель попадает на страницу вида /payments/external/ID/payment_page?key=....

В этот момент магазин сам делает POST на url способа и передаёт ту же форму, что и при обычном редиректе, телом JSON. Ожидается ответ 200 и JSON:

{ "widget_payment_data": {} }

Значение widget_payment_data попадает в переменную widget_payment_data на странице, рядом выводится widget_html_code. Подтверждение оплаты — те же success_url, fail_url и server_url.