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 == "order_id"

  • 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

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

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

Предназначен для инициализации и отслеживания статуса платежа в системе Теко

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: {...} }

Ваша основная задача сформировать валидный JSON с необходимыми параметрами, подписать его и отправить в виде POST-запроса на нужный URL и с необходимыми заголовками (HTTP headers)

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

    По этому полю можно запрашивать список транзакций. Запрещено использование символа |
Ответ

  • 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"
  },
  "dst": {
    "id": "Y6UBATOP9000",
    "extra": {
      "premium": true,
      "game_server": "Europe"
    }
  },
  "order": {
    "cls": "item_list",
    "item_list": [
      {
        "id": 121,
        "name": "Gold",
        "count": 100500
      }
    ]
  },
  "extra": {
    "from": "mobile_app",
    "some_key": "some_value"
  }
}
response
{
  "success": true,
  "result": {
    "tx": {
      "id": "55d8fb900cf23b38021b7c65",
      "start_t": 1440283536655
    }
  }
}

getPaymentStatus

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

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

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

Запрос

  • 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"
    }
  }
}

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

Оповещение приходит, если при инициализации платежа было заполнено поле callback. Для подписи запроса используется тот же ключ, что и при инициализации (initPayment).

Запрос на получение статуса платежа в системе Теко.

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

Запрос

  • clientStringrequired

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

  • txTransactionrequired

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

  • statusStatusrequired

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

  • partner_txTransactionoptional

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

  • successBooleanrequired

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

  • result.codeIntrequired

    Код ошибки

  • result.descriptionStringrequired

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

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

Предназначен для проведения платежа с возможность отмены или возврата средств при уже выполненном платеже

Endpoints

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

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

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

Взаимодействие начинается с метода isPaymentPossible, который приходит Мерчанту (Вам), если после проверки на стороне Мерчанта (Вашей стороне) отправляется успешный ответ (true), то далее Мерчанту (Вам) приходит запрос resumePayment на исполнение платежа.

В случае успешного ответа (true) на resumePayment взаимодействие завершится - платеж успешен.

Если же ответ на resumePayment является НЕуспешным (false), то шлюз (сторона Теко) повторит запрос resumePayment еще 10 раз с паузой в 30сек, если все ответы на него будут НЕуспешными (false) шлюз (сторона Теко) отправит запрос cancelPayment Мерчанту (Вам), в случае успешного ответа (true) взаимодействие завершится, платеж будет прерван, если же ответ от Мерчанта (от Вас) будет НЕуспешным, то шлюз (сторона Теко) повторит запрос cancelPayment еще 10 раз с паузой 30сек.

Метод rollbackPayment отправляется Мерчанту (Вам) при необходимости возврата платежа, при успешном ответе (true) от Мерчанта (Вас) средства будут возвращены изначальным владельцам.

isPaymentPossible

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

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

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

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

Запрос

  • clientClientrequired

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

  • productStringrequired

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

  • paymentPaymentrequired

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

  • src_paymentPaymentoptional

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

  • rateFloatoptional

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

  • src_clsStringrequired

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

  • srcPayeroptional

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

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

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

  • orderOrderrequired

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

  • txTransactionrequired

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

  • 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
  },
  "order": {
    "transaction": {
      "id": "qwerty",
      "start_t": 12345,
      "finish_t": 12345
    },
    "cls": "transaction"
  },
  "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": "1661803727",
      "start_t": 1437134068907
    }
  }
}

resumePayment

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

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

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

Запрос

  • clientClientrequired

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

  • productStringrequired

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

  • paymentPaymentrequired

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

  • src_paymentPaymentrequired

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

  • rateFloatoptional

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

  • srcPayeroptional

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

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

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

  • orderOrderrequired

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

  • txTransactionrequired

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

  • partner_txTransactionrequired

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

  • extraJSONoptional

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

  • security_extraJSONoptional

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

  • 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": 100,
    "currency": 643,
    "exponent": 2
  },
  "src": {
    "phone_number": "79771234567",
    "operator": "tele2_ru",
    "cls": "mc"
  },
  "dst": {
    "id": "login",
    "extra": {
      "premium": true,
      "game_server": "Europe"
    }
  },
  "order": {
    "transaction": {
      "id": "qwerty",
      "start_t": 12345,
      "finish_t": 12345
    },
    "cls": "transaction"
  },
  "tx": {
    "id": "59e732190cf26db591dbfb34",
    "start_t": 1508323865724
  }
}
response
{
  "success": true,
  "result": {
    "tx": {
      "id": "59e732190cf26db591dbfb34",
      "start_t": 1508323865724,
      "finish_t": 1508323865724
    }
  }
}

cancelPayment

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

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

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

Запрос

  • clientClientrequired

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

  • productStringrequired

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

  • paymentPaymentrequired

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

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

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

  • orderOrderrequired

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

  • txTransactionrequired

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

  • codeIntrequired

    Код ошибки

  • descriptionStringrequired

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

  • extraJSONoptional

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

  • partner_txTransactionrequired

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

  • security_extraJSONoptional

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

  • 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": 19999,
    "currency": 643,
    "exponent": 2
  },
  "dst": {
    "id": "login",
    "extra": {
      "premium": true,
      "game_server": "Europe"
    }
  },
  "order": {
    "transaction": {
      "id": "qwerty",
      "start_t": 12345,
      "finish_t": 12345
    },
    "cls": "transaction"
  },
  "tx": {
    "id": "59e765460cf26db591dbfb42",
    "start_t": 1508336966463
  },
  "code": 42,
  "description": "Unknown error",
  "partner_tx": {
    "id": "59e765460cf26db591dbfb42",
    "start_t": 1508336966902
  }
}
response
{
  "success": true,
  "result": {
    "tx": {
      "id": "59e732190cf26db591dbfb34",
      "start_t": 1508336975921,
      "finish_t": 1508336987232
    }
  }
}

rollbackPayment

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

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

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

Запрос

  • clientClientrequired

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

  • paymentPaymentrequired

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

  • txTransactionrequired

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

  • partner_txTransactionrequired

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

  • commentStringrequired

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

  • extraJSONoptional

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

  • security_extraJSONoptional

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

  • successBooleanrequired

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

  • result.codeIntrequired

    Код ошибки

  • result.descriptionStringrequired

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

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

Общее
  • Базовая форма реестра представляется собой файл 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
    }
  }
}