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": "Карта удалена" 
}

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

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

[POST] /invoice/create​

Headers:​

Запрос:​

Ответ:​

Пример:​

Списание платежа​

[POST] /payment/withdraw/{reference_id}​

Ответ:​

Оплата по API​

[POST] /invoice/api-payment​

Запрос:​

Ответ:​

Пример:​

Отмена платежа​

[POST] /payment/cancel​

Запрос:​

Ответ:​

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

[POST] /api/refund​

Headers:​

Запрос:​

Ответ:​

Пример:​

Обратный запрос​

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

[POST] /payment/check-status​

Запрос:​

Ответ:​

Пример:​

Определение банка через БИН номер​

[GET] /defineBank/{bin}​

Host​

Пример​

Запрос:​

Ответ:​

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

[POST] /api/invoice/card-linking​

Запрос:​

Ответ:​

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

[GET] /api/cards/payin​

Запрос:​

Ответ:​

Пример:​

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

[GET] /api/cards/payout​

Запрос:​

Ответ:​

Пример:​

Рекуррентный прием​

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

Запрос:​

Ответ:​

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

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

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

[DELETE] /api/cards/payin​

Запрос:​

Ответ:​

Пример:​

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

[DELETE] /api/cards/payout​

Запрос:​

Ответ:​

Пример:​

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

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

`[POST] /invoice/create`

Headers:

Запрос:

Ответ:

Пример:

Списание платежа

`[POST] /payment/withdraw/{reference_id}`

Ответ:

Оплата по API

`[POST] /invoice/api-payment`

Запрос:

Ответ:

Пример:

Отмена платежа

`[POST] /payment/cancel`

Запрос:

Ответ:

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

`[POST] /api/refund`

Headers:

Запрос:

Ответ:

Пример:

Обратный запрос

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

`[POST] /payment/check-status`

Запрос:

Ответ:

Пример:

Определение банка через БИН номер

`[GET] /defineBank/{bin}`

Host

Пример

Запрос:

Ответ:

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

`[POST] /api/invoice/card-linking`

Запрос:

Ответ:

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

`[GET] /api/cards/payin`

Запрос:

Ответ:

Пример:

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

`[GET] /api/cards/payout`

Запрос:

Ответ:

Пример:

Рекуррентный прием

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

Запрос:

Ответ:

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

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

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

`[DELETE] /api/cards/payin`

Запрос:

Ответ:

Пример:

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

`[DELETE] /api/cards/payout`

Запрос:

Ответ:

Пример: