sun-img
moon-img

Обзор API

Протокол реализуется мерчантом при подключении к процессинговому центру ТЕКО.

  • Запросы и ответы для передачи прикладной информации используют JSON.
  • Запрос должен содержать тело с JSON-запросом.
  • Не смотря на JSON, протокол является строго типизированным.
  • Все ответы приходят в обертке { success: true/false, result: {...} }

Безопасность

Общение происходит только по протоколу HTTPS (не актуально для тестовой среды).

Каждый запрос к API должен содержать поле client и заголовок (HTTP header) Signature. Пример HTTP заголовка: "Signature: VgepHaYJBn9jwAg3N6wzFhi8UeQ="

Для вычисления подписи Signature используется алгоритм HMAC-SHA1.Подписи подлежит:

  • В случае POST запроса (тело запроса)
  • В случае GET запроса (GET параметры)
Bash code
echo -n "REQUEST_BODY" | openssl dgst -binary -sha1 -hmac "SECRET_KEY" | openssl base64

Типы данных

  • Int

    Целочисленный тип. Эквивалентен BigInt в Scala

  • Float

    Число с плавающей точкой. Эквивалентен Double

  • String

    Строка

  • List[type]

    Список элементов определенного типа. В JSON представляется массивом

  • Enum

    Строка с фиксированным набором значений

  • JSON

    JSON объект со свободной структурой

  • ClassName

    JSON объект с фиксированной структурой (см. раздел Классы)

  • Map

    JSON объект вида { key: value, ... }, где key и value могут быть только строками

Классы

Классы бывают двух типов: простые, включающие в себя только примитивные типы (Int, String, Float и т.д.), и сложные, включающие в себя другие классы помимо примитивных типов

Client

Информация о клиенте

  • idStringrequired

    Идентификатор клиента

  • showcaseStringrequired

    Идентификатор витрины клиента

Transaction

Информация о транзакции

  • idStringrequired

    Идентификатор транзакции

  • start_tNumberrequired

    Время начала в миллисекундах

  • finish_tNumberoptional

    Время окончания в миллисекундах
Transaction object
{
  "id": "9af8498e-9b81-11e4-9169-3c15c2d429ea",
  "start_t": 1421197379341
}

Payment

Информация о сумме платежа и валюте

  • amountIntrequired

    Сумма в минорных единицах валюты

  • currencyIntrequired

    Валюта (ISO код)

  • exponentIntrequired

    Количество знаков после запятой
Payment object
{
  "amount": 10000,
  "currency": 643,
  "exponent": 2
}

Payer

Информация о плательщике

  • clsEnumrequired

    Категория источника средств оплаты.
    Возможные значения:
    mc - мобильная коммерция
    card - банковская карта
    cpa - оплата услугами связи
    e_wlt - электронные кошельки
    cash - наличные
Если cls == "mc"

  • phone_numberStringrequired

    Номер телефона в формате
    79993332211
    (код страны, префикс, номер абонента без пробелов и знаков)

  • operatorEnum

    Наименование Оператора.
    Поле является обязательным только в ответах от системы,
    в запросах его можно опустить
Если cls == "card"

  • idStringrequired

    Hash карты, полученный от сервиса хэширования ДДК,
    либо 'unknown' в случае неизвестных ДДК.

  • payment_systemEnumoptional

    Платежная система.
    Возможные значения:
    plastic_card - в случае, когда процессингу нужно будет вернуть форму для заполнения ДДК
    visa
    master_card
    visa_electron
    maestro

  • extraJSONoptional

    Различные дополнительные сведения
Если cls == "cpa"

  • phone_numberStringrequired

    Номер телефона в формате
    79993332211
    (код страны, префикс, номер абонента без пробелов и знаков)

  • operatorEnum

    Наименование Оператора.
    Поле является обязательным только в ответах от системы, в запросах его можно опустить
Если cls == "e_wlt"

  • payment_systemEnumrequired

    Наименование платежной системы

  • idStringrequired

    Идентификатор пользователя в платежной системе

  • extraJSONoptional

    Дополнительные поля для некоторых платежных систем
Payer object
{
  "cls": "mc",
  "phone_number": "79993332211"
}

Theme

Параметры цветовой схемы

  • primaryBgColorStringrequired

    Цвет фона на форме в CSS совместимом формате.
    Примеры: #00ff00, red

  • primaryTextColorStringoptional

    Цвет текста на форме в CSS совместимом формате.
    Примеры: #ffffff, white
Theme object
{
  "primaryBgColor": "#00ff00",
  "primaryTextColor": "#ffffff"
}

Product

Информация о выбранном товаре

  • urlString

    URL сайта мерчанта

  • idString

    Идентификатор товара в системе ТЕКО

  • nameString

    Название товара, отображаемое покупателю

  • redirectUrlString

    URL редиректа после совершения платежа
Product object
{
  "url": "https://teko.io",
  "id": "Teko",
  "name": "Тариф E-commerce",
  "redirectUrl": "https://teko.io"
}

AmountOptions

Настройки выбора суммы платежа

  • titleString

    Название экрана выбора суммы

  • amountOptionsList[Number]

    Варианты сумм, которые доступны для оплаты

  • defaultAmountOptionNumber

    Выбранное значение по умолчанию

  • useAmountInputBoolean

    Может ли покупатель сам вводить сумму
AmountOptions object
{
  "title": "Однократно",
  "amountOptions": [
    10000,
    30000,
    50000,
    100000,
    300000,
    500000
  ],
  "defaultAmountOption": 10000,
  "withYourAmountInput": true
}

Account

Информация о пользователе

  • idStringrequired

    Идентификатор пользователя в системе мерчанта

  • extraJSONoptional

    Дополнительные поля для мерчанта
Account object
{
  "id": "login",
  "extra": {
    "premium": true,
    "game_server": "Europe"
  }
}

Item

Информация о товаре

  • idIntrequired

    Идентификатор товара, согласованный с мерчантом

  • nameStringrequired

    Название товара, согласованное с мерчантом

  • countIntoptional

    Количество предметов. Может быть опущено для неисчисляемых товаров.
Item object
{
  "id": 121,
  "name": "Gold",
  "count": 100500
}

Order

Описание заказа

  • clsEnumrequired

    Может принимать значения:
    item_list - список товаров в
    системе мерчанта
    transaction - идентификатор
    сформированного заказа
    в системе мерчанта 
    transfer - просто перевод денег,
    все остальные поля
    становятся необязательными
Если cls == "item_list"

  • item_listList[item]required

    Список покупок.
    Подробнее в классе Item
Если cls == "transaction"

  • transactionTransactionrequired

    Информация о транзакции в системе мерчанта

  • extraJSONoptional

    Будет передаваться мерчанту в неизменном виде
Order object
{
  "cls": "item_list",
  "item_list": [
    {
      "id": 121,
      "name": "Gold",
      "count": 100500
    }
  ]
}

Status

Статуса платежа

  • clsEnumrequired

    Возможные значения:
    success - транзакция завершена успешно
    failed - транзакция завершена ошибкой
    redirect - для продолжения необходимо
    переадресовать пользователя
    pending - транзакция в процессе
Если cls == "redirect"

  • redirectRedirectrequired

    Объект для перенаправления пользователя
Если cls == "failed"

  • codeIntrequired

    Код ошибки

  • descriptionStringrequired

    Описание ошибки
Status object
{
  "cls": "failed",
  "code": 1144,
  "description": "provider is unavailable"
}

Redirect

Поля класса Redirect

  • methodEnumrequired

    Возможные значения:
    GET
    POST

  • urlStringrequired

    Адрес для перенаправления пользователя

  • paramsMaprequired

    Параметры запроса (могут быть пустым объектом вида {})
Redirect object
{
  "method": "GET",
  "url": "https://api.teko.io/api-reference",
  "params": {}
}

MerchantTransaction

  • merchant_idStringoptional

    Идентификатор мерчанта

  • idStringoptional

    Идентификатор транзакции

  • extraJSONoptional

    Дополнительные поля транзакции

