API
Структура ответов системы
В ответе на каждый содержится поле success
, error_code
, message
.
При успешном запросе success
равен true
.
В других случаях error
содержит error_code
код ошибки. В ответе дополнительно содержатся поля message.
Инициация приема
[POST] /invoice/create
Запрос используется для формирования запроса на оплату. При успешном исполнении запроса, ответ будет содержать ссылку redirectUrl
, на которую нужно переадресовать пользователя.
Headers:
Название | Тип | Описание | Обязательность |
---|---|---|---|
Accept | String | Application/json | Да |
Запрос:
Название | Тип | Описание | Обязательность |
---|---|---|---|
reference_id | String | Номер заказа на стороне мерчанта | Да |
request_url | String | Абсолютная ссылка на сайт мерчанта для перенаправления пользователя. | Да |
back_url | String | Абсолютная ссылка на сайт мерчанта для отправки статуса платежа. Детальное описание запроса ниже. | Да |
description | String | Описание платежа | Да |
amount | Integer | Сумма заказа | Да |
merchant_id | Integer | ID мерчанта | Да |
user_id | Integer | ID пользователя | Нет |
secret_key | String | Поле secret_key необходимо формировать конкатенацией параметров: reference_id + секретный ключ (Ваш ID заказа и секретный ключ в вашем личном кабинете). Полученный результат необходимо обернуть в bcrypt, где модификатор входа хэш-функции (соль/round) равен 10. | Да |
is_test | Boolean | Тестовый платеж | Нет |
user_email | String | email пользователя | Нет |
tr_type | Integer | Тип транзакции (при двухфазовой оплате нужно передать 1) | Нет |
Ответ:
Название | Тип | Описание | Обязательность |
---|---|---|---|
success | Boolean | Результат запроса | Да |
redirect_url | String | Абсолютная ссылка на форму оплаты | Да |
transaction_id | Integer | Номер транзакции | Да |
message | String | Ответное сообщение | Да |
error_code | Integer | Код ошибки | Да |
Пример:
[POST] /invoice/create HTTP/1.1
Host: api.tarlanpayments.kz
Accept: application/json
{
"merchant_id": 4,
"amount": 100,
"description": "Test",
"back_url": "https://example.com/callback",
"request_url": "https://example.com",
"reference_id": 1,
"secret_key": "asd12"
}
Пример успешного ответа:
{
"success": true,
"data": {
"redirect_url": "https://api.tarlanpayments.kz?payment_id=3&payment_hash=7cebd626b74a2b729d0be099d76fda",
"transaction_id": 3,
"referenceId": "1"
},
"message": "",
"error_code": 0
}
Пример запроса при ошибке
{
"success": false,
"error_code": 102,
"message": "Unauthorized",
"data": []
}
Списание платежа
[POST] /payment/withdraw/{reference_id}
Списание платежа (используется при двухфазовой оплате)
Ответ:
Название | Тип | Описание | Обязательность |
---|---|---|---|
success | Boolean | Результат запроса | Да |
message | String | Сообщение | Да |
error_code | Integer | Код ошибки | Да |
data | Array | Данные ответа | Да |
Оплата по API
[POST] /invoice/api-payment
Запрос используется для формирования оплат с банковской карты клиента.
Запрос:
Название | Тип | Описание | Обязательность |
---|---|---|---|
reference_id | String | Номер заказа на стороне мерчанта | Да |
merchant_id | Integer | ID мерчанта | Да |
secret_key | String | Поле secret_key необходимо формировать конкатенацией параметров: reference_id + amount + pan + cvc + секретный ключ (Ваш ID заказа и секретный ключ в вашем личном кабинете). Полученный результат необходимо обернуть в bcrypt, где модификатор входа хэш-функции (соль/round) равен 10. | Да |
amount | Integer | Сумма заказа | Да |
description | String | Описание платежа | Да |
is_test | Boolean | Тестовый платеж | Нет |
card_holder | String | Имя держателя карты | Нет |
pan | String | Номер карты | Да |
exp_month | String | Срок карты, месяц | Да |
exp_year | String | Срок карты, год | Да |
cvc | String | Номер на обратной стороне карты | Да |
user_email | String | Email пользователя | Нет |
user_phone | String | Номер телефона пользователя | Нет |
back_url | String | Абсолютная ссылка на сайт мерчанта для отправки статуса платежа | Нет |
Ответ:
Возможны два варианта ответа в зависимости от настроек 3ds на карте и терминале и соответственно должно быть 2 варианта реагирования на них.
1) Если нет проверки 3ds securecode. На терминале Мерчанта отключена проверка 3ds.
Название | Тип | Описание | Обязательность |
---|---|---|---|
success | Boolean | Результат запроса | Да |
message | String | Сообщение | Да |
error_code | Integer | Код ошибки | Да |
2) Эмитент запрашивает проверку по 3ds (на терминале включена проверка 3ds). 3ds 2.0 и 3ds 1.0 отрабатывают в данном случае по одинаковой схеме, представленной ниже.
Название | Тип | Описание | Обязательность |
---|---|---|---|
success | Boolean | Результат запроса | Да |
acsUrl | String | Url на который необходимо перенаправить пользователя для проверки 3ds securecode | Да |
md | String | Токен 1 3ds проверки | Да |
pares | String | Токен 2 3ds проверки | Да |
termUrl | String | Url в систему Tarlan для завершения платежа | Да |
На стороне Мерчанта необходимо перенаправить пользователя на acsUrl
с параметрами из таблицы.
На форма ниже должно запускаться событие submit
Пример:
<form action="acsUrl" method="POST">
<input type=hidden name=PaReq value="pares">
<input type=hidden name=TermUrl value="termUrl">
<input type=hidden name=MD value="md">
</form>
Отмена платежа
[POST] /payment/cancel
Отмена платежа (используется при двухфазовой оплате)
Запрос:
Название | Тип | Описание | Обязательность |
---|---|---|---|
reference_id | String | Номер заказа на стороне мерчанта | Да |
merchant_id | Integer | ID мерчанта | Да |
secret_key | String | Поле secret_key необходимо формировать конкатенацией параметров: reference_id + секретный ключ (Ваш ID заказа и секретный ключ в вашем личном кабинете). Полученный результат необходимо обернуть в bcrypt, где модификатор входа хэш-функции (соль/round) равен 10. | Да |
Ответ:
Название | Тип | Описание | Обязательность |
---|---|---|---|
success | Boolean | Результат запроса | Да |
message | String | Сообщение | Да |
error_code | Integer | Код ошибки | Да |
data | Array | Данные ответа | Да |
Возврат платежа
[POST] /api/refund
Headers:
Название | Тип | Описание | Обязательность |
---|---|---|---|
Accept | String | Application/json | Да |
Запрос:
Название | Тип | Описание | Обязательность |
---|---|---|---|
reference_id | String | Номер заказа на стороне мерчанта | Да |
merchant_id | Integer | ID мерчанта | Да |
secret_key | String | Поле secret_key необходимо формировать конкатенацией параметров: reference_id + секретный ключ (Ваш ID заказа и секретный ключ в вашем личном кабинете). Полученный результат необходимо обернуть в bcrypt, где модификатор входа хэш-функции (соль/round) равен 10. | Да |
refund_amount | Float | Сумма возврата | Да |
reason | String | Причина обращения | Нет |
Ответ:
Название | Тип | Описание | Обязательность |
---|---|---|---|
success | Boolean | Результат запроса | Да |
message | String | Сообщение | Да |
error_code | Integer | Код ошибки | Да |
data | Array | Данные ответа | Нет |
Пример:
[POST] /api/refund/
HTTP/1.1
Host: api.tarlanpayments.kz
Accept: application/json
{
"reference_id": 123456,
"merchant_id": 4,
"secret_key": "$2a$10$Yu2Ev14ut8XZyxs/laiv0e2cMxIO3yney1gl5CK/DUJ/4dUtfcfDC",
"refund_amount": 100,
"reason": "test"
}
Пример успешного ответа:
{
"success": true,
"data": [],
"message": "Частичный возврат успешен",
"error_code": 0
}
Пример запроса при ошибке
{
"success": false,
"error_code": 103,
"message":
"Not found",
"data": []
}
Обратный запрос
На указанный Callback Url
будет отправлен ответный POST с JSON телом.
Название | Тип | Описание | Обязательность |
---|---|---|---|
status | Integer | Результат транзакции: 0 - только создано 1 - успешно 2 - в процессе 3дс проверки 3 - Платеж авторизован 4 - Платеж отменен 5 - Возврат Платежа 6 - Ошибка при списании с карты | Да |
transaction_id | Integer | Номер транзакции | Да |
secret_key | String | Поле secret_key необходимо формировать конкатенацией параметров: reference_id + секретный ключ (Ваш ID заказа и секретный ключ в вашем личном кабинете). Полученный результат необходимо обернуть в bcrypt, где модификатор входа хэш-функции (соль/round) равен 10. | Да |
reference_id | String | Номер заказа на стороне мерчанта | Да |
masked_pan | String | Маска карты | Да |
description | String | Описание платежа | Да |
bank_id | Integer | По bank_id вы можете узнать банк 1 - Народный Банк Казахстана 2 - ДБ "Альфа-Банк" 3 - Kaspi Bank 4 - AsiaCredit Bank 5 - Altyn Bank 6 - Bank RBK 7 - Capital Bank Kazakhstan 9 - ForteBank 10 - Tengri Bank 11 - ATF Bank 12 - Банк Freedom Finance 28 - АО "КАЗПОЧТА" | Да |
Статус платежа
[POST] /payment/check-status
Проверка статуса транзакции
Запрос:
Название | Тип | Описание | Обязательность |
---|---|---|---|
reference_id | String | Номер заказа на стороне мерчанта | Да |
merchant_id | Integer | ID мерчанта | Да |
secret_key | String | Поле secret_key необходимо формировать конкатенацией параметров: reference_id + секретный ключ (Ваш ID заказа и секретный ключ в вашем личном кабинете). Полученный результат необходимо обернуть в bcrypt, где модификатор входа хэш-функции (соль/round) равен 10. | Да |
Ответ:
Название | Тип | Описание | Обязательность |
---|---|---|---|
success | Boolean | Результат запроса | Да |
message | String | Сообщение | Да |
error_code | Integer | Код ошибки | Да |
data | Array | Данные ответа | Нет |
Пример:
[POST] /payment/check-status
HTTP/1.1
Host: api.tarlanpayments.kz
Accept: application/json
{
"merchant_id": 4,
"reference_id": 1,
"secret_key": "asd12"
}
Пример успешного ответа:
{
"success": true,
"data": {
"reference_id": "123",
"status": 1,
"masked_pan": "5169-49XXXXXX-8835",
"status_desc": "Оплачен"
},
"message": "",
"error_code": 0
}
Пример запроса при ошибке
{
"success": true,
"error_code": 0,
"message": "Заказ не найден",
"data": []
}
Определение банка через БИН номер
[GET] /defineBank/{bin}
Определение банка через номер БИН (Bank Identification Number). БИН'ом является первые шесть цифр номера карты.
Host
api.tarlanpayments.kz
Пример
https://api.tarlanpayments.kz/defineBank/516949
Запрос:
Название | Тип | Описание | Обязательность |
---|---|---|---|
bin | String | БИН номер банка | Да |
Ответ:
Название | Тип | Описание | Обязательность |
---|---|---|---|
success | Boolean | Результат запроса | Да |
message | String | Краткое наименование банка | Да |
Привязка карты
[POST] /api/invoice/card-linking
Используется для формирования запроса на привязку карты. При успешном исполнении запроса, ответ будет содержать ссылку redirectUrl
, на которую нужно переадресовать пользователя..
Запрос:
Название | Тип | Описание | Обязательность |
---|---|---|---|
merchant_id | Integer | ID мерчанта | Да |
user_id | Integer | ID пользователя | Да |
request_url | String | Абсолютная ссылка на сайт мерчанта для перенаправления пользователя. | Да |
is_test | Boolean | Тестовый платеж | Нет |
secret_key | String | Поле secret_key необходимо формировать конкатенацией параметров: merchant_id + user_id + секретный ключ (секретный ключ в вашем личном кабинете). Полученный результат необходимо обернуть в bcrypt, где модификатор входа хэш-функции (соль/round) равен 10. | Да |
Ответ:
Название | Тип | Описание | Обязательность |
---|---|---|---|
success | Boolean | Результат запроса | Да |
redirect_url | String | Абсолютная ссылка на форму оплаты | Да |
transaction_id | Integer | Номер транзакции | Да |
user_id | Integer | ID пользователя | Да |
message | String | Ответное сообщение | Да |
error_code | Integer | Код ошибки | Да |
Получение карт пользователя по приему
[GET] /api/cards/payin
Получение карт пользователя по приему
Запрос:
Название | Тип | Описание | Обязательность |
---|---|---|---|
merchant_id | Integer | ID мерчанта | Да |
user_id | Integer | ID пользователя | Да |
secret_key | String | merchant_id + user_id + secret_key (здесь secret_key - Уникальный код мерчанта ) Полученный результат необходимо обернуть в bcrypt, где модификатор входа хэш-функции (соль/round) равен 10. | Да |
Ответ:
Название | Тип | Описание | Обязательность |
---|---|---|---|
success | Boolean | Результат запроса | Да |
message | String | Сообщение | Да |
error_code | Integer | Код ошибки | Да |
data | Array | Данные карты пользователя | Нет |
Пример:
{
"success": true,
"data": [
{
"id": 821862,
"masked_pan": "4405-64XXXXXX-6150"
},
{
"id": 895245,
"masked_pan": "4400-43XXXXXX-8153"
}
],
"message": "Карты пользователя",
"error_code": 0
}
Получение карт пользователя по выводу
[GET] /api/cards/payout
Запрос:
Название | Тип | Описание | Обязательность |
---|---|---|---|
merchant_id | Integer | ID мерчанта | Да |
user_id | Integer | ID пользователя | Да |
secret_key | String | merchant_id + user_id + secret_key (здесь secret_key - Уникальный код мерчанта ) Полученный результат необходимо обернуть в bcrypt, где модификатор входа хэш-функции (соль/round) равен 10. | Да |
Ответ:
Название | Тип | Описание | Обязательность |
---|---|---|---|
success | Boolean | Результат запроса | Да |
message | String | Сообщение | Да |
error_code | Integer | Код ошибки | Да |
data | Array | Данные карты пользователя | Нет |
Пример:
{
"success": true,
"data": [
{
"id": 821862,
"masked_pan": "4405-64XXXXXX-6150"
},
{
"id": 895245,
"masked_pan": "4400-43XXXXXX-8153"
}
],
"message": "Карты пользователя",
"error_code": 0
}
Рекуррентный прием
[POST] /api/invoice/api-recurrent
Проведение рекуррентного приема без формы
Запрос:
Название | Тип | Описание | Обязательность |
---|---|---|---|
merchant_id | Integer | ID мерчанта | Да |
reference_id | String | Номер заказа на стороне мерчанта | Да |
back_url | String | Абсолютная ссылка на сайт мерчанта для отправки статуса платежа. Детальное описание запроса ниже. | Да |
description | String | Описание платежа | Да |
amount | Integer | Сумма заказа | Да |
is_test | Boolean | Тестовый платеж | Нет |
user_id | Integer | ID пользователя | Да |
card_id | Integer | ID выбранной пользователем карты (данный параметр получаете в api "Вывод карт пользователя") | Да |
secret_key | String | Поле secret_key необходимо формировать конкатенацией параметров: reference_id + секретный ключ (Ваш ID заказа и секретный ключ в вашем личном кабинете). Полученный результат необходимо обернуть в bcrypt, где модификатор входа хэш-функции (соль/round) равен 10. | Да |
user_email | String | email пользователя | Нет |
user_phone | String | Номер телефона пользователя | Нет |
Ответ:
Название | Тип | Описание | Обязательность |
---|---|---|---|
success | Boolean | Результат запроса | Да |
message | String | Ответное сообщение | Да |
error_code | Integer | Код ошибки | Да |
Рекуррентный вывод средств
[POST] /api/invoice/payout/api-recurrent
Рекуррентный вывод средств на карту.
Структура запроса и ответа как у Рекуррентного приема
Удаление карты по приему
[DELETE] /api/cards/payin
Удаление карты по приему
Запрос:
Название | Тип | Описание | Обязательность |
---|---|---|---|
card_id | Integer | ID карты | Да |
merchant_id | Integer | ID мерчанта | Да |
user_id | Integer | ID пользователя | Да |
secret_key | String | merchant_id + user_id + secret_key (здесь secret_key - Уникальный код мерчанта ) Полученный результат необходимо обернуть в bcrypt, где модификатор входа хэш-функции (соль/round) равен 10. | Да |
Ответ:
Название | Тип | Описание | Обязательность |
---|---|---|---|
success | Boolean | Результат запроса | Да |
message | String | Cообщение | Да |
Пример:
{
"success": true,
"message": "Карта удалена"
}
Удаление карты по выводу
[DELETE] /api/cards/payout
Удаление карты по выводу
Запрос:
Название | Тип | Описание | Обязательность |
---|---|---|---|
card_id | Integer | ID карты | Да |
merchant_id | Integer | ID мерчанта | Да |
user_id | Integer | ID пользователя | Да |
secret_key | String | merchant_id + user_id + secret_key (здесь secret_key - Уникальный код мерчанта ) Полученный результат необходимо обернуть в bcrypt, где модификатор входа хэш-функции (соль/round) равен 10. | Да |
Ответ:
Название | Тип | Описание | Обязательность |
---|---|---|---|
success | Boolean | Результат запроса | Да |
message | String | Cообщение | Да |
Пример:
{
"success": true,
"message": "Карта удалена"
}