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

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

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

Чтобы создать внешний способ оплаты, отправьте POST /admin/payment_gateways.json с типом PaymentGateway::External. Получение списка, изменение и удаление способов, а также наложенный платёж и произвольный способ описаны в разделе «Способы оплаты».

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

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

  • url — адрес платёжного сервиса.
  • shop_id — идентификатор магазина в вашей системе.
  • password — секрет для расчёта подписи. Если поле не передать, в ответе будет сгенерированное значение. Переданное значение сохраняется как есть.
  • send_order — добавить в отправляемую форму поле order_json с составом заказа. При расчёте подписи его значение добавляется после остальных полей формы, перед паролем.
  • convert_currency — ISO-код валюты списания. Добавьте эту валюту в магазин: InSales использует её курс для пересчёта суммы. Суммы в 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
  }
}

При успешном создании API возвращает статус 201 и поля password, success_url, fail_url, server_url. Полученные URL уже содержат идентификатор способа оплаты:

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

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

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

InSales отправляет POST-запрос на адрес из поля url. Форма содержит следующие поля в указанном порядке:

  • 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 при успехе или на 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. Передайте те же поля, что и при возврате покупателя. InSales вернёт ответ в 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": {} }

InSales сохраняет значение widget_payment_data в одноимённой переменной страницы и выводит код из widget_html_code. Для подтверждения результата оплаты используйте success_url, fail_url и server_url, как и при переходе на платёжный сервис.