Перейти к основному содержимому

API

Структура ответов системы

В ответе на каждый содержится поле success, error_code, message.

При успешном запросе success равен true.

В других случаях error содержит error_code код ошибки. В ответе дополнительно содержатся поля message.

Инициация приема

[POST] /invoice/create

Запрос используется для формирования запроса на оплату. При успешном исполнении запроса, ответ будет содержать ссылку redirectUrl, на которую нужно переадресовать пользователя.

Headers:

НазваниеТипОписаниеОбязательность
AcceptStringApplication/jsonДа

Запрос:

НазваниеТипОписаниеОбязательность
reference_idStringНомер заказа на стороне мерчантаДа
request_urlStringАбсолютная ссылка на сайт мерчанта для перенаправления пользователя.Да
back_urlStringАбсолютная ссылка на сайт мерчанта для отправки статуса платежа. Детальное описание запроса ниже.Да
descriptionStringОписание платежаДа
amountIntegerСумма заказаДа
merchant_idIntegerID мерчантаДа
user_idIntegerID пользователяНет
secret_keyStringПоле secret_key необходимо формировать конкатенацией параметров: reference_id + секретный ключ (Ваш ID заказа и секретный ключ в вашем личном кабинете). Полученный результат необходимо обернуть в bcrypt, где модификатор входа хэш-функции (соль/round) равен 10.Да
is_testBooleanТестовый платежНет
user_emailStringemail пользователяНет
tr_typeIntegerТип транзакции (при двухфазовой оплате нужно передать 1)Нет

Ответ:

НазваниеТипОписаниеОбязательность
successBooleanРезультат запросаДа
redirect_urlStringАбсолютная ссылка на форму оплатыДа
transaction_idIntegerНомер транзакцииДа
messageStringОтветное сообщениеДа
error_codeIntegerКод ошибкиДа

Пример:

[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}

Списание платежа (используется при двухфазовой оплате)

Ответ:

НазваниеТипОписаниеОбязательность
successBooleanРезультат запросаДа
messageStringСообщениеДа
error_codeIntegerКод ошибкиДа
dataArrayДанные ответаДа

Оплата по API

[POST] /invoice/api-payment

Запрос используется для формирования оплат с банковской карты клиента.

Запрос:

НазваниеТипОписаниеОбязательность
reference_idStringНомер заказа на стороне мерчантаДа
merchant_idIntegerID мерчантаДа
secret_keyStringПоле secret_key необходимо формировать конкатенацией параметров: reference_id + amount + pan + cvc + секретный ключ (Ваш ID заказа и секретный ключ в вашем личном кабинете). Полученный результат необходимо обернуть в bcrypt, где модификатор входа хэш-функции (соль/round) равен 10.Да
amountIntegerСумма заказаДа
descriptionStringОписание платежаДа
is_testBooleanТестовый платежНет
card_holderStringИмя держателя картыНет
panStringНомер картыДа
exp_monthStringСрок карты, месяцДа
exp_yearStringСрок карты, годДа
cvcStringНомер на обратной стороне картыДа
user_emailStringEmail пользователяНет
user_phoneStringНомер телефона пользователяНет
back_urlStringАбсолютная ссылка на сайт мерчанта для отправки статуса платежаНет

Ответ:

Возможны два варианта ответа в зависимости от настроек 3ds на карте и терминале и соответственно должно быть 2 варианта реагирования на них.

1) Если нет проверки 3ds securecode. На терминале Мерчанта отключена проверка 3ds.

НазваниеТипОписаниеОбязательность
successBooleanРезультат запросаДа
messageStringСообщениеДа
error_codeIntegerКод ошибкиДа

2) Эмитент запрашивает проверку по 3ds (на терминале включена проверка 3ds). 3ds 2.0 и 3ds 1.0 отрабатывают в данном случае по одинаковой схеме, представленной ниже.

