Настоящий документ описывает принципы подключения и программные интерфейсы платежной платформы — InecoPay.
Для осуществления покупок в сети Интернет существует необходимость в обеспечении безопасного взаимодействия сторон, участвующих при осуществлении операции продажи товаров/услуг – клиента, магазина и банка- эквайера. ТСП, планирующее осуществлять продажу услуг или товаров в сети Интернет посредством банковских карт должен выполнять процедуры по обеспечению безопасности проведения платежей. Для выполнения данных требований банк- эквайер использует специализированную технологию по обеспечению безопасности платежей в сети Интернет, разработанную Международными Платежными Системами Visa International и MasterCard – ЗDSecure (Verified by Visa и MasterCard SecureCode). В качестве технологической платформы используется платежная платформа, позволяющая ТСП выполнить необходимые процедуры безопасности без существенной перестройки Интернет-магазина и существующих бизнес-процессов.
Платежная платформа InecoPay предоставляет следующие функции, рассматриваемые в настоящем документа:
-
Личный Кабинет (по адресу — https://inecopay.ru/inecogate/admin/login.jsp) -позволяющий:
-
Выполнять подключение и настройку ТСП;
-
осуществлять ручную обработку транзакций;
-
осуществлять статистические выборки в реестре платежей.
-
-
API для организации взаимодействия с платежным шлюзом для проведения платежей. API представляет собой набор методов информационного обмена между ТСП и Системой. Протокол предназначен для формирования заказа на витрине партнера и предоставления клиенту платежных веб-форм, где он может ввести платежные реквизиты, а также дополнительную информацию, необходимую для оплаты товара или услуги. Взаимодействие между ТСП и Системой происходят в синхронном режиме. В качестве транспортного механизма используется протокол HTTP поверх TLS (HTTPS). Запросы отправляются в формате RESTFull методов в кодировке UTF-8. Сертификаты в данной версии API не используются. Все значения времени задаются в формате UTC с указанием временной зоны (пример: «2015-10-26T13:00:53.409+0300»). Все значения сумм указываются в копейках.
-
Интерактивный интерфейс к Платежным сервисам InecoGate API
https://inecopay.ru/inecogate/doc/dist/index.html?url=https://inecopay.ru/inecogate/doc/inecogate_gate.json -
Набор тестовых банковских карт
https://inecopay.ru/inecogate/doc/test_card.htmlAPI содержит 5 основных сервисов для завершения полного цикла приема платежа.
- status — проверка статуса и получение подробный информации о платеже.
- register — регистрация заказа для получения ссылки на платежную страницу.
- confirm — применяется при двухстадийной оплате для подтверждения платежа.
- cancel — применяется при двухстадийной оплате для отмены платежа.
- refund — полный или частичный возврат уже подтвержденной оплаты.
Подробное описание сервисов
-
/gate/status
Сервис status предназначен для получения данных о состоянии ,статусе и данных транзакции.
Вызов методом GET.
Сервис принимает один входной параметр transactionId вида UUID ( например 18ceca78-e8c4-401b-9cb7-341edc584c55 ).
Пример запроса утилитой CURL:
curl -X GET --header "Accept: application/json" "https://inecopay.ru/inecogate/rest/api/v1.0/gate/status?transactionId=18ceca78-e8c4-401b-9cb7-341edc584c55"
Пример ответа:
{ "transactionId": "18ceca78-e8c4-401b-9cb7-341edc584c55", "timestampRegistered": "2016-06-28 12:32:39", "paymentTypeId": 14, "statusNote": "Авторизация отклонена", "statusName": "DECLINED", "partnerId": 1007, "userData": { "phone": "+7(985)369-55-53", "address": "", "email": "acrrrub@list.ru", "basket": { "basketId": 134, "priceCount": 1, "payed": false, "prices": [ { "id": 318, "amount": 34000, "count": 1, "name": "Мяч баскетбольный", "code": "00014" } ] }, "passport": "", "fio": "asdd sad sadad" }, "paymentTypeName": "CARD", "currency": "RUB", "amount": 34000, "statusCode": 6, "id": 5790, "timestampWaiting": "2016-06-28 13:02:39", "orderId": "A1467106359248", "extTransactionId": "802249cf-df6e-4de9-be25-2dc84c7ac053", "partnerName": "Galaxy", "timestampRegisteredTZ": "2016-06-28T12:32:39.248+0300", "actionDescription": "Истек срок ожидания ввода данных.", "currencyCode": 643, "timestampCommited": "2016-06-28 12:52:39", "typeName": "AVIA", "actionCode": -2007, "bankInfo": { "bankCountryCode": "UNKNOWN", "bankCountryName": "<Неизвестно>" }, "timestampWaitingTZ": "2016-06-28T13:02:39.248+0300", "timestampCommitedTZ": "2016-06-28T12:52:39.390+0300", "clientIp": "87.245.131.168", "typeId": 1 }
Сервис для регистрации платежа и получения ссылки для ввода реквизитов кредитной карты.
Вызов методом POST.
Необходимые входные параметры: partnerId, paymentType, amount и sign (в случае, если в настройках интеграции настроена ЭЦП).
При отсутствии параметров successUrl и failUrl, данные берутся из настроек кабинета (раздел Интеграция).
Коды ответа:
Пример ответа:
{ "statusNote": "Заказ зарегистрирован,но не оплачен", "timestampRegisteredTZ": "2017-09-16T15:53:25.639+0300", "amount": 100001, "userData": "test", "partnerName": "GLX", "orderId": "TEST_1", "userNote": "test", "paymentTypeName": "CARD", "typeName": "WALLET", "timestampWaitingTZ": "2017-09-16T16:23:25.639+0300", "transactionId": "01e782bf-859f-418b-b016-9ccb8c925ce1", "frameUrl": "https://inecopay.ru/inecogate/inecogate.jsp?uid=01e782bf-859f-418b-b016-9ccb8c925ce1", "paymentTypeId": 14, "shipped": false, "timestampWaiting": "2017-09-16 16:23:25", "timestampRegistered": "2017-09-16 15:53:25", "statusName": "CREATED", "currency": "RUB", "typeId": 1, "id": 23636, "partnerId": 1007, "currencyCode": 643, "statusCode": 0 }
После этого в системе сформирован платеж, который имеет статус «CREATED«. Далее в случае оплаты картой происходит переход на страницу (URL передается в поле frameUrl) ввода реквизитов карты и авторизация по карте.
Вызов методом POST.
-
/gate/confirm
Сервис подтверждения платежа, выполненного через двухстадийную оплату и имеющего статус «APPROVED«. После его вызова транзакция переходит в статус «DEPOSITED«.
Вызов методом POST.
Необходимые входные параметры — transactionId и один из параметров sessionId/sign.
Коды ответа:
Пример успешного ответа:
{ "errorMessage": "Успешно", "errorCode": "0" }
-
/gate/cancel
Сервис отмены платежа, выполненного через двухстадийную оплату и имеющего статус «APPROVED«. После его вызова транзакция переходит в статус «REVERSED«,
Вызов методом POST.
Необходимые входные параметры — transactionId и один из параметров sessionId/sign.
Пример успешного ответа:
{ "errorMessage": "Успешно", "errorCode": "0" }
-
/gate/refund
Сервис для возврата платежа. Применим только к транзакциям со статусом «DEPOSITED«. Создается новая транзакция возврата, сумма этой транзакции не может быть больше суммы платежа.
Вызов методом POST.
Необходимые входные параметры — transactionId, amount и один из параметров sessionId/sign.
Транзакций возврата может быть несколько (несколько частичных возвратов). Сумма всех транзакций возврата не может превышать сумму исходной оплаты, в противном случае на запрос вернется код ответа 414.
Пример ответа на ошибочный запрос:
{ "errorCode": "414", "errorNote": "Сумма возврата превышает сумму списания", "errorUrl": "https://inecopay.ru/inecogate/errors?code=414" }
Пример успешного ответа:
{ "errorMessage": "Успешно", "errorCode": "0" }