API Описание

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

    API содержит 5 основных сервисов для завершения полного цикла приема платежа.

    Снимок экрана 2016-07-06 в 15.53.50

  1. status —  проверка статуса и получение подробный информации о платеже.
  2. register — регистрация заказа для получения ссылки на платежную страницу.
  3. confirm — применяется при двухстадийной оплате для подтверждения платежа.
  4. cancel — применяется при двухстадийной оплате для отмены платежа.
  5. refund — полный или частичный возврат уже подтвержденной оплаты.

Подробное описание сервисов

  • /gate/status

Сервис status предназначен для получения данных о состоянии ,статусе и данных транзакции.

Снимок экрана 2016-07-06 в 16.26.46

Вызов методом 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.

register1 register2

Необходимые входные параметры: partnerId, paymentType, amount и sign (в случае, если в настройках интеграции настроена ЭЦП).
При отсутствии параметров successUrl и failUrl, данные берутся из настроек кабинета (раздел Интеграция).

Коды ответа:

register3

Пример ответа:

{
 "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.

confirm1

Необходимые входные параметры — transactionId и один из параметров sessionId/sign.

Коды ответа:

confirm2

Пример успешного ответа:

{
 "errorMessage": "Успешно",
 "errorCode": "0"
}

 

  • /gate/cancel

Сервис отмены платежа, выполненного через двухстадийную оплату и имеющего статус «APPROVED«. После его вызова транзакция переходит в статус «REVERSED«,
Вызов методом POST.

cancel

Необходимые входные параметры — transactionId и один из параметров sessionId/sign.

Пример успешного ответа:

{
 "errorMessage": "Успешно",
 "errorCode": "0"
}

 

Сервис для возврата платежа. Применим только к транзакциям со статусом «DEPOSITED«. Создается новая транзакция возврата, сумма этой транзакции не может быть больше суммы платежа.
Вызов методом POST.

refund

Необходимые входные параметры — transactionId, amount и один из параметров sessionId/sign.

Транзакций возврата может быть несколько (несколько частичных возвратов). Сумма всех транзакций возврата не может превышать сумму исходной оплаты, в противном случае на запрос вернется код ответа 414.

refund2

Пример ответа на ошибочный запрос:

{
 "errorCode": "414",
 "errorNote": "Сумма возврата превышает сумму списания",
 "errorUrl": "https://inecopay.ru/inecogate/errors?code=414"
}

Пример успешного ответа:

{
 "errorMessage": "Успешно",
 "errorCode": "0"
}