НазваниеТипОписаниеОбязательность
successBooleanРезультат запросаДа
acsUrlStringUrl на который необходимо перенаправить пользователя для проверки 3ds securecodeДа
mdStringТокен 1 3ds проверкиДа
paresStringТокен 2 3ds проверкиДа
termUrlStringUrl в систему 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_idStringНомер заказа на стороне мерчантаДа
merchant_idIntegerID мерчантаДа
secret_keyStringПоле secret_key необходимо формировать конкатенацией параметров: reference_id + секретный ключ (Ваш ID заказа и секретный ключ в вашем личном кабинете). Полученный результат необходимо обернуть в bcrypt, где модификатор входа хэш-функции (соль/round) равен 10.Да

Ответ:

НазваниеТипОписаниеОбязательность
successBooleanРезультат запросаДа
messageStringСообщениеДа
error_codeIntegerКод ошибкиДа
dataArrayДанные ответаДа

Возврат платежа

[POST] /api/refund

Headers:

НазваниеТипОписаниеОбязательность
AcceptStringApplication/jsonДа

Запрос:

НазваниеТипОписаниеОбязательность
reference_idStringНомер заказа на стороне мерчантаДа
merchant_idIntegerID мерчантаДа
secret_keyStringПоле secret_key необходимо формировать конкатенацией параметров: reference_id + секретный ключ (Ваш ID заказа и секретный ключ в вашем личном кабинете). Полученный результат необходимо обернуть в bcrypt, где модификатор входа хэш-функции (соль/round) равен 10.Да
refund_amountFloatСумма возвратаДа
reasonStringПричина обращенияНет

Ответ:

НазваниеТипОписаниеОбязательность
successBooleanРезультат запросаДа
messageStringСообщениеДа
error_codeIntegerКод ошибкиДа
dataArrayДанные ответаНет

Пример:

[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 телом.

НазваниеТипОписаниеОбязательность
statusIntegerРезультат транзакции:
0 - только создано
1 - успешно
2 - в процессе 3дс проверки
3 - Платеж авторизован
4 - Платеж отменен
5 - Возврат Платежа
6 - Ошибка при списании с карты
Да
transaction_idIntegerНомер транзакцииДа
secret_keyStringПоле secret_key необходимо формировать конкатенацией параметров: reference_id + секретный ключ (Ваш ID заказа и секретный ключ в вашем личном кабинете). Полученный результат необходимо обернуть в bcrypt, где модификатор входа хэш-функции (соль/round) равен 10.Да
reference_idStringНомер заказа на стороне мерчантаДа
masked_panStringМаска картыДа
descriptionStringОписание платежаДа
bank_idIntegerПо 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_idStringНомер заказа на стороне мерчантаДа
merchant_idIntegerID мерчантаДа
secret_keyStringПоле secret_key необходимо формировать конкатенацией параметров: reference_id + секретный ключ (Ваш ID заказа и секретный ключ в вашем личном кабинете). Полученный результат необходимо обернуть в bcrypt, где модификатор входа хэш-функции (соль/round) равен 10.Да

Ответ:

НазваниеТипОписаниеОбязательность
successBooleanРезультат запросаДа
messageStringСообщениеДа
error_codeIntegerКод ошибкиДа
dataArrayДанные ответаНет

Пример:

[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

Запрос:

НазваниеТипОписаниеОбязательность
binStringБИН номер банкаДа

Ответ:

НазваниеТипОписаниеОбязательность
successBooleanРезультат запросаДа
messageStringКраткое наименование банкаДа

Привязка карты

[POST] /api/invoice/card-linking

Используется для формирования запроса на привязку карты. При успешном исполнении запроса, ответ будет содержать ссылку redirectUrl, на которую нужно переадресовать пользователя..

Запрос:

НазваниеТипОписаниеОбязательность
merchant_idIntegerID мерчантаДа
user_idIntegerID пользователяДа
request_urlStringАбсолютная ссылка на сайт мерчанта для перенаправления пользователя.Да
is_testBooleanТестовый платежНет
secret_keyStringПоле secret_key необходимо формировать конкатенацией параметров: merchant_id + user_id + секретный ключ (секретный ключ в вашем личном кабинете). Полученный результат необходимо обернуть в bcrypt, где модификатор входа хэш-функции (соль/round) равен 10.Да

Ответ:

НазваниеТипОписаниеОбязательность
successBooleanРезультат запросаДа
redirect_urlStringАбсолютная ссылка на форму оплатыДа
transaction_idIntegerНомер транзакцииДа
user_idIntegerID пользователяДа
messageStringОтветное сообщениеДа
error_codeIntegerКод ошибкиДа

Получение карт пользователя по приему

[GET] /api/cards/payin

Получение карт пользователя по приему

Запрос:

НазваниеТипОписаниеОбязательность
merchant_idIntegerID мерчантаДа
user_idIntegerID пользователяДа
secret_keyStringmerchant_id + user_id + secret_key (здесь secret_key - Уникальный код мерчанта ) Полученный результат необходимо обернуть в bcrypt, где модификатор входа хэш-функции (соль/round) равен 10.Да

Ответ:

НазваниеТипОписаниеОбязательность
successBooleanРезультат запросаДа
messageStringСообщениеДа
error_codeIntegerКод ошибкиДа
dataArrayДанные карты пользователяНет

Пример:

{ 
"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_idIntegerID мерчантаДа
user_idIntegerID пользователяДа
secret_keyStringmerchant_id + user_id + secret_key (здесь secret_key - Уникальный код мерчанта ) Полученный результат необходимо обернуть в bcrypt, где модификатор входа хэш-функции (соль/round) равен 10.Да

Ответ:

НазваниеТипОписаниеОбязательность
successBooleanРезультат запросаДа
messageStringСообщениеДа
error_codeIntegerКод ошибкиДа
dataArrayДанные карты пользователяНет

Пример:

{ 
"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_idIntegerID мерчантаДа
reference_idStringНомер заказа на стороне мерчантаДа
back_urlStringАбсолютная ссылка на сайт мерчанта для отправки статуса платежа. Детальное описание запроса ниже.Да
descriptionStringОписание платежаДа
amountIntegerСумма заказаДа
is_testBooleanТестовый платежНет
user_idIntegerID пользователяДа
card_idIntegerID выбранной пользователем карты (данный параметр получаете в api "Вывод карт пользователя")Да
secret_keyStringПоле secret_key необходимо формировать конкатенацией параметров: reference_id + секретный ключ (Ваш ID заказа и секретный ключ в вашем личном кабинете). Полученный результат необходимо обернуть в bcrypt, где модификатор входа хэш-функции (соль/round) равен 10.Да
user_emailStringemail пользователяНет
user_phoneStringНомер телефона пользователяНет

Ответ:

НазваниеТипОписаниеОбязательность
successBooleanРезультат запросаДа
messageStringОтветное сообщениеДа
error_codeIntegerКод ошибкиДа

Рекуррентный вывод средств

[POST] /api/invoice/payout/api-recurrent

Рекуррентный вывод средств на карту.

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

Удаление карты по приему

[DELETE] /api/cards/payin

Удаление карты по приему

Запрос:

НазваниеТипОписаниеОбязательность
card_idIntegerID картыДа
merchant_idIntegerID мерчантаДа
user_idIntegerID пользователяДа
secret_keyStringmerchant_id + user_id + secret_key (здесь secret_key - Уникальный код мерчанта ) Полученный результат необходимо обернуть в bcrypt, где модификатор входа хэш-функции (соль/round) равен 10.Да

Ответ:

НазваниеТипОписаниеОбязательность
successBooleanРезультат запросаДа
messageStringCообщениеДа

Пример:

{ 
"success": true,
"message": "Карта удалена"
}

Удаление карты по выводу

[DELETE] /api/cards/payout

Удаление карты по выводу

Запрос:

НазваниеТипОписаниеОбязательность
card_idIntegerID картыДа
merchant_idIntegerID мерчантаДа
user_idIntegerID пользователяДа
secret_keyStringmerchant_id + user_id + secret_key (здесь secret_key - Уникальный код мерчанта ) Полученный результат необходимо обернуть в bcrypt, где модификатор входа хэш-функции (соль/round) равен 10.Да

Ответ:

НазваниеТипОписаниеОбязательность
successBooleanРезультат запросаДа
messageStringCообщениеДа

Пример:

{ 
"success": true,
"message": "Карта удалена"
}