CatalogItem

  • idStringrequired

    Идентификатор товара

  • nameStringoptional

    Название товара

  • catStringoptional

    Категория

  • subcatStringoptional

    Подкатегория

  • innerStringoptional

    Выражение для заполнения поля dst.id при платеже

  • minIntoptional

    Минимальная сумма платежа

  • maxIntoptional

    Максимальная сумма платежа

  • commentStringoptional

    Комментарий

  • isActiveBooleanoptional

    Вкл/выкл

  • toSaveBooleanoptional

  • historyTagsList[String]optional

CatalogItemField

  • field_nameStringrequired

    Название поля

  • typeEnumoptional

    Может принимать одно из значений: text, amount, number, date, phone, enum, address

  • captionStringoptional

  • requiredBooleanoptional

  • reg_exStringoptional

  • min_lengthIntoptional

  • max_lengthIntoptional

  • placeholderStringoptional

  • commentStringoptional

  • conditionStringoptional

  • visualVisualoptional

    JSON из трех полей:
    size: Int,
    offset: Int,
    post: Int

  • toSaveBooleanoptional

  • itemsList[CatalogEnumValue]optional

    CatalogEnumValue - JSON из 2-х полей:
    name: String,
    value: String

Коды ошибок

  • 42

    Сервис временно недоступен

  • 201

    Ошибка на стороне получателя средств

  • 300

    Отказ клиента в процессе подтверждения платежа

  • 301

    Не получено подтверждение клиента

  • 302

    Техническая ошибка. Необходимо провести платёж снова. При повторении ошибки обратитесь техническую поддержку

  • 305

    Услуга недоступна для данного источника средств

  • 306

    Нарушен один из лимитов (сумма, количество попыток и т.п.) или у данного клиента существует незавершенный платёж

  • 307

    Недостаточно денежных средств

  • 308

    Для данной карты услуга не доступна. Истек срок действия или существуют ограничения со стороны эмитента

  • 309

    При оплате была указана неверная сумма платежа или неверный номер счета

  • 310

    Ошибка идентификации источника средств

  • 311

    Указан неверный номер телефона или параметры товара

  • 312

    Операция завершена

  • 399

    Техническая ошибка на стороне источника денежных средств

  • 401

    Некорректная подпись

  • 402

    Некорректный запрос

  • 601

    Некорректные параметры платежа

  • 602

    Некорректная валюта

  • 603

    Некорректный метод оплаты

  • -1

    Неизвестная ошибка

Протокол инициатора

Предназначен для инициализации платежа, отслеживания информации и проведения возврата по успешному платежу, а также отмены платежа через шлюз Teko.

Endpoints

Обзор протокола

  • Протокол использует REST архитектуру
  • В нем присутствуют 3 метода [initPayment, getPaymentStatus, оповещение об изменении статуса платежа], после реализации они должны отправлять POST-запрос на шлюз Теко и отображать полученный ответ
  • Во время настройки и отладки протокола используется тестовая среда - playground
  • URL для отправки тестовых запросов - http://pg.teko.io/api/initiators/default/[Имя метода]
  • Вместо [Имя метода] нужно подставить имя небходимого метода, например: http://pg.teko.io/api/initiators/default/initPayment
  • Для передачи информации в запросах и ответах используется формат JSON
  • Каждый запрос должен содержать заголовок (HTTP header) "Content-Type" со значением "application/json"
  • Не смотря на JSON, протокол является строго типизированным
  • Все ответы приходят в обертке { success: true/false, result: {...} }

В рамках стандартного флоу необходимо реализовать метод initPayment. В случае, если в запросе initPayment заполнен параметр callback, Вам придет оповещение об изменении статуса платежа по его завершению. Иначе Вам необходимо самостоятельно узнавать об успешности завершения платежа с помощью запроса getPaymentStatus.

Также протокол предоставляет дополнительные методы:
  • Инициализация платежа с возможностью перенаправления пользователя на платежную форму (initRedirectPayment)
  • Проведение возврата (rollbackPayment)
  • Получения подробной информации о совершенных транзакциях (getPaymentById, getPaymentsByTag)

initPayment

Запрос на инициализацию платежа.

Является POST-запросом на шлюз.

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

Запрос

  • clientClientrequired

    Идентификатор пользователя API

  • productStringrequired

    Наименование продукта (проекта)

  • paymentPaymentrequired

    Информация о сумме платежа и валюте

  • srcPayerrequired

    Информация об аккаунте плательщика в платежной системе

  • dstAccountrequired if (order.cls == "item_list" || order.cls == "transfer")

    Информация об аккаунте в проекте

  • orderOrderrequired

    Информация о назначении платежа

  • extraJSONoptional

    json объект с дополнительной информацией

  • callbackStringoptional

    URL, на который придет оповещение по завершению платежа. Указать, если такое оповещение нужно. Паттерн 'https://*'

  • security_extraJSONoptional

    Предназначено для антифрод системы (необходимость передачи параметра определяется индивидуально при согласовании подключения)

  • tagStringoptional

    Строковая метка для поиска платежей в системе Теко (Запрещено использование символа |). Например, после инициации платежей с полем tag == "Europe" в будущем можно запросить список всех платежей с соответствующим полем tag при помощи запроса getPaymentsByTag
Ответ

  • successBooleanrequired

    Индикатор успешности
Если success == true

  • result.txTransactionrequired

    Идентификатор транзакции процессинга
Если success == false

  • result.codeIntrequired

    Код ошибки

  • result.descriptionStringrequired

    Описание ошибки
post
/api/initiators/default/initPayment
{
  "client": {
    "id": "company_name",
    "showcase": "mobile_app"
  },
  "product": "world_of_warcraft",
  "payment": {
    "amount": 10000,
    "currency": 643,
    "exponent": 2
  },
  "src": {
    "cls": "mc",
    "phone_number": "79163332211",
    "operator": "mts_ru"
  },
  "dst": {
    "id": "Y6UBATOP9000",
    "extra": {
      "premium": true,
      "game_server": "Europe"
    }
  },
  "order": {
    "transaction": {
      "id": "1122334455",
      "start_t": 1428430631504
    },
    "cls": "transaction",
    "extra": {
      "from": "mobile_app",
      "some_key": "some_value"
    }
  },
  "extra": {
    "from": "mobile_app",
    "some_key": "some_value"
  },
  "callback": "https://companydomain.com",
  "tag": "Europe"
}
response
{
  "success": true,
  "result": {
    "tx": {
      "id": "55d8fb900cf23b38021b7c65",
      "start_t": 1440283536655
    }
  }
}
response
{
  "success": false,
  "result": {
    "code": 401,
    "description": "invalid signature"
  }
}

initRedirectPayment

Запрос на инициализацию платежа с возможностью перенаправить пользователя напрямую на платежную форму.

Запрос

  • clientClientrequired

    Идентификатор пользователя API

  • productStringrequired

    Наименование продукта (проекта)

  • paymentPaymentrequired

    Информация о сумме платежа и валюте

  • srcPayerrequired

    Информация об аккаунте плательщика в платежной системе

  • dstAccountrequired

    Информация об аккаунте в проекте

  • orderOrderrequired

    Информация о назначении платежа

  • extraJSONoptional

    json объект с дополнительной информацией

  • callbackStringoptional

    URL, на который придет оповещение по завершению платежа. Указать, если такое оповещение нужно. Паттерн 'https://*'

  • security_extraJSONoptional

    Предназначено для антифрод системы (необходимость передачи параметра определяется индивидуально при согласовании подключения)

  • tagStringoptional

    Строковая метка для поиска платежей в системе Теко (Запрещено использование символа |). Например, после инициации платежей с полем tag == "Europe" в будущем можно запросить список всех платежей с соответствующим полем tag при помощи запроса getPaymentsByTag
Ответ

  • successBooleanrequired

    Индикатор успешности
