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

В inSales есть возможность сделать интеграцию с платежной системой, создав "прокси" из формата передачи данных inSales в формат платежной системы. После создания заказа в браузере пользователя делаем post-запрос на URL из настроек, передавая в форме все необходимые данные о заказе. В ответ ожидаем редирект пользователя назад или бэкенд-запрос о результатах платежа. Также есть возможность сделать оплату прямо в магазине через js-виджет.

1. Создание нового способа оплаты в inSales
2. Отправка post-запроса в платежную систему
3. Передача информации о заказе в платежный модуль
4. Редирект пользователя назад после успешной/неуспешной оплаты
5. Отправка результатов оплаты с бэкенда
6. Конвертация суммы заказа при использовании поля convert_currency
7. Оплата через виджет на сайте

Создание нового способа оплаты в inSales

Специальный способ оплаты создается в разделе Настройки → Оплата. Далее необходимо добавить новый вариант "Внешний способ оплаты". Интеграция для Appstore должна создавать этот способ оплаты по API https://api.insales.ru/?doc_format=JSON#paymentgateway-create-external-payment-gateway-json.    

• shop_id - идентификатор магазина в вашей системе;
• password - пароль для генерации подписи;
• url - адрес внешнего сервиса, куда будет отправлен покупатель;
• send_order  - передавать ли order_json с детальной информацией о заказе;
• convert_currency - использовать ли конвертацию в валюту отличную от валюты сайта,  нужно задать iso code валюты и валюта должна быть добавлена в магазине  (чтобы было понятно по какому курсу делать конвертацию);
• wigdet_mode - оплата происходит прямо на сайте магазина через js-виджет;
• widget_html_code - код виджета, может содержать html и javascript.

Отправка post-запроса в платежную систему

На последнем шаге оформления заказа покупателем система inSales отправляет на внешний URL (задается в настройках внешнего способа оплаты в inSales) POST-запросом следующие параметры:

• shop_id - идентификатор магазина в вашей системе;
• amount - сумма;
• transaction_id - id транзакции;
• key - ключ заказа;
• description - описание заказа;
• order_id - id заказа;
• phone - телефон клиента;
• email - email клиента;
• order_json - полная информация по заказу в json-формате (если стоит флаг send_order);
• original_currency -  iso code основной валюты сайта (если стоит флаг convert_currency);
• convert_currency - iso code валюты, в которую выполнена конвертация (если стоит флаг convert_currency);
• conversion_rate - курс пересчета;
• original_amount - стоимость заказа в основной валюте сайта (если стоит флаг convert_currency);
• signature - подпись. 
  Формируется как MD5 от  "shop_id;amount;transaction_id;key;description;order_id;phone;email;original_currency;convert_currency;original_amount;conversion_rate;order_json;password"

После обработки платежа внешний сервис возвращает на success_url или fail_url c параметрами.

Передача информации о заказе в платежный модуль

Рассмотрим на примере запроса:

"order_lines": [
   {
      "id": 604294351,
      "order_id": 64844218,
      "sale_price": 8000.0,
      "full_sale_price": 8000.0,
      "total_price": 8000.0,
      "full_total_price": 8000.0,
      "discounts_amount": 0.0,
      "quantity": 1
   }
],
   "total_price": 8824.0,
   "items_price": 8000.0,
   "delivery_title": "Курьером Boxberry",
   "delivery_description": "Курьером Boxberry (Курьерская служба Boxberry)",
   "delivery_price": 824.0,
   "full_delivery_price": 824.0
}

order_lines - это перечень позиций заказа. Только позиций, доставка сюда не входит. Перечень позиций включает в себя:

• sale_price: 8000.0 - цена одной единицы товара в позиции без учёта применённых скидок;
• full_sale_price: 8000.0 - цена одной единицы товара в позиции с учётом применённых скидок;
• total_price: 8000.0 - сумма товаров в позиции без учёта применённых скидок (то есть sale_price умноженное на quantity);
• full_total_price: 8000.0 - сумма товаров в позиции с учётом применённых скидок (то есть full_sale_price умноженное на quantity).

• delivery_price: 824.0 - исходная стоимость доставки;
• full_delivery_price: 824.0 - стоимость доставки с учётом наценок.

• total_price: 8824.0 - общая сумма заказа со всеми скидками/наценками и доставкой;
• items_price: 8000.0 - общая сумма товаров (то есть total_price минус доставка).

Редирект пользователя назад на сайт после успешной/неуспешной оплаты

В случае успешной оплаты нужно отправить пользователя POST-запросом на http://shop.myinsales.ru/payments/external/#%7Bpayment_gateway_id%7D/success, этот урл отдается в ответе при создании внешнего способа оплаты.

В post-запросе необходимо передать следующие поля:

• paid - оплачен или нет. "1" или "0";
• amount - сумма платежа. Например, "87.10", или "1200.00";
• key - ключ идентификации заказа. Изначально был отправлен inSales;
• transaction_id - id транзакции. Изначально был отправлен inSales;
• signature - Подпись. Формируется как MD5 от "shop_id;amount;transaction_id;key;paid;password".
• shop_id - идентификатор магазина.

Сохраняет данные, проверяет: подпись, сумму, параметр paid и shop_id. Дальше помечает заказ как успешный.

В случае неуспешной оплаты нужно отправить пользователя POST-запросом на http://shop.myinsales.ru/payments/external/#%7Bpayment_gateway_id%7D/fail. Поля для post-запроса такие же, как и для success-запроса.

Отправка результатов оплаты с бэкенда

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

Урл для отправки запроса вида http://shop.myinsales.ru/payments/external/server для конкретного магазина отдается в ответе по API. В POST-запросе inSales ожидает следующие поля:

• paid - оплачен или нет. "1" или "0".
• amount - сумма платежа. Например, "87.10", или "1200.00".
• key - ключ идентификации заказа. Изначально был отправлен inSales.
• transaction_id  - id транзакции. Изначально был отправлен inSales.
• signature - подпись. Формируется как MD5 от "shop_id;amount;transaction_id;key;paid;password".
• shop_id - идентификатор магазина.

Если все хорошо, inSales проверяет: подпись, сумму, параметр paid и shop_id. Дальше помечает заказ как успешный. В ответ возвращает json:

'status' → 'ok' в случае подтверждения;

'status' → 'error', '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'

Конвертация суммы заказа при использовании поля convert_currency

Если для способа оплаты указана валюта конвертации, то при переходе в платежную систему передается сумма заказа (amount), уже сконвертированная в указанную валюту, и справочно передаются три дополнительных поля - original_currency, convert_currency и original_amount.

Важно: если передается order_json или при запросе заказа по API через /admin/orders/ID.json, то все суммы будут в оригинальной валюте сайта и конвертация не произойдет.

Оплата через виджет на сайте

1. Если для способа оплата включен widget_mode, то после создания заказа у inSales идет редирект на страницу вида /payments/external/16173/payment_page?key=0477bd091e1e2047790e32b3a42db7a5 .

2. В момент запроса этой страницы inSales отправляет запрос на внешний урл из настроек способа оплаты в json-формате передавая все данные формы, как и при редиректе в обычной форме (shop_id, amount, transaction_id, … signature ).

3. В ответе inSales ожидает 200-й код и json вида { widget_payment_data: … } .

4. Содержимое ключа widget_payment_data подставляется в js-переменную на странице: var widget_payment_data = '{}';

5. Также на странице подставляется html-код из настроек способа оплаты (поле widget_html_code).

6. Для подтверждения способа оплаты никаких новых урлов нет, ожидаем такие же запросы, как и при обычной внешней оплате.