Настоящий документ описывает принципы подключения и программные интерфейсы платежной платформы — 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"
}