Если success == true

  • result.txTransactionrequired

    Идентификатор транзакции процессинга

  • result.tx.start_tTransactionrequired

    Время создания транзакции в процессинге

  • result.tx.finish_tTransactionoptional

    Время окончания транзакции в процессинге

  • result.statusStatusoptional

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

  • result.status.clsStatusrequired

    Статус транзакции в процессинге

  • result.status.redirect.methodStatusrequired

    HTTP Метод, используемый при перенаправлении

  • result.status.redirect.urlStatusrequired

    URL для перенаправления пользователя

  • result.status.redirect.paramsStatusrequired

    Параметры запроса для перенаправления (это могут быть параметры для POST запроса с media-type application/x-www-form-urlencoded, например, параметры для прохождения 3DSecure)
Если success == false

  • result.codeIntrequired

    Код ошибки

  • result.descriptionStringrequired

    Описание ошибки
Инициация оплаты по кнопке YandexPay

Данный метод также позволяет инициировать оплату по кнопке YandexPay, встроенной в Вашу платежную форму. Источником платежа служит банковская карта (Payer.cls == “card”). Для встраивания кнопки и дальнейшей обработки платежа шлюзом Теко необходимо:

  1. Подключить кнопку на сайте, руководствуясь следующей документацией: https://yandex.ru/dev/yandex-pay/doc/tutorial/index.html.
  2. После оформления заказа получить из кнопки PaymentToken (в нем в зашифрованном виде передаются платежные данные).
  3. PaymentToken передать в платежный шлюз Теко в виде строки в поле order.extra.yandexPaymentToken.
  4. В поле src.id необходимо передать строку "yandexPaymentToken" (константа).
  5. Результат платежа необходимо получить самостоятельно с помощью запроса на шлюз getPaymentStatus.
post
/api/initiators/default/initRedirectPayment
{
  "client": {
    "id": "company_name",
    "showcase": "mobile_app"
  },
  "product": "world_of_warcraft",
  "payment": {
    "amount": 10000,
    "currency": 643,
    "exponent": 2
  },
  "src": {
    "cls": "mc",
    "phone_number": "79163332211",
    "operator": "mts_ru"
  },
  "dst": {
    "id": "Y6UBATOP9000",
    "extra": {
      "premium": true,
      "game_server": "Europe"
    }
  },
  "order": {
    "transaction": {
      "id": "1122334455",
      "start_t": 1428430631504
    },
    "cls": "transaction",
    "extra": {
      "from": "mobile_app",
      "some_key": "some_value"
    }
  },
  "extra": {
    "from": "mobile_app",
    "some_key": "some_value"
  },
  "callback": "https://companydomain.com",
  "tag": "Europe"
}
response
{
  "success": true,
  "result": {
    "tx": {
      "id": "55241f34a7c82fc5f202ca21",
      "start_t": 1428430644807,
      "finish_t": 1428430647904
    },
    "status": {
      "cls": "redirect",
      "redirect": {
        "method": "POST",
        "url": "https://redirectPaymentSite.com",
        "params": {
          "token": "871199b37f207f0c4f725a37cdcc71dfcea880b4a4b65e3cf852c5dc1e99a8d6"
        }
      }
    }
  }
}
response
{
  "success": false,
  "result": {
    "code": 401,
    "description": "invalid signature"
  }
}
post
/api/initiators/default/initRedirectPayment
{
  "client": {
    "id": "company_name",
    "showcase": "mobile_app"
  },
  "product": "world_of_warcraft",
  "payment": {
    "amount": 10000,
    "currency": 643,
    "exponent": 2
  },
  "src": {
    "cls": "card",
    "id": "yandexPaymentToken",
    "extra": {
      "key": "value"
    }
  },
  "dst": {
    "id": "Y6UBATOP9000",
    "extra": {
      "premium": true,
      "game_server": "Europe"
    }
  },
  "order": {
    "transaction": {
      "id": "1122334455",
      "start_t": 1428430631504
    },
    "cls": "transaction",
    "extra": {
      "yandexPaymentToken": "ewoidHlwZSI6ICJZYW5kZXgiLAoic2lnbmVkTWVzc2FnZSI6ICJ7XCJlbmNyeXB0ZWRNZXNzY Wdl XCI6XCIzRUlHSGhhUldsTEJZM0NRNCtoTVdmYmlFOHZETHkydndHNVZrWTVYZ0lMYXE1V mpoLwpN RUQ1WE8xdzZLd1duUWlUM1RKRFY1cmovaXhMSHpQanBONGVVd2thUVRnd1VjRkdZU0Ni d3U0cGFC aHVhT2xZS3Z4M1VoeGxHcworc1dmQ3hsSkhhd0ZXbEVjWDI1NHUvNHljNDVDbklBbWFKTEd SN1JM dkFYNjZWT2lDTy8KR3BlcVBaWHBjdFJ6ajA2OFRUaEVTbVJLdi8yVmI5UzU0Q1JJRDFaMCtR SWFt Wkl3b0toa0V0OTlGMEVYd25mS2RsemFrcEwKK040aTk5WDNFa2F2UUEySW0zbEZKNkM5T XZJS3Fh aG5ORjlFODlNSUFpZ3NuWVorL1p1N1F2dGZBZTFtVmJMRE1HSlJGcWs3TllGMFEvClhYcnd hakpD TUZjQ3ZUTmtTWGgwV215V0k3RmE5cjErRXlkSm1hb3UxWFRvL1JVdnZiZkozbDdhc2VwY3Z GY3M3 d2NLVWdpOXdXR0tlOXRkMG55NEVxelZpKytobS8KWmlKaGNTa25RQndzTkJTSE95N2FKWl ZveEk1 RFVMN2dFVjdYM0tBUzBRXCIsXCJ0YWdcIjpcIm5QQ2tCZFhnZHZiK1ZoVFNNNVJjOVFkdkV wUEZk MW1OdFN5RTBjV0N1WlU9XCIsClwiZXBoZW1lcmFsUHVibGljS2V5XCI6XCJCRmlnMnFxR0h zWC9M QTZHckZiSGNHODNlTGpUQWlCa1RUa0plNWxraTM3V01NWlVKamZUOHRUTE9kK3ZoUm1r SXJ1NGhj TVJmcHhmRVIxM1dJaE5heUU9ClwifSIsCiJwcm90b2NvbFZlcnNpb24iOiAiRUN2MiIsCiJzaWdu YXR1cmUiOiAiTUVVQ0lRRE9CU1NCMXlGbTNFOWdNMWtUcDNDSE1raEhNMWc0ZHNZS28 5L1RYaUVo bXdJZ1NNQ3AydDF0Q29yQmpoR3cxazlFdjl0dzRJeUtWVXJNQWJKbmZBZzBOZzA9IiwKImlu dGVy bWVkaWF0ZVNpZ25pbmdLZXkiOiB7CiJzaWduZWRLZXkiOiAie1wia2V5VmFsdWVcIjpcIk1Ga 3dF d1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRXFZTmVQdDZCUGdDdjVKeGZPOW RGMnZyU3Ft bnA0TWhlL3ZGK1hPK0RldmJzNi8KS1ZwVlZvVEQ4TExjQW80VFpoNkl1T0RWblZwSHJUT2Jo ZzNI SlZKQT09XCIsXCJrZXlFeHBpcmF0aW9uXCI6XCIxNzY0OTUwODkyMDAwXCJ9IiwKInNpZ25 hdHVy ZXMiOiBbCiJNRVFDSURSc2xNVzd3TlpicHFWdy9kRDdoRFFoMzBoR2hxZmpmV1RCdmM3ek FZSlNB aUFHQXZqQXNsQTJBeHdkQUV1T2ZhY0ZyNkRhRTV5aWlVdVV0TTZEVXJlWllnPT0iCl0KfQp 9"
    }
  },
  "extra": {
    "from": "mobile_app",
    "some_key": "some_value"
  },
  "callback": "https://companydomain.com",
  "tag": "Europe"
}
response
{
  "success": true,
  "result": {
    "tx": {
      "id": "55d8fb900cf23b38021b7c65",
      "start_t": 1440283536655
    }
  }
}
response
{
  "success": false,
  "result": {
    "code": 444,
    "description": "PaymentToken processing error"
  }
}

