Подключение внешнего способа оплаты (для разработчиков интеграций) — различия между версиями

Материал из Insales Wiki
Перейти к: навигация, поиск
 
(не показано 30 промежуточных версий 4 участников)
Строка 1: Строка 1:
Специальный способ оплаты создается в разделе Настройки -> Оплата.
+
= Введение =
  
Настройки на стороне InSales:
+
В InSales есть возможность сделать интеграцию с платежной системы создав "прокси" из формата передачи данных InSales в формат платежной системы. После создания заказа мы в браузере пользователя делаем post-запрос на урл из настроек, передавая в форме все необходимые данные о заказа. В ответ ожидаем редирект пользователя назад или бэкенд-запрос о результатах платежа. Так же есть возможность сделать оплату прямо в магазине через js-виджет.
 +
 
 +
=Настройки на стороне InSales=
 +
 
 +
Специальный способ оплаты создается в разделе Настройки -> Оплата. Добавить новый вариант "Внешний способ оплаты". Интеграция для Appstore должна создавать этот способ оплаты по API https://api.insales.ru/?doc_format=JSON#paymentgateway-create-external-payment-gateway-json .
  
 
     shop_id - идентификатор магазина в вашей системе.
 
     shop_id - идентификатор магазина в вашей системе.
 
     password - пароль для генерации подписи.
 
     password - пароль для генерации подписи.
 
     url - адрес внешнего сервиса, куда будет отправлен покупатель.
 
     url - адрес внешнего сервиса, куда будет отправлен покупатель.
 +
    send_order  - передавать ли order_json с детальной информацией о заказе.
 +
    convert_currency - использовать ли конвертацию в валюту отличную от валюты сайта, нужно задать iso code валюты и валюта должна быть добавлена в магазине (чтобы было понятно по какому курсу делать конвертацию)
 +
    wigdet_mode - оплата происходит прямо на сайте магазина через js-виджет.
 +
  widget_html_code - код виджета, может содержать html и javascript.
  
 +
=Отправка post-запроса в платежную систему=
  
 
На последнем шаге заказа, система InSales отправляет на внешний URL (задается в настройках внешнего способа оплаты в InSales) POST запросом следующие параметры:
 
На последнем шаге заказа, система InSales отправляет на внешний URL (задается в настройках внешнего способа оплаты в InSales) POST запросом следующие параметры:
Строка 13: Строка 22:
 
     amount - сумма
 
     amount - сумма
 
     transaction_id - id транзакции
 
     transaction_id - id транзакции
 +
    key - ключ заказа
 
     description - описание заказа
 
     description - описание заказа
     key - ключ заказа
+
     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 параметрами:
 
После обработки платежа, внешний сервис возвращает на success_url или fail_url c параметрами:
  
1) success-контроллер ожидает POST запрос со следующими параметрами:
+
=Редирект пользователя назад на сайт после оплаты или неудачной оплаты=
 +
В случае успешной оплаты нужно отправить пользователя POST-запросом на
 +
http://shop.myinsales.ru/payments/external/#{payment_gateway_id}/success , этот урл отдается в ответе при создании внешнего способа оплаты.
 +
 
 +
В post-запросе необходимо передать следующие поля:
  
 
     paid: Оплачен или нет. "1" или "0".
 
     paid: Оплачен или нет. "1" или "0".
Строка 29: Строка 51:
 
Сохраняет данные, проверяет подпись, сумму, параметр paid и shop_id. Дальше помечает заказ как успешный.
 
Сохраняет данные, проверяет подпись, сумму, параметр paid и shop_id. Дальше помечает заказ как успешный.
  
2) fail только сохраняет данные.
+
В случае неуспешной оплаты нужно отправить пользователя POST-запросом на http://shop.myinsales.ru/payments/external/#{payment_gateway_id}/fail . Поля для post-запроса такие же как и для success-запроса.
 +
 
 +
= Отправка результатов оплаты с бэкенда =
 +
 
 +
В случае когда есть задержа между подтверждением оплаты и редиректом пользователя назад или есть соображения безопасности, то можно передать данные по платежку запросом с сервера.
 +
 
 +
Урл для отправки запроса вида http://shop.myinsales.ru/payments/external/server , для конкретного магазина отдается в ответе по API.
 +
В 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. Дальше помечаем заказ как успешный.
 +
В ответ возвращаем 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, то после создания заказа идет редирект на страницу у нас вида /payments/external/16173/payment_page?key=0477bd091e1e2047790e32b3a42db7a5 .
 +
 
 +
2. В момент запроса этой страницы мы отправляем запрос на внешний урл из настроек способа оплаты в json-формате передавая все данные формы, как и при редиректе в обычной форме (shop_id, amount, transaction_id, … signature ).
 +
 
 +
3. В ответе мы ожидаем 200-й код и json вида { widget_payment_data: … } .
 +
 
 +
4. Содержимое ключа widget_payment_data  мы подставляем в js-переменную на странице:
 +
      var widget_payment_data = '{}';
 +
 
 +
5. Так же на странице подставляем html-код из настроек способа оплаты (поле widget_html_code).
  
Примеры success_url и fail_url:
+
6. Для подтверждения способа оплаты никаких новых урлов нет, ожидаем такие же запросы, как и при обычной внешней оплате.
http://shop.myinsales.ru/payments/external/success
 
http://shop.myinsales.ru/payments/external/fail
 

Текущая версия на 14:00, 26 июня 2020

Введение

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

Настройки на стороне 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 параметрами:

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

В случае успешной оплаты нужно отправить пользователя POST-запросом на http://shop.myinsales.ru/payments/external/#{payment_gateway_id}/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/#{payment_gateway_id}/fail . Поля для post-запроса такие же как и для success-запроса.

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

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

Урл для отправки запроса вида http://shop.myinsales.ru/payments/external/server , для конкретного магазина отдается в ответе по API. В 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. Дальше помечаем заказ как успешный. В ответ возвращаем 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, то после создания заказа идет редирект на страницу у нас вида /payments/external/16173/payment_page?key=0477bd091e1e2047790e32b3a42db7a5 .

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

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

4. Содержимое ключа widget_payment_data мы подставляем в js-переменную на странице:

     var widget_payment_data = '{}';

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

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