getPaymentsByTag

Запрос на получение информации о всех платежах по указанному полю tag

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

Запрос

  • clientStringrequired

    Идентификатор пользователя API

  • tagStringrequired

    Строковая метка для поиска списка всех платежей с соответствующим полем tag в системе Теко (Запрещено использование символа |).
Ответ

  • successBooleanrequired

    Индикатор успешности
Если success == true

  • result.payments.tx.idTransactionrequired

    Идентификатор транзакции процессинга

  • result.payments.tx.start_tTransactionrequired

    Время создания транзакции в процессинге

  • result.payments.tx.finish_tTransactionoptional

    Время окончания транзакции в процессинге

  • result.payments.status.clsStatusrequired

    Статус транзакции в процессинге

  • result.payments.productStringrequired

    Наименование продукта (проекта)

  • result.payments.payment.amountPaymentrequired

    Сумма в минорных единицах валюты

  • result.payments.payment.currencyPaymentrequired

    Валюта (ISO код)

  • result.payments.payment.exponentPaymentrequired

    Количество знаков после запятой

  • result.payments.src.clsPayerrequired

    Категория источника средств оплаты

  • result.payments.src.phone_numberPayerrequired

    Номер телефона

  • result.payments.src.operatorPayeroptional

    Наименование оператора

  • result.payments.dst.idAccountrequired

    Идентификатор пользователя в системе мерчанта

  • result.payments.dst.extraAccountoptional

    Дополнительные поля для мерчанта

  • result.payments.extraJSONoptional

    json объект с дополнительной ифнормацией

  • result.payments.order.clsOrderrequired

    Назначение платежа

  • result.payments.order.transaction.idOrderrequired

    Идентификатор транзакции, согласованный с мерчантом

  • result.payments.order.transaction.start_tOrderrequired

    Время начала транзакции

  • result.payments.order.extraOrderoptional

    Дополнительная информация о платеже

  • result.payments.tagStringoptional

    строковая метка, по которой возвращается список транзакций
Если success == false

  • result.codeIntrequired

    Код ошибки

  • result.descriptionStringrequired

    Описание ошибки
post
/api/initiators/default/getPaymentsByTag
{
  "client": {
    "id": "test_client",
    "showcase": "showcases"
  },
  "tag": "Europe"
}
response
{
  "success": true,
  "result": {
    "payments": [
      {
        "tx": {
          "id": "55241f34a7c82fc5f202ca21",
          "start_t": 1428430644807,
          "finish_t": 1428430647904
        },
        "status": {
          "cls": "success"
        },
        "product": "world_of_warcraft",
        "payment": {
          "amount": 10000,
          "currency": 643,
          "exponent": 2
        },
        "src": {
          "cls": "mc",
          "phone_number": "79163332211",
          "operator": "mts_ru"
        },
        "dst": {
          "id": "Y6UBATOP9000",
          "extra": {
            "premium": true,
            "game_server": "Europe"
          }
        },
        "extra": {
          "from": "mobile_app",
          "some_key": "some_value"
        },
        "order": {
          "transaction": {
            "id": "1122334455",
            "start_t": 1428430631504,
            "finish_t": 1428430631907
          },
          "cls": "transaction",
          "extra": {
            "from": "mobile_app",
            "some_key": "some_value"
          }
        },
        "tag": "Europe"
      },
      {
        "tx": {
          "id": "6170372abf028f6e56db0116",
          "start_t": 1428530644807,
          "finish_t": 1428530647904
        },
        "status": {
          "cls": "success"
        },
        "product": "world_of_warcraft",
        "payment": {
          "amount": 10000,
          "currency": 643,
          "exponent": 2
        },
        "src": {
          "cls": "mc",
          "phone_number": "79163332211",
          "operator": "mts_ru"
        },
        "dst": {
          "id": "Y6UBATOP9000",
          "extra": {
            "premium": true,
            "game_server": "Europe"
          }
        },
        "extra": {
          "from": "mobile_app",
          "some_key": "some_value"
        },
        "order": {
          "transaction": {
            "id": "1122334466",
            "start_t": 1428430644908,
            "finish_t": 1428430651041
          },
          "cls": "transaction",
          "extra": {
            "from": "mobile_app",
            "some_key": "some_value"
          }
        },
        "tag": "Europe"
      }
    ]
  }
}
response
{
  "success": false,
  "result": {
    "code": 401,
    "description": "invalid signature"
  }
}

getPaymentById

Запрос для получения подробной информации о совершенной транзакциии по id.

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

Запрос

  • clientStringrequired

    Идентификатор пользователя API

  • tx_idStringrequired

    Идентификатор платежа в системе Теко (из ответа на запрос initPayment)
Ответ

  • successBooleanrequired

    Индикатор успешности
Если success == true

  • result.payments.tx.idTransactionrequired

    Идентификатор транзакции процессинга

  • result.payments.tx.start_tTransactionrequired

    Время создания транзакции в процессинге

  • result.payments.tx.finish_tTransactionoptional

    Время окончания транзакции в процессинге

  • result.payments.status.clsStatusrequired

    Статус транзакции в процессинге

  • result.payments.productStringrequired

    Наименование продукта (проекта)

  • result.payments.payment.amountPaymentrequired

    Сумма в минорных единицах валюты

  • result.payments.payment.currencyPaymentrequired

    Валюта (ISO код)

  • result.payments.payment.exponentPaymentrequired

    Количество знаков после запятой

  • result.payments.src.clsPayerrequired

    Категория источника средств оплаты

  • result.payments.src.phone_numberPayerrequired

    Номер телефона

  • result.payments.src.operatorPayeroptional

    Наименование оператора

  • result.payments.dst.idAccountrequired

    Идентификатор пользователя в системе мерчанта

  • result.payments.dst.extraAccountoptional

    Дополнительные поля для мерчанта

  • result.payments.extraJSONoptional

    json объект с дополнительной ифнормацией

  • result.payments.order.clsOrderrequired

    Назначение платежа

  • result.payments.order.transaction.idOrderrequired

    Идентификатор транзакции, согласованный с мерчантом

  • result.payments.order.transaction.start_tOrderrequired

    Время начала транзакции

  • result.payments.order.extraOrderoptional

    Дополнительная информация о платеже

  • result.payments.tagStringoptional

    строковая метка, по которой возвращается список транзакций
Если success == false

  • result.codeIntrequired

    Код ошибки

  • result.descriptionStringrequired

    Описание ошибки
post
/api/initiators/default/getPaymentById
{
  "client": {
    "id": "test_client",
    "showcase": "showcases"
  },
  "tx_id": "55241f34a7c82fc5f202ca21"
}
response
{
  "success": true,
  "result": {
    "payment": {
      "tx": {
        "id": "55241f34a7c82fc5f202ca21",
        "start_t": 1428430644807,
        "finish_t": 1428430647904
      },
      "status": {
        "cls": "success"
      },
      "product": "world_of_warcraft",
      "payment": {
        "amount": 10000,
        "currency": 643,
        "exponent": 2
      },
      "src": {
        "cls": "mc",
        "phone_number": "79163332211",
        "operator": "mts_ru"
      },
      "dst": {
        "id": "Y6UBATOP9000",
        "extra": {
          "premium": true,
          "game_server": "Europe"
        }
      },
      "extra": {
        "from": "mobile_app",
        "some_key": "some_value"
      },
      "order": {
        "transaction": {
          "id": "1122334455",
          "start_t": 1428430631504,
          "finish_t": 1428430631804
        },
        "cls": "transaction",
        "extra": {
          "from": "mobile_app",
          "some_key": "some_value"
        }
      },
      "tag": "Europe"
    }
  }
}
response
{
  "success": false,
  "result": {
    "code": 401,
    "description": "invalid signature"
  }
}

getPaymentStatus

Запрос на получение статуса платежа.

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

Запрос

  • clientStringrequired

    Идентификатор пользователя API

  • tx_idStringrequired

    Id транзакции процессинга
Ответ

  • successBooleanrequired

    Индикатор успешности
Если success == true

  • result.txTransactionrequired

    Идентификатор транзакции на процессинге

  • result.statusStatusrequired

    Статус платежа
post
/api/initiators/default/getPaymentStatus
{
  "client": {
    "id": "test_client",
    "showcase": "showcases"
  },
  "tx_id": "55241f34a7c82fc5f202ca21"
}
response
{
  "success": true,
  "result": {
    "tx": {
      "id": "55d8fb900cf23b38021b7c65",
      "start_t": 1440283536655,
      "finish_t": 1440283542127
    },
    "status": {
      "cls": "success"
    }
  }
}
response
{
  "success": false,
  "result": {
    "code": 401,
    "description": "invalid signature"
  }
}

rollbackPayment

Запрос на возврат денежных средств после успешного проведения платежа.

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

Запрос

  • clientClientrequired

    Идентификатор пользователя API

  • productStringrequired

    Наименование продукта (проекта)

  • paymentPaymentrequired

    Информация о сумме платежа и валюте

  • dstAccountrequired

    Информация об аккаунте в проекте

  • orderOrderrequired

    Информация о назначении платежа

  • txTransactionrequired

    Транзакция в системе Теко

  • codeIntrequired

    Код причины возврата

  • descriptionStringrequired

    Описание причины возврата

  • partner_txTransactionrequired

    Транзакция в системе инициатора

  • security_extraJSONoptional

    Предназначено для антифрод системы (необходимость передачи параметра определяется индивидуально при согласовании подключения)

  • extraJSONoptional

    json объект с дополнительной информацией
Ответ

  • successBooleanrequired

    Индикатор успешности
Если success == true и по транзакции ранее уже был совершен возврат:

  • result.tx.idTransactionrequired

    Идентификатор транзакции процессинга

  • result.tx.start_tTransactionrequired

    Время создания транзакции в процессинге

  • result.tx.finish_tTransactionoptional

    Время окончания транзакции в процессинге
Если success == true и по транзакции ранее возвратов не проводилось:

  • result.rollbackTypeStringrequired

    Тип операции возврата (принимает значение "cancel", если день запроса операции возврата совпадает с днем окончания транзакции, иначе - "refund")

  • result.tx.idTransactionrequired

    Идентификатор транзакции процессинга

  • result.tx.start_tTransactionrequired

    Время создания транзакции в процессинге

  • result.tx.finish_tTransactionoptional

    Время окончания транзакции в процессинге
Если success == false

  • result.codeIntrequired

    Код ошибки

  • result.descriptionStringrequired

    Описание ошибки
post
/api/initiators/default/rollbackPayment
{
  "client": {
    "id": "company_name",
    "showcase": "mobile_app"
  },
  "product": "world_of_warcraft",
  "payment": {
    "amount": 10000,
    "currency": 643,
    "exponent": 2
  },
  "dst": {
    "id": "Y6UBATOP9000",
    "extra": {
      "premium": true,
      "game_server": "Europe"
    }
  },
  "order": {
    "transaction": {
      "id": "1122334455",
      "start_t": 1428430631504,
      "finish_t": 1428430631905
    },
    "cls": "transaction",
    "extra": {
      "from": "mobile_app",
      "some_key": "some_value"
    }
  },
  "tx": {
    "id": "55241f34a7c82fc5f202ca21",
    "start_t": 1428430644807
  },
  "code": 250,
  "description": "Неверный формат счета/телефона",
  "partner_tx": {
    "id": "13584192567",
    "start_t": 1428430644997
  },
  "extra": {
    "from": "mobile_app",
    "some_key": "some_value"
  }
}
response
{
  "success": true,
  "result": {
    "tx": {
      "id": "5152ba7fe4b08d2e1a903251",
      "start_t": 1428430644807,
      "finish_t": 1428430655917
    }
  }
}
response
{
  "success": true,
  "result": {
    "rollbackType": "refund",
    "tx": {
      "id": "5152ba7fe4b08d2e1a903251",
      "start_t": 1428430644807,
      "finish_t": 1428430655917
    }
  }
}
response
{
  "success": false,
  "result": {
    "code": 401,
    "description": "invalid signature"
  }
}

Оповещение об изменении статуса платежа

Отправляется партнеру со стороны шлюза Теко, если в запросе initPayment заполнен параметр callback.

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

Запрос

  • clientStringrequired

    Идентификатор пользователя API

  • txTransactionrequired

    Транзакция в процессинге

  • statusStatusrequired

    Статус платежа

  • partner_txTransactionoptional

    Транзакция в системе инициатора
Ответ

  • successBooleanrequired

    Индикатор успешности
Если success == false

  • result.codeIntrequired

    Код ошибки

  • result.descriptionStringrequired

    Описание ошибки
Оповещение об изменении статуса платежа request
{
  "client": {
    "id": "company_name",
    "showcase": "mobile_app"
  },
  "tx": {
    "id": "55241f34a7c82fc5f202ca21",
    "start_t": 1428430644807,
    "finish_t": 1428430655917
  },
  "partner_tx": {
    "id": "111122223333444",
    "start_t": 1428430642331
  },
  "status": {
    "cls": "success"
  }
}
response
{
  "success": false,
  "result": {
    "code": 401,
    "description": "invalid signature"
  }
}

Протокол мерчанта

Предназначен для уточнения возможности проведения платежа на стороне Мерчанта (isPaymentPossible) и для дальнейшего его проведения (resumePayment) или отмены (cancelPayment).

Endpoints

Обзор протокола

  • Реализуется мерчантом при подключении к процессинговому центру ТЕКО
  • Протокол использует REST архитектуру.
  • В нем присутствуют 4 метода [isPaymentPossible, resumePayment, cancelPayment, rollbackPayment], после реализации они должны, получив сообщение, отправлять соответствующий ответ
  • Запросы и ответы для передачи прикладной информации используют JSON
  • Во время настройки и отладки протокола используется тестовая среда - playground
  • Запрос должен содержать тело с JSON-запросом
  • Не смотря на JSON, протокол является строго типизированным
  • Все ответы приходят в обертке { success: true/false, result: {...} }
  • Каждый запрос должен содержать заголовок (HTTP header) "Content-Type" со значением "application/json"

Взаимодействие начинается с запроса isPaymentPossible со стороны шлюза Теко. После получения успешного ответа (success == true) на запрос проверки платежа начинается процесс списания денежных средств с клиента. Если списание прошло успешно, то шлюз Теко отправляет Мерчанту запрос на исполнение платежа - resumePayment, иначе будет отправлен запрос на отмену – cancelPayment.

Если ответ на resumePayment или cancelPayment является НЕуспешным (success == false), то шлюз Теко повторит запрос еще 10 раз с паузой в 30сек.

isPaymentPossible

Проверка возможности проведения платежа.

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

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

Запрос почти совпадает с методом initPayment из протокола Инициатора, за исключением того что в данном случае вы принимаете запрос, а не отправляете его, как было в протоколе Инициатора

Запрос

  • clientClientrequired

    Идентификатор пользователя API

  • productStringrequired

    Наименование продукта (проекта)

  • paymentPaymentrequired

    Информация о сумме платежа и валюте

  • src_paymentPaymentoptional

    Сумма и валюта, принятые от пользователя

  • rateFloatoptional

    Курс покупки.
    При src_payment == "100 RUB" и payment == "1 EUR", rate == 100

  • orderOrderrequired

    Информация о назначении платежа

  • txTransactionrequired

    Идентификатор транзакции в системе Теко

  • src_clsStringrequired

    Категория плательщика

  • srcPayeroptional

    Информация об аккаунте плательщика в платежной системе. Передается, если известен на этом этапе

  • dstAccountrequired if (order.cls == "item_list" || order.cls == "transfer")

    Информация об аккаунте в проекте

  • security_extraJSONoptional

    Предназначено для антифрод системы (необходимость передачи параметра определяется индивидуально при согласовании подключения)
Ответ

  • successBooleanrequired

    Индикатор успешности
Если success == true

  • result.txTransactionrequired

    Идентификатор транзакции процессинга

  • result.src_paymentPaymentoptional

    Сумма и валюта, которые необходимо принять от пользователя

  • result.rateFloatoptional

    Курс покупки.
    При src_payment == "100 RUB" и payment == "1 EUR", rate == 100

  • result.extraJSONoptional

    Дополнительные параметры, которые нужно будет прокинуть в resumePayment
Если success == false

  • result.codeIntrequired

    Код ошибки

  • result.descriptionStringrequired

    Описание ошибки
post
/api/isPaymentPossible
{
  "client": {
    "id": "test_client",
    "showcase": "showcases"
  },
  "product": "test_client_product",
  "payment": {
    "amount": 100,
    "currency": 643,
    "exponent": 2
  },
  "src_payment": {
    "amount": 110,
    "currency": 643,
    "exponent": 2
  },
  "rate": 110,
  "order": {
    "transaction": {
      "id": "1122334455",
      "start_t": 1508336966892,
      "finish_t": 1508336969354
    },
    "cls": "transaction",
    "extra": {
      "from": "mobile_app",
      "some_key": "some_value"
    }
  },
  "tx": {
    "id": "59e765510cf26db591dbfb43",
    "start_t": 1508336977892
  },
  "src_cls": "tele2_ru",
  "src": {
    "phone_number": "79529612574",
    "operator": "tele2_ru",
    "cls": "mc"
  },
  "dst": {
    "id": "login",
    "extra": {
      "premium": true,
      "game_server": "Europe"
    }
  }
}
response
{
  "success": true,
  "result": {
    "tx": {
      "id": "11223344556677",
      "start_t": 1537134068907
    },
    "src_payment": {
      "amount": 110,
      "currency": 643,
      "exponent": 2
    },
    "rate": 110,
    "extra": {
      "key": "important info"
    }
  }
}
response
{
  "success": false,
  "result": {
    "code": 320,
    "description": "Insufficient funds"
  }
}

resumePayment

Используется только после isPaymentPossible для продолжения платежа. Отправляется полноценный запрос со всей информацией о транзакции. Т.е. поля, которые уже были отправлены в isPaymentPossible дублируются (т.е. их содержание идентично тому, что было в isPaymentPossible).

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

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

Запрос

  • clientClientrequired

    Идентификатор пользователя API

  • productStringrequired

    Наименование продукта (проекта)

  • paymentPaymentrequired

    Информация о сумме платежа и валюте

  • src_paymentPaymentrequired

    Сумма и валюта, принятые от пользователя

  • rateFloatoptional

    Курс покупки.
    При src_payment == "100 RUB" и payment == "1 EUR", rate == 100

  • srcPayerrequired

    Информация об аккаунте плательщика в платежной системе. Передается, если известен на этом этапе

  • dstAccountrequired if (order.cls == "item_list" || order.cls == "transfer")

    Информация об аккаунте в проекте

  • orderOrderrequired

    Информация о назначении платежа

  • txTransactionrequired

    Идентификатор транзакции в системе Теко

  • partner_txTransactionrequired

    Идентификатор транзакции в системе мерчанта (из ответа на isPaymentPossible)

  • security_extraJSONoptional

    Предназначено для антифрод системы (необходимость передачи параметра определяется индивидуально при согласовании подключения)

  • extraJSONoptional

    Если было в ответе на isPaymentPossible
Ответ

  • successBooleanrequired

    Индикатор успешности
Если success == true

  • result.txTransactionrequired

    Идентификатор транзакции в системе мерчанта
Если success == false

  • result.codeIntrequired

    Код ошибки

  • result.descriptionStringrequired

    Описание ошибки
post
/api/resumePayment
{
  "client": {
    "id": "test_client",
    "showcase": "showcases"
  },
  "product": "test_client_product",
  "payment": {
    "amount": 100,
    "currency": 643,
    "exponent": 2
  },
  "src_payment": {
    "amount": 110,
    "currency": 643,
    "exponent": 2
  },
  "rate": 110,
  "src": {
    "phone_number": "79771234567",
    "operator": "tele2_ru",
    "cls": "mc"
  },
  "dst": {
    "id": "login",
    "extra": {
      "premium": true,
      "game_server": "Europe"
    }
  },
  "order": {
    "transaction": {
      "id": "qwerty",
      "start_t": 1508336966892,
      "finish_t": 1508336969354
    },
    "cls": "transaction",
    "extra": {
      "from": "mobile_app",
      "some_key": "some_value"
    }
  },
  "tx": {
    "id": "59e765510cf26db591dbfb43",
    "start_t": 1508336977892
  },
  "partner_tx": {
    "id": "11223344556677",
    "start_t": 1537134068907
  },
  "extra": {
    "key": "important info"
  }
}
response
{
  "success": true,
  "result": {
    "tx": {
      "id": "11223344556677",
      "start_t": 1537134068907,
      "finish_t": 1537134069341
    }
  }
}
response
{
  "success": false,
  "result": {
    "code": 305,
    "description": "Parsing error"
  }
}

cancelPayment

Отмена платежа, для которого ранее производилась проверка с помощью метода isPaymentPossible.

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

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

Запрос

  • clientClientrequired

    Идентификатор пользователя API

  • productStringrequired

    Наименование продукта (проекта)

  • paymentPaymentrequired

    Информация о сумме платежа и валюте

  • dstAccountrequired if (order.cls == "item_list" || order.cls == "transfer")

    Информация об аккаунте в проекте

  • orderOrderrequired

    Информация о назначении платежа

  • txTransactionrequired

    Идентификатор транзакции в системе Теко

  • codeIntrequired

    Код ошибки

  • descriptionStringrequired

    Описание ошибки

  • partner_txTransactionrequired

    Идентификатор транзакции в системе мерчанта (из ответа на isPaymentPossible)

  • security_extraJSONoptional

    Предназначено для антифрод системы (необходимость передачи параметра определяется индивидуально при согласовании подключения)

  • extraJSONoptional

    Если было в ответе на isPaymentPossible
Ответ

  • successBooleanrequired

    Индикатор успешности
Если success == true

  • result.txTransactionrequired

    Идентификатор транзакции в системе мерчанта
Если success == false

  • result.codeIntrequired

    Код ошибки

  • result.descriptionStringrequired

    Описание ошибки
post
/api/cancelPayment
{
  "client": {
    "id": "test_client",
    "showcase": "showcases"
  },
  "product": "test_client_product",
  "payment": {
    "amount": 100,
    "currency": 643,
    "exponent": 2
  },
  "dst": {
    "id": "login",
    "extra": {
      "premium": true,
      "game_server": "Europe"
    }
  },
  "order": {
    "transaction": {
      "id": "qwerty",
      "start_t": 1508336966892,
      "finish_t": 1508336969354
    },
    "cls": "transaction",
    "extra": {
      "from": "mobile_app",
      "some_key": "some_value"
    }
  },
  "tx": {
    "id": "59e765510cf26db591dbfb43",
    "start_t": 1508336977892
  },
  "code": 42,
  "description": "Unknown error",
  "partner_tx": {
    "id": "11223344556677",
    "start_t": 1537134068907
  },
  "extra": {
    "key": "important info"
  }
}
response
{
  "success": true,
  "result": {
    "tx": {
      "id": "11223344556677",
      "start_t": 1537134068907,
      "finish_t": 1537134069341
    }
  }
}
response
{
  "success": false,
  "result": {
    "code": 230,
    "description": "Payment was cancelled earlier"
  }
}

rollbackPayment

Возврат уже выполненного платежа.

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

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

Запрос

  • clientClientrequired

    Идентификатор пользователя API

  • paymentPaymentoptional

    Информация о сумме платежа и валюте

  • txTransactionrequired

    Идентификатор транзакции в системе Теко

  • partner_txTransactionrequired

    Идентификатор транзакции в системе мерчанта (из ответа на isPaymentPossible)

  • commentStringoptional

    Комментарий к возврату

  • security_extraJSONoptional

    Предназначено для антифрод системы (необходимость передачи параметра определяется индивидуально при согласовании подключения)

  • extraJSONoptional

    Если было в ответе на isPaymentPossible
Ответ

  • successBooleanrequired

    Индикатор успешности
Если success == true

  • result.txTransactionrequired

    Идентификатор транзакции в системе мерчанта
Если success == false

  • result.codeIntrequired

    Код ошибки

  • result.descriptionStringrequired

    Описание ошибки
post
/api/rollbackPayment
{
  "client": {
    "id": "test_client",
    "showcase": "showcases"
  },
  "payment": {
    "amount": 100,
    "currency": 643,
    "exponent": 2
  },
  "tx": {
    "id": "59e765510cf26db591dbfb43",
    "start_t": 1508336977892
  },
  "partner_tx": {
    "id": "11223344556677",
    "start_t": 1537134068907
  },
  "comment": "rollback reason",
  "extra": {
    "key": "important info"
  }
}
response
{
  "success": true,
  "result": {
    "tx": {
      "id": "11223344556677",
      "start_t": 1537134068907,
      "finish_t": 1537134069341
    }
  }
}
response
{
  "success": false,
  "result": {
    "code": 316,
    "description": "Rollback failed"
  }
}

Описание формата реестра

Общее
  • Базовая форма реестра представляется собой файл CSV, разделитель ;
  • Период отправки реестра оговаривается с партнером при запуске
  • Набор полей в реестре может изменяться в зависимости от требований партнера
  • Суммы в реестре передаются в формате 100.12 (100 рублей 12 копеек)
  • Время передается в формате {dd/MM/yy HH:mm:ss}
Описание полей

  • Transaction id

    Идентификатор операции на стороне процессинга

  • Partner transaction id

    Идентификатор операции со стороны партнера

  • Good ID

    Идентификатор товара

  • Start time

    Время старта операции

  • Finish time

    Время завершения операции (дата учета операции)

  • Payment method

    Метод оплаты

  • Payer id

    Идентификатор плательщика в методе оплаты

  • Currency

    Валюта

  • Amount

    Базовая сумма платежа (база расчетов)

  • Commission

    Комиссия с физического лица

  • Payout

    Сумма выплаты
Registry
Transaction id;Partner transaction id;Good ID;Start time;Finish time;Payment method;Payer id;Currency;Amount;Commission;Payout
processing id;partner id;Good1;26/12/16 06:29;26/12/16 06:31;mts_ru;phone number;643;100.0;10.0;97.0 processing id;partner id;Good2;26/12/16 07:55;26/12/16 10:18;megafon_ru;phone number;643;100.0;15.0;97.0 processing id;partner id;Good2;26/12/16 07:40;26/12/16 10:42;plastic_card;unknown;643;100.0;0.0;97.0 processing id;partner id;Good2;26/12/16 15:48;26/12/16 15:53;tele2_ru;phone number;643;100.0;14.0;97.0 processing id;partner id;Good1;26/12/16 15:48;26/12/16 15:53;beeline_ru;phone number;643;100.0;20.0;97.0

Рекуррентные списания

Endpoints

Обзор протокола

Ключевым понятием в работе протокола рекуррентных списаний является понятие политики списания денежных средств. Под политикой понимается набор атрибутов:

  • Стартовое списание
  • Периодичность списания (в миллисекундах)
  • Количество периодов (от 1 до бесконечности)
  • “Пробный” (trial) период – количество периодов, за которые не будут списываться денежные средства
  • Сумма списания или набор сумм списания:
    1. В случае, если сумма одна, то списывается каждый период одна и та же сумма
    2. В случае если сумм несколько, то система списывает денежные средства циклично, в порядке следования сумм. Пример: если периодов – 10, а сумм указано 3 (1 руб, 2 руб и 3 руб), то за полный цикл пройдет 4 платежа на 1 рубль, 3 платежа на 2 рубля и 3 платежа на 3 рубля.
Статусы подписки:

“Жизненный цикл” подписки состоит из нескольких статусов:

  • created - подписка создана, находится в статусе ожидания инициации стартового списания.
  • trial - находится в пробном статусе. Следущее списание не будет произведено.
  • active - подписка активна и оплачена. Списания идут в соответствии с назначенной логикой.
  • freezed - последняя попытка списаний не прошла по какой-то причине: недостаточно средств, не получено подтверждение.
  • to_be_canceled - подписка, услуги которой продолжают действовать, но по истечении периода, подписка примет статус canceled.
  • canceled – подписка закончена или отменена

Безопасность

  • Общение происходит только по HTTPS
  • Каждый запрос к API должен содержать HTTP заголовки login и signature (login и secret для генерации подписи выдаются в процессе интеграции)
  • Для вычисления подписи signature используется алгоритм HMAC-SHA1
  • В случае POST запросов подписывается все тело запроса, в случае GET-запросов - строка с параметрами.

Методы API

Все ответы приходят в обертке { success: true/false, result: {...} }

subscribe

Запрос на подписку

Запрос

  • numberStringrequired

    Номер телефона клиента

  • policyStringrequired

    Наименование зарегистрированной политики списаний средств

  • tagStringoptional

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

  • prepaidBooleanrequired

    Была ли подписка активирована с помощью предоплаты. В случае значения true, первоначальный платеж взиматься не будет и подписка будет автоматически переведена в статус active

  • extraJSONoptional

Ответ

  • idStringrequired

    Идентификатор подписки

  • tNumberrequired

    Время регистрации в системе

unsubscribe

Отказ от подписки

Запрос

  • idStringrequired

    Идентификатор подписки

subscriptionState

Получение информации о статусе подписки

Запрос

  • idStringrequired

    Идентификатор подписки
Ответ

  • idStringrequired

    Идентификатор подписки

  • tNumberrequired

    Время создания подписки

  • statusStringrequired

    Текущий статус подписки

  • next_statusStringrequired

    Планируемый следующий статус подписки

  • end_of_current_statusNumberrequired

    Время окончания текущего статуса

  • last_charge_tNumberrequired

    Планируемое время следующего списания

  • next_charge_tNumberrequired

    Планируемое время следующего списания

  • policyStringrequired

    Идентификатор политики

subscriptionInfo

Получение полной информации по подписке

Запрос

  • idStringrequired

    Идентификатор подписки
Ответ

  • policyPolicyrequired

    Описание политики списаний этой подписки

  • contractContractrequired

    Описание найденной подписки

subscriptionsByTag

Получение списка подписок по тегу

Запрос

  • tagStringrequired

    Тэг
Ответ

  • subscription_idsList[String]required

    Список идентификаторов найденых подписок

subscriptionsByPhone

Получение списка подписок по номеру телефона

Запрос

  • numberStringrequired

    Номер телефона клиента
Ответ

  • subscription_idsList[String]required

    Список идентификаторов найденых подписок

partnerSubscriptions

Получение списка партнерских подписок

Ответ

  • subscription_idsList[String]required

    Список идентификаторов найденых подписок

Paycafe

Endpoints

Обзор протокола

  • Боевое взаимодействие происходит только по протоколу HTTPS.
  • Боевые параметры и ключи могут быть получены у менеджера по интеграции.
  • Платежная форма может быть интегрирована несколькими способами: перенаправление на форму, встраивание в код веб-страницы, использование JavaScript виджета на веб-странице.
  • Метод для перенаправления на платежную форму, сгенерированную с переданными параметрами:
    GET https://paycafe.teko.io:3007/api/init-session
  • JavaScript Paycafe виджет доступен по следующему адресу:
    https://paycafe.teko.io/paycafeWidget.js

initSession

Данный метод может быть использован в качестве src атрибута в <iframe> элементе веб-страницы или в качестве initSessionUrl параметра в paycafeWidget.js. В случае успеха происходит перенаправление на платежную форму, иначе – на страницу с ошибкой. Следующие параметры запроса должны быть переданы в URL-encoded query string:

Запрос

  • initiatorClientrequired

    Информация о магазине, использующем форму

  • paymentPaymentrequired

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

  • localeEnumrequired

    Язык формы. Возможные значения:
    ru – русский
    en – английский
    tj - таджикский

  • productProductrequired

    Информация о выбранном товаре

  • signatureStringrequired

    Base64-encoded HMAC-SHA1 подпись запроса

  • orderOrderrequired

    Информация о назначении платежа

  • dstAccountoptional

    Информация об аккаунте в проекте

  • paymentMethodsArray[Enum]optional

    Список доступных методов оплаты.
    Значения: "bank- card", "mobile-pay", и тд.

  • themeThemeoptional

    Параметры цветовой схемы

  • selectAmountAmountOptionsoptional

    Настройки выбора суммы платежа

Формирование подписи

  • Следующие параметры должны быть использованы при формировании подписи: locale, initiator, payment, order, product, dst.
  • Сложные параметры с вложенными объектами должны быть представлены в виде JSON. Пример: initiator={"id":"test","showcase":"main_showcase"}
  • Отсортируйте все параметры в алфавитном порядке и сформируйте строку следующего формата: "KEY1|VALUE1|KEY2|VALUE2"
  • Подпись запроса формируется с помощью алгоритма HMAC-SHA1 от строки из пункта выше и секретного ключа. Строка с подписью должна быть Base64-encoded.

Протокол кассового ПО

Endpoints

isPaymentPossible

Проверка возможности проведения платежа.
Запрос совпадает с initPayment протокола инициатора, за исключением:

Запрос

  • clientClientrequired

    Идентификатор пользователя API

  • productString

    Наименование продукта (проекта)

  • paymentPayment

    Информация о сумме платежа и валюте

  • src_paymentPayment

    Сумма и валюта принятые от пользователя

  • rateFloat

    Курс покупки. При src_payment = 100 RUB и payment = 1 EUR, rate = 100

  • srcPayerrequired

    Информация об аккаунте плательщика в платежной системе

  • dstAccountrequired if (order.cls == "item_list" || order.cls == "transfer")

    Информация об аккаунте в проекте

  • orderOrderrequired

    Информация о назначении платежа

  • txTransactionrequired

    Созданная транзакция, для которой производится проверка

  • security_extraJSONoptional

    Предназначено для антифрод системы
Ответ

  • successBooleanrequired

    Индикатор успешности

  • result.txTransaction

    Идентификатор транзакции процессинга
Если success == true

  • result.merchant_txTransaction

    Транзакция у мерчанта (системы денежных переводов)

  • result.rateFloat

    Курс покупки payment. При src_payment = 100 RUB и payment = 1 EUR, rate = 100

  • result.dstAccount

    Может дополнится информацией по отношению к запросу
Если success == false

  • result.codeInt

    Код ошибки

  • result.descriptionString

    Описание ошибки
post
/api/isPaymentPossible
response
{
  "success": true,
  "result": {
    "tx": {
      "id": "1661803727",
      "start_t": 1437134068907
    }
  }
}

resumePayment

Используется только после isPaymentPossible для продолжения платежа. Отправляется полноценный запрос со всей информацией о транзакции. Те поля, которые уже были отправлены в isPaymentPossible дублируются (т.е. их содержание идентично тому, что было в isPaymentPossible)

Запрос

  • clientClient

    Идентификатор пользователя API

  • productString

    Наименование продукта (проекта)

  • paymentPayment

    Сумма и валюта платежа

  • src_paymentPaymentrequired

    Сумма и валюта принятые от пользователя

  • dstAccountrequired if (order.cls == "item_list" || order.cls == "transfer")

    Информация об аккаунте в проекте

  • orderOrder

    Информация о назначении платежа

  • txTransaction

    Созданная транзакция, для которой производится проверка

  • partner_txTransaction

    Транзакция из ответа на isPaymentPossible

  • rateFloat

    Курс покупки. При src_payment = 100 RUB и payment = 1 EUR, rate = 100

  • security_extraJSON

    Предназначено для антифрод системы
Ответ

  • successBooleanrequired

    Индикатор успешности

  • result.txTransaction

    Транзакция, созданная в результате проверки
Если success == true

  • result.merchant_txTransaction

    Транзакция у мерчанта (системы денежных переводов)

  • result.src_paymentPayment

    Cумма и валюта, которые необходимо принять от пользователя

  • result.rateFloat

    Курс покупки payment. При src_payment = 100 RUB и payment = 1 EUR, rate = 100

  • result.dstAccount

    Может дополнится информацией по отношению к запросу
Если success == false

  • result.codeInt

    Код ошибки

  • result.descriptionString

    Описание ошибки
post
/api/resumePayment
response
{
  "success": true,
  "result": {
    "tx": {
      "id": "1661803727",
      "start_t": 1437134068907,
      "finish_t": 1437134086421
    }
  }
}

cancelPayment

Отмена платежа, для которого ранее производилась проверка

Запрос

  • clientClient

    Идентификатор пользователя API

  • productString

    Наименование продукта (проекта)

  • paymentPayment

    Сумма и валюта платежа

  • dstAccountrequired if (order.cls == "item_list" || order.cls == "transfer")

    Информация об аккаунте в проекте

  • orderOrder

    Информация о назначении платежа

  • txTransaction

    Созданная транзакция, для которой производится проверка

  • codeIntrequired

    Код ошибки

  • descriptionString

    Описание ошибки

  • extraJSON

    Если было в ответе на isPaymentPossible

  • partner_txTransaction

    Транзакция из ответа на isPaymentPossible

  • security_extraJSON

    Предназначено для антифрод системы
Ответ

  • successBoolean

    Индикатор успешности
Если success == true

  • result.txTransaction

    Идентификатор транзакции процессинга
Если success == false

  • result.codeInt

    Код ошибки

  • result.descriptionString

    Описание ошибки
post
/api/cancelPayment
response
{
  "success": true,
  "result": {
    "tx": {
      "id": "1438730878",
      "start_t": 1437133818318,
      "finish_t": 1437141086421
    }
  }
}

calcCommission

Расчет комиссии для платежа без заведения полей

Запрос

  • clientClient

    Идентификатор пользователя API

  • productString

    Наименование продукта (проекта)

  • paymentPayment

    Сумма и валюта платежа

  • src_clsString

    Класс плательщика

  • extraJSON

    Если было в ответе на isPaymentPossible
Ответ

  • successBoolean

    Индикатор успешности
Если success == true

  • result.src_paymentPayment

    Сумма из запроса

  • result.dst_paymentPayment

    Сумма с комиссией

  • result.rateFloat

    Курс покупки
Если success == false

  • result.codeInt

    Код ошибки

  • result.descriptionString

    Описание ошибки
post
/api/calcCommission
response
{
  "success": true,
  "result": {
    "tx": {
      "id": "1438730878",
      "start_t": 1437133818318,
      "finish_t": 1437141086421
    }
  }
}

getCatalog

Запрос

  • clientClient

    Идентификатор пользователя API

  • only_headersBoolean

    Возвращать ли предметы с полями или только заголовки

  • item_idString

    Если указан - в ответе будет информация только по конкретному товару
Ответ

  • successBooleanrequired

    Индикатор успешности
Если success == true

  • result.src_paymentList[CatalogItem]

    Список запрошенных элементов каталога
post
/api/getCatalog
response
{
  "success": true,
  "result": {
    "tx": {
      "id": "1438730878",
      "start_t": 1437133818318,
      "finish_t": 1437141086421
    }
  }
}