# Общая информация **Платежный шлюз** представляет собой программное решение, которое обеспечивает интеграцию между платежным шлюзом и вашим приложением или веб-сайтом. Данный документ описывает подробности методов, необходимых для взаимодействия с платежным шлюзом. *** ## **Термины и сокращения** **API: Application Programming Interface** — набор готовых методов, предоставляемых приложением (системой) для использования во внешних программных продуктах. **REST: Representational State Transfer** — архитектурный стиль взаимодействия компонентов распределенного приложения в сети. **JSON: JavaScript Object Notation** — текстовый формат обмена данными, основанный на JavaScript RFC 7159. **3DS: 3-D Secure** — протокол защиты карточных данных, используемый для аутентификации держателя банковской карты во время совершения платежной операции через интернет. Tarlan Payments поддерживает как версию 3DS 1.0, так и версию 3DS 2.0 протокола. **ТСП, Мерчант** — Торгово-сервисное предприятие, работающее с системой. **Проект —** дочерняя сущность партнёра (мерчанта). Позволяет мерчанту разграничивать юридические лица, терминалы, а также, отчёты. **Мерчант (партнёр) —** юридическое лицо, которое имеет возможность получать денежные средства за осуществление услуг, продажи товаров и так далее. Также является агрегирующей сущностью проектов. **Секретный ключ** — Символьная строка для авторизации проекта используемая для его идентификации. **Платежный токен** — Символьная строка, созданная по данным карты, для безакцептных платежей. *** ### Этапы имплементации 1. Оставьте заявку на подключение на сайте[ tarlanpayments.kz](https://tarlanpayments.kz/) *После обработки заявки менеджер Службы поддержки обсудит с вами возможные варианты подключения, запросит необходимые документы, запустит процесс интеграции с банками, договор, создание терминала.* 2. Получите доступ к личному кабинету.\ *При подключении к Протоколу приема платежей вы получаете уникальный идентификатор мерчанта и доступ в Личный кабинет. Параметры доступа отправляются на указанный при регистрации e-mail.* 3. Выпустите ключ доступа к API. *Ключ доступа к API используется для взаимодействия с API. Получите ключ API у аккаунт-менеджера.* 4. Протестируйте взаимодействие.\ *При подключении ваш идентификатор находится в тестовом режиме. В этом режиме вы можете проводить операции без списания средств с банковской карты.* Когда интеграция на вашей стороне закончена, мы переводим ваш идентификатор project\_id в производственный режим. ***Внимание!** В производственном режиме выполняются **реальные списания средств с карт.*** ### Обратная связь Вопросы и предложения можно отправлять по адресу: [support@tarlanpayments.kz](mailto:support@onevision.kz) А также, по реквизитам указанным в разделе "Контакты" на официальном [сайте ](https://tarlanpayments.kz) # Процесс одностадийного платежа #### Шаги проведения платежа 1. Клиент Партнера делает запрос на создание платежа в проекте Мерчанта 2. Проект отправляет запрос на создание транзакции 3. Проект получает URL страницы платежа 4. Проект перенаправляет клиента на страницу платежа 5. Клиент вводит данные карты и нажимает "Оплатить" 6. Платежная система получает запрос, если при создании транзакции был указан параметр [confirm\_url](/platezhnyi-shlyuz/webhook-platezhnoi-sistemy/gotovnost-provedeniya-oplaty), платежная система делает запрос в проект Мерчанта 7. Проект отвечает по адресу указанному в параметре [confirm\_url](/platezhnyi-shlyuz/webhook-platezhnoi-sistemy/gotovnost-provedeniya-oplaty). В случае, если проект отвечает http-кодом, отличным от "200", транзакция прерывается 8. Платежная система отправляет запрос в банк 9. Платежная система получает ответ от банка со статусом транзакции 10. Платежная система выводит чек на странице платежа 11. Платежная система отправляет статус транзакции в проект на адрес указанный в параметре [callback\_url](/platezhnyi-shlyuz/webhook-platezhnoi-sistemy/status-oplaty) #### UML-диаграмма проведения платежа # Процесс двухстадийного платежа #### Шаги проведения платежа 1. Клиент Партнера делает запрос на создание платежа в проекте Мерчанта с указанием параметра is\_hold = true 2. Проект отправляет запрос на создание транзакции 3. Проект получает URL страницы платежа 4. Проект перенаправляет клиента на страницу платежа 5. Клиент вводит данные карты и нажимает "Оплатить" 6. Платежная система получает запрос, если при создании транзакции был указан параметр [confirm\_url](/platezhnyi-shlyuz/webhook-platezhnoi-sistemy/gotovnost-provedeniya-oplaty), платежная система делает запрос в проект Мерчанта 7. Проект отвечает по адресу указанному в параметре [confirm\_url](/platezhnyi-shlyuz/webhook-platezhnoi-sistemy/gotovnost-provedeniya-oplaty). В случае, если проект отвечает http-кодом, отличным от "200", транзакция прерывается 8. Платежная система отправляет запрос в банк на блокирование средств 9. Платежная система получает ответ от банка со статусом транзакции 10. Платежная система выводит чек на странице платежа 11. Платежная система отправляет статус транзакции в проект на адрес указанный в параметре [callback\_url](/platezhnyi-shlyuz/webhook-platezhnoi-sistemy/status-oplaty) 12. Проект Мерчанта может [подтвердить](/platezhnyi-shlyuz/vspomogatelnye-metody/podtverzhdenie-spisaniya-sredstv) или [отменить](/platezhnyi-shlyuz/vspomogatelnye-metody/otmena-spisaniya-sredstv) списание средств используя API или ЛК 13. Платежная система отправляет запрос в банк на списание или отмену блокировки средств {% hint style="warning" %} По истечению определенного количества времени будет выполнено автоматическое списание денежных средств, настройка данного периода выполняется в ЛК и может быть от 3 до 13 дней включительно {% endhint %} {% hint style="info" %} Доступно списание или отмена всех заблокированных средств {% endhint %} #### UML-диаграмма проведения платежа # Виды операций **Приём (pay in)** — Операция по оплате товаров/услуг, совершенная через Интернет с использованием банковских карт. При оплате денежные средства перечисляются со счета держателя платежной карты в пользу Партнёра. **Вывод (pay out)** — При выводе денежные средства перечисляются со счета Партнёра на карточный счёт клиента Партнёра **Возврат (refund)** - Возврат денежных средств. Доступен только после успешного приёма денежных средств. *** **Двухстадийный платёж (pay in)** - Операция по оплате товаров/услуг, совершенная через Интернет с использованием банковских карт требующая дополнительного подтверждения. Двухстадийный механизм работы позволяет разделить процесс проверки платежеспособности банковской карты (авторизация) и снятие денег (финансовое подтверждение). На первой стадии двухстадийного платежа происходит блокирование средств на счету держателя карты, а на второй списание. * **Списание** - Операция доступная только при двухстадийном платеже после авторизации денежных средств. Возможно как полное, так и частичное списание заблокированной суммы. * **Отмена** - Операция доступная только при двухстадийном платеже после авторизации денежных средств. Возможно как полное, так и частичное списание заблокированной суммы. *** **Привязка карты (card link)** - Операция при которой происходит фиксированное списание денежных средств с банковской карты (pay in) и дальнейшем возвратом денежных средств на карту (refund). **Безакцептный приём (one click pay in) -** Операция приёма денежных средств с использованием сохранённой карты в платёжной системе без ввода карточных данных и без [3DS аутентификации](/platezhnyi-shlyuz/welcom/3d-secure) **Безакцептный вывод (one click pay out) -** Операция вывода денежных средств с использованием сохранённой карты в платёжной системе без ввода карточных данных. # 3D-Secure **3-D Secure** — протокол, используемый как дополнительный уровень безопасности онлайн-кредитных и дебетовых карт, для двухфакторной аутентификации пользователя. Цель - проверка подлинности держателя и защита от несанкционированного использования карты. Как это работает: владелец карты указывает реквизиты карты, далее открывается сайт эмитента, где держателю предлагается ввести пароль или секретный код. В большинстве случаев, код отправляется в СМС-сообщении. Если код указан правильно, оплата будет проведена. Если нет — отклонена. # PCI DSS **PCI DSS** — стандарт информационной безопасности, принятый в индустрии платежных карт Visa и Mastercard. Соблюдать требования стандарта обязаны все компании, которые принимают карты к оплате. Некоторым компаниям необходимо подтверждать свое соответствие. Соблюдение стандартов безопасности Основным принципом, на который ориентирован данный стандарт, является стремление максимально ограничить доступ к данным, связанным с платежными картами. Считается, что наилучшим решением будет вообще избегать обработки таких данных и, вместо этого, обращаться к сертифицированным провайдерам для приема платежей. Практически это означает, что мы не должны запрашивать и не должны передавать номера карт. В случае, если клиент пытается сообщить номер карты, например, во время звонка с проблемой платежа, наша задача - немедленно прервать эту попытку и объяснить, почему мы не можем принимать такие данные. Если данные поступают по электронной почте или через мессенджеры, мы должны удалить их и предупредить отправителя о рисках передачи данных карты. Под охраняемыми данными мы понимаем: * Полный номер карты * Код CVV2/CVC2 (три цифры, расположенные на обратной стороне карты). * Имена владельцев карты * Срок действия Маскированные номера карты (первые 6 и последние 4 цифры) не требуют такой же строгой защиты в соответствии с требованиями стандарта и могут использоваться в разумных пределах. Tarlan Payments ежегодно проходит данную сертификацию и соответствует всем требованиям PCI DSS
# Типы транзакций
кодописание
inСписание средств с карты пользователя
outВывод денежных средств со счёта проекта на карту пользователя
one_click_pay_inСписание средств по сохранённой карте пользователя
one_click_pay_outВывод средств со счёта проекта на сохранённую карту пользователя
google_payОплата по средствам технологии Google Pay
apple_payОплата по средствам технологии Apple Pay
card_linkПривязка карты пользователя в платёжной системе (используется для безакцептных платежей)
two_stage_pay_inДвустадийное списание средств с карты пользователя
# Структура ответов системы Ответ на каждый запрос содержит в себе поля: `status`, `status_code`, `message`, `result`. При успешной обработке запроса параметр `status` в ответе всегда равен `true`, а `status_code` равен `0`. В других случаях, поле `status_code` отображает причину некорректной обработки запроса. | наименование поля | тип данных | Описание | | :---------------: | :--------: | :--------------------------------------------: | | `status` | `bool` | Поле указывает на успешность обработки запроса | | `status_code` | `integer` | Код ошибки | | `message` | `string` | Текстовое описание кода ошибки | | `result` | `object` | Результат запрашиваемого ресурса | # Коды ошибок
КодТекстовое сопровождениеОписаниеHTTP status
1021request validation errorОшибка валидации полей запроса400
5102undefined transaction typeНеопределённый тип транзакции404
8301unexpected db errorНеопознанная ошибка при обработке ресурса500
5400couldn't receive project dataВозникла ошибка при получении данных по проекту500
5406invalid project secretНекорректное формирование хэша400
8008project doesn't existПроект не найден404
5000transaction already existsТранзакция уже была создана400
5101undefined transaction statusНеизвестный статус транзакции404
5107transaction limit doesn't existНе установлены лимиты для транзакции404
5006transaction amount limit is overПревышен лимит по сумме транзакции400
5003an error occurred while creating transactionВозникла ошибка при создании транзакции500
5202request failedОшибка при отправке запроса в адрес проекта500
1022couldn't parse response bodyПолучен некорректный ответ500
5205unavailable project serverНе доступен сервер мерчанта при проведении запроса на подтверждение транзакции500
3108card doesn't exist Карта не найдена 500
3010inoperable transaction status for this methodСтатус транзакции не позволяет сделать повторный возврат400
**Коды ошибок провайдера** Ошибки описывающие причину отклонения платежа, передаются при [статусе failed](/platezhnyi-shlyuz/statusy-tranzakcii)\ Данные ошибки передаются как доп. параметры в: * [Webhook](/platezhnyi-shlyuz/webhook-platezhnoi-sistemy/status-oplaty) на статус оплаты * В [запросе ](/platezhnyi-shlyuz/vspomogatelnye-metody/proverka-statusa-tranzakcii)на статус транзакции * В [One-click](/platezhnyi-shlyuz/platezhi-bez-formy-oplaty/platezh-po-sokhranennoi-karte-one-click) на прием без платежной страницы
Код ошибкиТекстовое сопровождениеОписание
100undefined errorНеопределенная ошибка
1013DS authentication failedНе удалось провести проверку 3DSecure
102invalid cardНедействительная карта
103exceeds amount limitПревышен лимит суммы
104exceeds transaction frequency limitПревышен предел частоты транзакций
105transaction declined by an issuerТранзакция отклонена банком-эмитентом
106transaction declined by an acquirerТранзакция отклонена банком-эквайером
107unavailable issuerБанк-эмитент недоступен
108unavailable acquirerБанк-эквайер недоступен
109payment is forbidden for the merchantПлатеж запрещен для продавца
110stolen cardКарта украдена
111blocked cardКарта заблокирована
112non existent cardКарты не существует
113lost cardКарта утеряна
114card has expiredСрок действия карты истёк
115incorrect CVV/CVCНекорректный CVV/CVC
116incorrect card numberНекорректный номер карты
117incorrect card expiration dateНекорректный срок действия карты
118insufficient fundsНедостаточно средств
119suspicious clientПодозрительный клиент
120user did not payПользователь не произвел оплату
121invalid threeD secure parametersНекорректно переданные параметры 3DSecure
122Declined. Matches the Anti-Fraud Center list. Please contact [source_organization].Отклонено. Данные совпали со списком Антифрод Центра. Просим обратиться в [source_organization]
# Статусы транзакций | код | наименование | описание | | :---------------: | :----------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | new | Транзакция создана | Статус при создании транзакции | | processed | Транзакция в работе | Пользователь нажал на кнопку "Оплатить". Транзакция прошла все этапы валидации. | | threeds\_waiting | Транзакция ожидает ответа от 3ds сервера | В ожидании проверки [3D-Secure](/platezhnyi-shlyuz/welcom/3d-secure) | | threeds\_received | Транзакция получила ответ от 3ds сервера | Получен ответ от 3DS сервера | | failed | Транзакция прошла неуспешно | Ошибка со стороны банка эквайера при проведении транзакции | | refund | Транзакция возвращена | Был произведён возврат денежных средств на карту пользователя | | canceled | Транзакция отменена | Отмена транзакции при двухстадийной оплате | | retry | Транзакция в статусе повтор | Повторная попытка оплаты. В случае, ошибки ввода со стороны пользователя | | success | Транзакция прошла успешно | Денежные средства сняты с карты пользователя ([Приём](/platezhnyi-shlyuz/vzaimodeistvie-s-formoi-oplaty/iniciaciya-priyoma-denezhnykh-sredstv)). Денежные средства выведены на карту пользователя ([Вывод](/platezhnyi-shlyuz/vzaimodeistvie-s-formoi-oplaty/iniciaciya-vyvoda-denezhnykh-sredstv)). | | holded | Транзакция в в статусе ожидания | В ожидании ответа от банка эквайера | | refund\_waiting | Транзакция в статусе ожидания возврата | Процесс возврата средств был запущен. Транзакция в ожидании возврата. | | authorized | Транзакция авторизована | Средства захолдированы. Используется при двухстадийной оплате. | | error | Произошла ошибка при проведении транзакции | Ошибка при проведении транзакции | # Формирование подписи Запросы для взаимодействия с платежной системой подписываются с использованием алгоритма SHA256. Для формирование подписи необходимо: 1. В случае POST запроса, тело запроса *requestData* сортируется по алфавиту и кодируется в BASE64. 2. В случае GET запроса, Query params преобразуем в JSON.\ ИЗ:\ **\ В:\ *{ "merchant\_id" : 123, "project\_client\_id" : "999", "project\_id" : 124}*\ После преобразования сортируем по алфавиту и кодируем в BASE64. 3. Конкатенируем кодированное тело запроса (*base64EncodedData*) и secret (выдается мерчанту платежной организацией) 4. Используя хеш-функцию SHA256 хешируем полученный результат (*dataToSign*) 5. Добавляем подпись в заголовок запроса Authorization: Bearer sign {% hint style="warning" %} **Все тело запроса участвует в подписи, кроме полей c пустым значением строки ""**\ **Поле additional\_data не участвует в формировании** [**подписи**](/platezhnyi-shlyuz/formirovanie-podpisi) {% endhint %} В формировании подписи участвует все тело запроса с исключениями:\ Поля с пустыми строковыми значениями "" не участвуют в подписи;\ Поле additional\_data не участвует в формировании подписи {% code lineNumbers="true" %} ```bash curl --location 'https://prapi.tarlanpayments.kz/transaction/...' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ff1a38a78ccca1b313ae172307e49112066ec2f5a1dfa2a76110104da3012896' --data-raw '{}' ``` {% endcode %} {% tabs %} {% tab title="PHP" %} {% code lineNumbers="true" %} ```php "9999", "merchant_id" => 1, "project_id" => 1, "additional_data" => ["key" => "This should be excluded"] ]; $secret = "12345"; // Remove the "additional_data" field from the request data unset($requestData["additional_data"]); // Sort the request data by keys in alphabetical order ksort($requestData); // Encode the sorted request data to JSON $sortedJson = json_encode($requestData, JSON_UNESCAPED_UNICODE | JSON_HEX_AMP | JSON_UNESCAPED_SLASHES); // Encode the sorted JSON to base64 $base64EncodedData = base64_encode($sortedJson); // Concatenate the base64-encoded data with the secret $dataToSign = $base64EncodedData . $secret; // Hash the result to SHA-256 $sha256Hash = hash("sha256", $dataToSign); echo $sha256Hash; ``` {% endcode %} {% endtab %} {% tab title="Python3" %} {% code lineNumbers="true" %} ```python import json import base64 import hashlib request_data = { "project_client_id": "9999", "merchant_id": 1, "project_id": 1, "additional_data": {"key":"This should be excluded"} } secret = "12345" # Remove the "additional_data" field from the request data if "additional_data" in request_data: del request_data["additional_data"] # Sort the request data by keys in alphabetical order sorted_data = json.dumps( request_data, sort_keys=True, ensure_ascii=False, separators=(',', ':'), ) # Encode the sorted JSON to base64 base64_encoded_data = base64.b64encode(sorted_data.encode()).decode() # Concatenate the base64-encoded data with the secret data_to_sign = base64_encoded_data + secret # Hash the result to SHA-256 sha256_hash = hashlib.sha256(data_to_sign.encode()).hexdigest() print(sha256_hash) ``` {% endcode %} {% endtab %} {% tab title="Golang" %} 
package main

import (
	"crypto/sha256"
	"encoding/base64"
	"encoding/json"
	"fmt"
)  // Тело берется из создания транзакции 

type Request struct {
	ProjectClientID string `json:"project_client_id"`
	MerchantId      uint64 `json:"merchant_id"`
	ProjectId       uint64 `json:"project_id"`
	AdditionalData  map[string]string `json:"additional_data"`
}

const secret = "12345"

func main() {
	request := Request{
		ProjectClientID: "9999",
		MerchantId:      1,
		ProjectId:       1,
		AdditionalData: map[string]string{
			"key": "This should be excluded",
		},
	}

	notSortedJson, err := json.Marshal(&request)
	if err != nil {
		panic(err)
	}

	var notSorteddMap map[string]interface{}

	
	if err = json.Unmarshal(notSortedJson, &notSorteddMap); err != nil {
		panic(err)
	}

	delete(notSortedMap, "additional_data")
	
	sortedJson, err := json.Marshal(&notSorteddMap)
	if err != nil {
		panic(err)
	}

	signData := base64.StdEncoding.EncodeToString(sortedJson)
	
	sign := sha256.Sum256([]byte(signData + secret))

	fmt.Printf("%x", sign)

}
{% endtab %} {% tab title="Dart" %} ```dart const paymentSecretKey = "123"; String hashedSecretKey({ required Map requestData, }) { // Sort the request data by keys in alphabetical order List> sortedEntries = requestData.entries.toList() ..sort((a, b) => a.key.compareTo(b.key)); Map sortedData = Map.fromEntries(sortedEntries); // Sort the request data by keys in alphabetical order String encodedData = json.encode(sortedData); // Encode the sorted JSON to base64 String base64EncodedData = base64.encode(Utf8Encoder().convert(encodedData)); // Concatenate the base64-encoded data with the secret String dataToSign = base64EncodedData + paymentSecretKey; // Hash the result to SHA-256 Digest sha256Hash = sha256.convert(Utf8Encoder().convert(dataToSign)); final result = sha256Hash.toString(); log('auth token $result'); return result; } ``` {% endtab %} {% endtabs %} [^1]: [https://app.gitbook.com/o/gxK1VbNmJ8bcGc8xM5wD/s/dkkz4EKtpaWVPlq7ZwsC/\~/changes/61/spravochnik-metodov-api/vzaimodeistvie-s-formoi-oplaty](/platezhnyi-shlyuz/vzaimodeistvie-s-formoi-oplaty) # Дополнительные параметры При [взаимодействии с формой оплаты](/platezhnyi-shlyuz/vzaimodeistvie-s-formoi-oplaty) передается поле additional\_data.\ Данное поле содержит динамические параметры мерчанта, которые будут сохранены в платежной системе и переданы мерчанту в [webhook-e со статусом оплаты](/platezhnyi-shlyuz/webhook-platezhnoi-sistemy/status-oplaty) и в [запросе статуса транзакции](/platezhnyi-shlyuz/vspomogatelnye-metody/proverka-statusa-tranzakcii). {% hint style="warning" %} Поле additional\_data не участвует в формировании [подписи](/platezhnyi-shlyuz/formirovanie-podpisi) {% endhint %} # Взаимодействие с формой оплаты Создания транзакции с использованием платежной страницы системы {% content-ref url="/pages/ckuD2hfrCTOXtL9Ssqtm" %} [Инициация приёма денежных средств](/platezhnyi-shlyuz/vzaimodeistvie-s-formoi-oplaty/iniciaciya-priyoma-denezhnykh-sredstv) {% endcontent-ref %} {% content-ref url="/pages/W0l0HAktw86BHDcPZEUJ" %} [Инициация вывода денежных средств](/platezhnyi-shlyuz/vzaimodeistvie-s-formoi-oplaty/iniciaciya-vyvoda-denezhnykh-sredstv) {% endcontent-ref %} {% content-ref url="/pages/fBnyoEnqMmkUDKS8DxSK" %} [Привязка карты](/platezhnyi-shlyuz/vzaimodeistvie-s-formoi-oplaty/privyazka-karty) {% endcontent-ref %} # Инициация приёма денежных средств ## Приём средств без сохранённой карты ## Создание транзакции на прием `POST` `https://prapi.tarlanpayments.kz/transaction/api/v1/transaction/primal/pay-in` #### Headers
NameTypeDescription
Authorization*String Bearer Авторизационный хэш (см Формирование подписи)
#### Request Body | Name | Type | Description | | -------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | amount\* | Float | Сумма платежа | | project\_client\_id | String | Идентификатор клиента на стороне проекта | | callback\_url | String | URL проекта для оправки коллбэка со статусом транзакции (см Отправка callback) | | failure\_redirect\_url\* | String | Страница проекта на которую будет выполнен редирект пользователя после неуспешнй оплаты. Если параметр не был передан, редирект будет выполнен на success\_redirect\_url | | merchant\_id\* | Integer | Идентификатор мерчанта присваиваемый платежной системой | | project\_id\* | Integer |

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

| | project\_reference\_id\* | String | Идентификатор заказа на стороне мерчанта | | success\_redirect\_url\* | String | Страница проекта на которую будет выполнен редирект пользователя после успешной оплаты | | shipment | String | Адрес доставки | | confirm\_url | String | URL Проекта для подтверждения проведения оплаты (см. Подтверждение проведения оплаты) | | description\* | String | Описание платежа (50 символов) | | additional\_data | Object | Дополнительные параметры | | project\_order\_id | String | Номер заказа на стороне проекта | | is\_hold | Bool | Указание на [блокирование средств ](/platezhnyi-shlyuz/welcom/process-dvukhstadiinogo-platezha)при проведении платежа | {% tabs %} {% tab title="200: OK Пример успешного ответа" %} ```json { "status": true, "message": "Success", "result": "https://process.tarlanpayments.kz?hash=$2a$10$nhrUYWm9sDVYqCL4LKxn9ugrdC4Pszz5wGaUsDYYIqCGc8ZA4Vu0y&transaction_id=100474" } ``` {% endtab %} {% tab title="500: Internal Server Error Пример ответа с ошибкой" %} ```json { "status": false, "status_code": 5000, "message": "transaction already exists", "result": {} } ``` {% endtab %} {% endtabs %} Example of a **CURL** request: {% code fullWidth="true" %} ```bash curl --location 'https://prapi.tarlanpayments.kz/transaction/api/v1/transaction/primal/pay-in' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer sign' \ --data-raw '{ "amount": 10, "callback_url": "https://test.site/callback_url", "confirm_url": "https://test.site/confirm_url", "description": "999", "failure_redirect_url": "https://www.test.com", "merchant_id": 9999, "project_client_id": "999", "project_id": 9999, "project_reference_id": "999", "shipment": "Tarlan ave, Payments str.", "success_redirect_url": "https://www.test.com", "additional_data": { "test1": "value1", "test2": 2 } }' ``` {% endcode %} **Платеж по сохраненной карте** При передаче параметра `project_client_id` у пользователя на форме оплаты появится возможность сохранения карты. Для сохранения карты, пользователю, на форме оплаты необходимо кликнуть "сохранить карту" и провести успешный платёж по этой карте. Для последующих платежей по сохранённой карте необходимо передавать параметр `project_client_id`. Особенностью платежа по сохранённой карте является отсутствие 3DS аутентификации пользователя, значительно ускоряющий и упрощающий процесс оплаты. # Инициация вывода денежных средств ## Вывод средств без сохранённой карты ## Создание транзакции на вывод `POST` `https://prapi.tarlanpayments.kz/transaction/api/v1/transaction/primal/pay-out` #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ | | Authorization\* | String | Bearer Авторизационный хэш (см [Формирование подписи](/platezhnyi-shlyuz/formirovanie-podpisi)) | #### Request Body | Name | Type | Description | | -------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | amount\* | Float | Сумма платежа | | project\_client\_id | String | Идентификатор клиента на стороне проекта | | callback\_url | String | URL проекта для оправки коллбэка со статусом транзакции (см Отправка callback) | | failure\_redirect\_url | String | Страница проекта на которую будет выполнен редирект пользователя после неуспешной оплаты. Если параметр не был передан, редирект будет выполнен на `success_redirect_url` | | merchant\_id\* | Integer | Идентификатор мерчанта присваиваемый платежной системой | | project\_id\* | Integer |

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

| | project\_reference\_id\* | String | Номер заказа на стороне проекта | | success\_redirect\_url\* | String | Страница проекта на которую будет выполнен редирект пользователя после успешной оплаты | | shipment | String | Адрес доставки | | confirm\_url | String | URL Проекта для подтверждения проведения оплаты (см. [Подтверждение проведения оплаты](/platezhnyi-shlyuz/webhook-platezhnoi-sistemy/gotovnost-provedeniya-oplaty)) | | description\* | String | Описание платежа (50 символов) | | additional\_data | Object | [Дополнительные параметры](/platezhnyi-shlyuz/dopolnitelnye-parametry) | | c\_info | String | Информация о кредите | {% tabs %} {% tab title="200: OK Пример успешного ответа" %} 
{
    "status": true,
    "message": "Success",
    "result": "https://process.tarlanpayments.kz?hash=$2a$10$nhrUYWm9sDVYqCL4LKxn9ugrdC4Pszz5wGaUsDYYIqCGc8ZA4Vu0y&transaction_id=100474"
}
{% endtab %} {% tab title="500: Internal Server Error Примет ответа с ошибкой" %} 
{
    "status": false,
    "status_code": 5000,
    "message": "transaction already exists",
    "result": {}
}
{% endtab %} {% endtabs %} Пример запроса CURL: {% code fullWidth="true" %} ```bash curl --location 'https://prapi.tarlanpayments.kz/transaction/api/v1/transaction/primal/pay-out' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer sign' \ --data-raw '{ "amount": 10, "callback_url": "https://test.site/callback_url", "confirm_url": "", "description": "999", "failure_redirect_url": "https://www.test.com", "merchant_id": 9999, "project_client_id": "999", "project_id": 9999, "project_reference_id": "999", "shipment": "", "success_redirect_url": "https://www.test.com", "additional_data": { "test1": "value1", "test2": 2 } }' ``` {% endcode %} ## Вывод средств сохранённой карте При передаче параметра `project_client_id` у пользователя на форме оплаты появится возможность сохранения карты. Для сохранения карты, пользователю, на форме оплаты необходимо кликнуть "сохранить карту" и провести успешный вывод средств по этой карте. Для последующих платежей по сохранённой карте необходимо передавать параметр `project_client_id`. # Привязка карты 1. Создание транзакции для привязки карты с указанием project\_client\_id. 2. Создается платеж на 10тг. 3. Мерчант перенаправляет на страницу оплаты. 4. После проведения платежа происходит возврат 10тг. {% hint style="info" %} Результат привязки карты мерчант можете узнать в методе [получения списка привязанных карт пользователя](broken://pages/NUtlqVz5wJmuviFTrYpZ), [Webhook ](/platezhnyi-shlyuz/webhook-platezhnoi-sistemy/status-oplaty)отправляется после списания средств. При последующих оплатах пользователю будут доступны ранее привязанные карты. {% endhint %} ## Создание транзакции для привязки карты `POST` `https://prapi.tarlanpayments.kz/transaction/api/v1/transaction/primal/card-link` #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ | | Authorization\* | String | Bearer Авторотационный хэш (см [Формирование подписи](/platezhnyi-shlyuz/formirovanie-podpisi)) | #### Request Body | Name | Type | Description | | -------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | project\_id\* | Integer | Идентификатор проекта присваиваемый платежной системой | | merchant\_id\* | Integer | Идентификатор мерчанта присваиваемый платежной системой | | project\_client\_id\* | String | Идентификатор клиента на стороне проекта | | success\_redirect\_url\* | String | Страница проекта на которую будет выполнен редирект пользователя после успешной оплаты | | failure\_redirect\_url\* | String | Страница проекта на которую будет выполнен редирект пользователя после неуспешной оплаты. Если параметр не был передан, редирект будет выполнен на `success_redirect_url` | | description\* | String | Описание платежа (50 символов) | | additional\_data | Object | Дополнительные параметры | | callback\_url | String | URL проекта для оправки коллбэка со статусом транзакции (см [Отправка callback](/platezhnyi-shlyuz/webhook-platezhnoi-sistemy/status-oplaty)) | {% tabs %} {% tab title="200: OK Пример успешного ответа" %} ```json { "status": true, "message": "Success", "result": "https://process.tarlanpayments.kz?hash=$2a$10$nhrUYWm9sDVYqCL4LKxn9ugrdC4Pszz5wGaUsDYYIqCGc8ZA4Vu0y&transaction_id=100474" } ``` {% endtab %} {% tab title="500: Internal Server Error Пример ответа с ошибкой" %} ```json { "status": false, "status_code": 5000, "message": "transaction already exists", "result": {} } ``` {% endtab %} {% endtabs %} {% code fullWidth="true" %} ```bash curl --location 'https://prapi.tarlanpayments.kz/transaction/api/v1/transaction/primal/card-link' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer sign' \ --data-raw '{ "callback_url": "https://test.site/callback_url", "description": "desc", "failure_redirect_url": "https://www.test.com", "merchant_id": 2222, "project_client_id": "999", "project_id": 111, "success_redirect_url": "https://www.test.com", "additional_data": { "test": "value", "qwerty": "123" } }' ``` {% endcode %} # Инициация приёма денежных средств посредством Apple Pay *** {% hint style="info" %} Данный метод оплаты доступен только для операционных систем IOS. {% endhint %} *** ## Создание транзакции типа Apple Pay `POST` `https://prapi.tarlanpayments.kz/transaction/api/v1/transaction/primal/apple-pay` #### Headers
NameTypeDescription
Authorization*String Bearer Авторизационный хэш (см Формирование подписи)
#### Request Body | Name | Type | Description | | -------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | amount\* | Float | Сумма платежа | | project\_client\_id | String | Идентификатор клиента на стороне проекта | | callback\_url | String | URL проекта для оправки коллбэка со статусом транзакции (см Отправка callback) | | failure\_redirect\_url\* | String | Страница проекта на которую будет выполнен редирект пользователя после неуспешнй оплаты. Если параметр не был передан, редирект будет выполнен на success\_redirect\_url | | merchant\_id\* | Integer | Идентификатор мерчанта присваиваемый платежной системой | | project\_id\* | Integer |

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

| | project\_reference\_id\* | String | Идентификатор заказа на стороне мерчанта | | success\_redirect\_url\* | String | Страница проекта на которую будет выполнен редирект пользователя после успешной оплаты | | shipment | String | Адрес доставки | | confirm\_url | String | URL Проекта для подтверждения проведения оплаты (см. Подтверждение проведения оплаты) | | description\* | String | Описание платежа (50 символов) | | additional\_data | Object | Дополнительные параметры | | project\_order\_id | String | Номер заказа на стороне проекта | {% tabs %} {% tab title="200: OK Пример успешного ответа" %} ```json { "status": true, "message": "Success", "result": "https://process.tarlanpayments.kz?hash=$2a$10$nhrUYWm9sDVYqCL4LKxn9ugrdC4Pszz5wGaUsDYYIqCGc8ZA4Vu0y&transaction_id=100474" } ``` {% endtab %} {% tab title="500: Internal Server Error Пример ответа с ошибкой" %} ```json { "status": false, "status_code": 5000, "message": "transaction already exists", "result": {} } ``` {% endtab %} {% endtabs %} Example of a **CURL** request: ```bash curl --location 'https://prapi.tarlanpayments.kz/transaction/api/v1/transaction/primal/apple-pay' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer sign' \ --data-raw '{ "amount": 10, "callback_url": "https://test.site/callback_url", "confirm_url": "https://test.site/confirm_url", "description": "999", "failure_redirect_url": "https://www.test.com", "merchant_id": 9999, "project_client_id": "999", "project_id": 9999, "project_reference_id": "999", "shipment": "Tarlan ave, Payments str.", "success_redirect_url": "https://www.test.com", "additional_data": { "test1": "value1", "test2": 2 } }' ``` # Инициация приёма денежных средств посредство Google Pay *** {% hint style="info" %} Данный метод оплаты доступен только с использованием браузера Google Chrome {% endhint %} *** ## Создание транзакции типа Google Pay `POST` `https://prapi.tarlanpayments.kz/transaction/api/v1/transaction/primal/google-pay` `Headers`
NameTypeDescription
Authorization*String Bearer Авторизационный хэш (см Формирование подписи)
#### Request Body | Name | Type | Description | | -------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | amount\* | Float | Сумма платежа | | project\_client\_id | String | Идентификатор клиента на стороне проекта | | callback\_url | String | URL проекта для оправки коллбэка со статусом транзакции (см Отправка callback) | | failure\_redirect\_url\* | String | Страница проекта на которую будет выполнен редирект пользователя после неуспешнй оплаты. Если параметр не был передан, редирект будет выполнен на success\_redirect\_url | | merchant\_id\* | Integer | Идентификатор мерчанта присваиваемый платежной системой | | project\_id\* | Integer |

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

| | project\_reference\_id\* | String | Идентификатор заказа на стороне мерчанта | | success\_redirect\_url\* | String | Страница проекта на которую будет выполнен редирект пользователя после успешной оплаты | | shipment | String | Адрес доставки | | confirm\_url | String | URL Проекта для подтверждения проведения оплаты (см. Подтверждение проведения оплаты) | | description\* | String | Описание платежа (50 символов) | | additional\_data | Object | Дополнительные параметры | | project\_order\_id | String | Номер заказа на стороне проекта | {% tabs %} {% tab title="200: OK Пример успешного ответа" %} ```json { "status": true, "message": "Success", "result": "https://process.tarlanpayments.kz?hash=$2a$10$nhrUYWm9sDVYqCL4LKxn9ugrdC4Pszz5wGaUsDYYIqCGc8ZA4Vu0y&transaction_id=100474" } ``` {% endtab %} {% tab title="500: Internal Server Error Пример ответа с ошибкой" %} ```json { "status": false, "status_code": 5000, "message": "transaction already exists", "result": {} } ``` {% endtab %} {% endtabs %} Example of a **CURL** request: ```bash curl --location 'https://prapi.tarlanpayments.kz/transaction/api/v1/transaction/primal/google-pay' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer sign' \ --data-raw '{ "amount": 10, "callback_url": "https://test.site/callback_url", "confirm_url": "https://test.site/confirm_url", "description": "999", "failure_redirect_url": "https://www.test.com", "merchant_id": 9999, "project_client_id": "999", "project_id": 9999, "project_reference_id": "999", "shipment": "Tarlan ave, Payments str.", "success_redirect_url": "https://www.test.com", "additional_data": { "test1": "value1", "test2": 2 } }' ``` # Iframe Внедрение формы оплаты позволит пользователям внешнего сайта осуществлять платежи через свой сайт. Документация предоставляет шаги по созданию формы оплаты, обработке данных платежа и настройке размера Iframe. Для задания размера iframe установите атрибуты width и height в HTML-коде вашего iframe: ```html ``` Здесь width (ширина) установлена в 360 пикселей, а height (высота) установлена в 700 пикселей. Эти значения могут быть настроены в соответствии с вашими предпочтениями и дизайном внешнего сайта. # Платежи без формы оплаты # Платеж по сохраненной карте (one click) Платеж по сохраненной карте ## Проведение транзакции по сохраненной карте `POST` `https://prapi.tarlanpayments.kz/transaction/api/v1/system/one-click/pay-in` #### Request Body | Name | Type | Description | | -------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | amount\* | Float | Сумма платежа | | callback\_url | String | URL проекта для оправки коллбэка со статусом транзакции (см [Отправка callback](/platezhnyi-shlyuz/webhook-platezhnoi-sistemy/status-oplaty)) | | card\_token\* | String | Токен платежной системы полученный после [привязки карты](/platezhnyi-shlyuz/vzaimodeistvie-s-formoi-oplaty/privyazka-karty) в [webhook-e](/platezhnyi-shlyuz/webhook-platezhnoi-sistemy/status-oplaty), [списке карт](/platezhnyi-shlyuz/vspomogatelnye-metody/poluchenie-spiska-kart) или [статусе транзакции](/platezhnyi-shlyuz/statusy-tranzakcii) | | description\* | String | Описание платежа (50 символов) | | merchant\_id\* | Integer | Идентификатор мерчанта присваиваемый платежной системой | | project\_client\_id\* | String | Идентификатор клиента на стороне проекта | | project\_id\* | Integer | Идентификатор проекта присваиваемый платежной системой | | project\_reference\_id\* | String | Номер заказа на стороне проекта | | additional\_data | Object | [Дополнительные параметры](/platezhnyi-shlyuz/dopolnitelnye-parametry) | {% tabs %} {% tab title="200: OK Пример успешного ответа" %} ```json { "status": true, "message": "Success", "result": { "transaction_id": 140001455, "transaction_status_code": "success", "bank_code":"101", "bank_message":"3DS authentication failed" } } ``` {% endtab %} {% tab title="500: Internal Server Error Пример ответа с ошибкой" %} ```json { "status": false, "status_code": 5000, "message": "transaction already exists", "result": {} } ``` {% endtab %} {% endtabs %} {% code lineNumbers="true" fullWidth="true" %} ```bash curl --location 'https://prapi.tarlanpayments.kz/transaction/api/v1/system/one-click/pay-in' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer 123gf4d260ab38694d10833asdf3030d9a1cc75df4c598b0wer3230680923b1da7' \ --data-raw '{ "amount": 10, "callback_url": "", "card_token": "sdsd13123", "description": "test", "merchant_id": 9999, "project_client_id": "9999", "project_id": 9999, "project_reference_id": "9999" }' ``` {% endcode %} # Вывод по сохраненной карте (one click) Платеж по сохраненной карте ## Проведение транзакции по сохраненной карте `POST` `https://prapi.tarlanpayments.kz/transaction/api/v1/system/one-click/pay-out` #### Request Body | Name | Type | Description | | -------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | amount\* | Float | Сумма платежа | | callback\_url | String | URL проекта для оправки коллбэка со статусом транзакции (см [Отправка callback](/platezhnyi-shlyuz/webhook-platezhnoi-sistemy/status-oplaty)) | | card\_token\* | String | Токен платежной системы полученный после [привязки карты](/platezhnyi-shlyuz/vzaimodeistvie-s-formoi-oplaty/privyazka-karty) в [webhook-e](/platezhnyi-shlyuz/webhook-platezhnoi-sistemy/status-oplaty), [списке карт](/platezhnyi-shlyuz/vspomogatelnye-metody/poluchenie-spiska-kart) или [статусе транзакции](/platezhnyi-shlyuz/statusy-tranzakcii) | | description\* | String | Описание платежа (50 символов) | | merchant\_id\* | Integer | Идентификатор мерчанта присваиваемый платежной системой | | project\_client\_id\* | String | Идентификатор клиента на стороне проекта | | project\_id\* | Integer | Идентификатор проекта присваиваемый платежной системой | | project\_reference\_id\* | String | Номер заказа на стороне проекта | | additional\_data | Object | [Дополнительные параметры](/platezhnyi-shlyuz/dopolnitelnye-parametry) | {% tabs %} {% tab title="200: OK Пример успешного ответа" %} ```json { "status": true, "message": "Success", "result": { "transaction_id": 140001455, "transaction_status_code": "success", "bank_code":"101", "bank_message":"3DS authentication failed" } } ``` {% endtab %} {% tab title="500: Internal Server Error Пример ответа с ошибкой" %} ```json { "status": false, "status_code": 5000, "message": "transaction already exists", "result": {} } ``` {% endtab %} {% endtabs %} {% code lineNumbers="true" fullWidth="true" %} ```bash curl --location 'https://prapi.tarlanpayments.kz/transaction/api/v1/system/one-click/pay-out' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer 123gf4d260ab38694d10833asdf3030d9a1cc75df4c598b0wer3230680923b1da7' \ --data-raw '{ "amount": 10, "callback_url": "", "card_token": "sdsd13123", "description": "test", "merchant_id": 9999, "project_client_id": "9999", "project_id": 9999, "project_reference_id": "9999" }' ``` {% endcode %} # Вывод денежных средств (pay-out) Платеж реализующий вывод денежных средств ## Проведение транзакции по выводу денежных средств `POST` [https://prapi.tarlanpayments.kz/transaction/api/v1/system/pay-out](https://prapi.test-tarlanpayments.kz/transaction/api/v1/system/pay-out) `POST` #### Request Body | Name | Type | Description | | -------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | amount\* | Float | Сумма платежа | | callback\_url | String | URL проекта для оправки коллбэка со статусом транзакции (см [Отправка callback](/platezhnyi-shlyuz/webhook-platezhnoi-sistemy/status-oplaty)) | | description\* | String | Описание платежа (50 символов) | | project\_order\_id | String | Идентификатор заказа на стороне проекта | | merchant\_id\* | Integer | Идентификатор мерчанта присваиваемый платежной системой | | project\_client\_id | String | Идентификатор клиента на стороне проекта | | project\_id\* | Integer | Идентификатор проекта присваиваемый платежной системой | | project\_reference\_id\* | String | Номер заказа на стороне проекта | | encrypted\_pan\* | String | [Зашифрованные данные карты](/platezhnyi-shlyuz/platezhi-bez-formy-oplaty/shifrovanie-platezhnoi-karty) | | user\_phone | String | Номер телефона пользователя | | user\_email | String | Почта пользователя | | additional\_data | Object | [Дополнительные параметры](/platezhnyi-shlyuz/dopolnitelnye-parametry) | #### Header | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ | | Authorization\* | String | Bearer Авторотационный хэш (см [Формирование подписи](/platezhnyi-shlyuz/formirovanie-podpisi)) | | X-Accees-Key | String | Буквенно-цифровая строка для доступа к API | {% tabs %} {% tab title="200: OK Пример успешного ответа" %} ```json { "status": true, "message": "Success", "result": { "transaction_id": 139271, "transaction_status_code": "success", "acquirer_code": "jusan" } } ``` {% endtab %} {% tab title="500: Internal Server Error Пример ответа с ошибкой" %} ```json { "status": false, "status_code": 5000, "message": "transaction already exists", "result": {} } ``` {% endtab %} {% endtabs %} {% code lineNumbers="true" fullWidth="true" %} ```bash curl --location 'https://prapi.tarlanpayments.kz/transaction/api/v1/system/pay-out' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer token1' \ --header 'X-Accees-Key: 7e6c7a61-298d-4e09-9f50-cd7c4fc5ab35' \ --data-raw '{ "amount": 10, "project_client_id": "systemPayOutTest", "description": "System PayOut Test", "user_phone": "+77777777777", "callback_url": "https://website.com/31e680d7", "project_reference_id": "systemPayOutTest002", "merchant_id": 999, "project_id": 00, "user_email": "mail@mail.com", "encrypted_pan": "ZW5jcnlwdGVkX3Bhbg==" }' ``` {% endcode %} # Вывод денежных средств по мобильному номеру Платеж реализующий вывод денежных средств ## Создание транзакции для вывода по средств по мобильному номеру `POST` `POST` #### Request Body | Name | Type | Description | | -------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | phone\_number\* | String | Номер мобильного телефона для вывода средств | | callback\_url | String | URL проекта для оправки коллбэка со статусом транзакции (см [Отправка callback](/platezhnyi-shlyuz/webhook-platezhnoi-sistemy/status-oplaty)) | | description\* | String | Описание платежа (50 символов) | | merchant\_id\* | Integer | Идентификатор мерчанта присваиваемый платежной системой | | project\_client\_id | String | Идентификатор клиента на стороне проекта | | project\_id\* | Integer | Идентификатор проекта присваиваемый платежной системой | | project\_reference\_id\* | String | Номер заказа на стороне проекта | | user\_email | String | Почта пользователя | #### Header | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ | | Authorization\* | String | Bearer Авторотационный хэш (см [Формирование подписи](/platezhnyi-shlyuz/formirovanie-podpisi)) | {% tabs %} {% tab title="200: OK Пример успешного ответа" %} ```json { "status": true, "message": "Success", "result": { "transaction_id": 139271, "issuer_name": "Bank", "recipient_name": "John Doe", "card_type": "Visa", } } ``` {% endtab %} {% tab title="500: Internal Server Error Пример ответа с ошибкой" %} ```json { "status": false, "status_code": 5000, "message": "transaction already exists", "result": {} } ``` {% endtab %} {% endtabs %} {% code lineNumbers="true" fullWidth="true" %} ```bash curl --location 'https://prapi.tarlanpayments.kz/phone/api/v1/primal/payout/phone' \ --header 'accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer 123' \ --data-raw '{ "phone_number": "77777777777", "callback_url": "string", "user_email": "122@1212.kz", "project_reference_id": "1213", "amount": 10, "project_id": 99, "merchant_id": 99, "description": "test payout for visa+", "project_client_id": "99" }' ``` {% endcode %} ## Проведение транзакции для вывода по средств по мобильному номеру `POST` `POST` #### Request Body | Name | Type | Description | | ------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------- | | transaction\_id\* | String | Идентификатор транзакции полученный в методе [создания ](#sozdanie-tranzakcii-dlya-vyvoda-po-sredstv-po-mobilnomu-nomeru) | {% tabs %} {% tab title="200: OK Пример успешного ответа" %} ```json { "status": true, "message": "Success", "result": { "transaction_id": 139271, "transaction_status_code": "success", "acquirer_code": "jusan" } } ``` {% endtab %} {% tab title="500: Internal Server Error Пример ответа с ошибкой" %} ```json { "status": false, "status_code": 5000, "message": "transaction already exists", "result": {} } ``` {% endtab %} {% endtabs %} {% code lineNumbers="true" fullWidth="true" %} ```bash curl --location 'https://prapi.tarlanpayments.kz/phone/api/v1/payout/phone' \ --header 'accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer 1222' \ --data '{ "transaction_id": 139271 }' ``` {% endcode %} # Шифрование платежной карты В целях обеспечения безопасности данные платежной карты шифруются с использованием RSA PKCS1 Для шифрования необходимо: 1. Запрос GET [https://prapi.tarlanpayments.kz/card/api/v1/encryption/public-key](https://prapi.test-tarlanpayments.kz/card/api/v1/encryption/public-key) \ Запрос GET [https://sandboxapi.tarlanpayments.kz/card/api/v1/encryption/public-key](https://prapi.test-tarlanpayments.kz/card/api/v1/encryption/public-key) \ для получения publick\_key с помощью которого шифруются данные карт используя алгоритм RSA PKCS1 2. Формируем JSON.\ Для ***приема*** денежных средств необходимы все данные карты:\ `{"pan":"4049121234345656","exp_month":"04","exp_year":"26","cvc":"123","full_name":"Test test"}`\ Для ***вывод*** денежных средств необходимы только pan карты:\ `{"pan":"4049121234345656", "full_name":"Test test"}` 3. Шифруем получившийся объект используя алгоритм RSA PKCS1 и публичный ключ 4. Получившийся шифр кодируем в base64 Пример ответа GET {% code lineNumbers="true" %} ```json { "status": true, "message": "Success", "result": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxTl2VCVIQ3R6WWexWfEt\n80+mwQLOwVRSsmmoFZhYnuCgtdthJlb4CJ+LTup19ttHdU0h43r3W4urNDWWFuxf\nlKsIuuztP4Zc44TV4gG7YkHmz+iP90JrYzhE4yMaMYv0jTJ1lXBGTHk+Sfoa2nGg\nIdB/onVGfX27W7yjv62yZ/7V/GZljxP/8V3x/KRm/i05B4hsSE3DWw2AX+dOtvSj\n/JYXu713nGh4lsj9/CABT/GHkwY33e14YwXAS4P7f/ixGdcFudKU1QxIorFqOK0W\nDURmfnnoBuL1ailkHWb8LIu7FXUEbKi0QpmKsV5UnFWNuIQKtE/Mt+P6UJ/oGtdc\nHQIDAQAB\n-----END PUBLIC KEY-----" } ``` {% endcode %} {% tabs %} {% tab title="PHP" %} {% code lineNumbers="true" %} ```php $pan]); // Получаем публичный ключ $response = file_get_contents('https://prapi.tarlanpayments.kz/card/api/v1/encryption/public-key'); if ($response === FALSE) { throw new Exception('Can not get public key'); } $responseJson = json_decode($response, true); if (!isset($responseJson['result'])) { throw new Exception('Invalid response format'); } $publicKeyPem = $responseJson['result']; // Декодируем публичный ключ из формата PEM $publicKey = openssl_pkey_get_public($publicKeyPem); if ($publicKey === FALSE) { throw new Exception('Failed to parse public key'); } // Шифруем данные с использованием публичного ключа $encryptedCard = ''; if (!openssl_public_encrypt($panData, $encryptedCard, $publicKey)) { throw new Exception('Failed to encrypt data'); } // Возвращаем зашифрованную строку в формате base64 return base64_encode($encryptedCard); } try { $pan = '4049121234345656'; // Пример PAN, который можно заменить на любой другой $encryptedCard = encryptCard($pan); echo "Encrypted Card: " . $encryptedCard . PHP_EOL; } catch (Exception $e) { echo "Error: " . $e->getMessage() . PHP_EOL; } ?> ``` {% endcode %} {% endtab %} {% tab title="Python3" %} {% code lineNumbers="true" %} ```python import requests import json import base64 from Crypto.PublicKey import RSA from Crypto.Cipher import PKCS1_v1_5 as Cipher_PKCS1_v1_5 from Crypto.Random import get_random_bytes def encrypt_card(pan): pan_data = json.dumps({'pan': pan}).encode('utf-8') # Получаем публичный ключ response = requests.get('https://prapi.tarlanpayments.kz/card/api/v1/encryption/public-key') if response.status_code != 200: raise Exception('Can not get public key') response_json = response.json() if 'result' not in response_json: raise Exception('Invalid response format') public_key_pem = response_json['result'] # Декодируем публичный ключ из формата PEM public_key = RSA.import_key(public_key_pem) # Шифруем данные с использованием публичного ключа cipher = Cipher_PKCS1_v1_5.new(public_key) encrypted_card = cipher.encrypt(pan_data) # Возвращаем зашифрованную строку в формате base64 return base64.b64encode(encrypted_card).decode('utf-8') try: pan = '4049121234345656' # Пример PAN, который можно заменить на любой другой encrypted_card = encrypt_card(pan) print("Encrypted Card:", encrypted_card) except Exception as e: print("Error:", str(e)) ``` {% endcode %} {% endtab %} {% tab title="Golang" %} {% code lineNumbers="true" %} ```go package main import ( "crypto/rand" "crypto/rsa" "crypto/x509" "encoding/base64" "encoding/json" "encoding/pem" "errors" "fmt" "io" "net/http" ) func EncryptCard(pan string) (string, error) { panData := struct { Pan string `json:"pan"` }{ Pan: pan, } response := struct { PublicKey string `json:"result"` }{} notSortedJson, err := json.Marshal(panData) if err != nil { return "", err } publicKeyResp, err := http.Get("https://prapi.tarlanpayments.kz/card/api/v1/encryption/public-key") if err != nil { return "", err } defer publicKeyResp.Body.Close() if publicKeyResp.StatusCode != http.StatusOK { return "", errors.New("can not get public key") } readAll, err := io.ReadAll(publicKeyResp.Body) if err != nil { return "", err } err = json.Unmarshal(readAll, &response) if err != nil { return "", err } block, _ := pem.Decode([]byte(response.PublicKey)) if block == nil || block.Type != "PUBLIC KEY" { return "", fmt.Errorf("failed to parse PEM block containing the public key") } pub, err := x509.ParsePKIXPublicKey(block.Bytes) if err != nil { return "", fmt.Errorf("failed to parse public key: %v", err) } rsaPub, ok := pub.(*rsa.PublicKey) if !ok { return "", fmt.Errorf("not an RSA public key") } encryptedCard, err := rsa.EncryptPKCS1v15(rand.Reader, rsaPub, notSortedJson) if err != nil { return "", err } return base64.StdEncoding.EncodeToString(encryptedCard), nil } func main() { pan := "4049121234345656" // Пример PAN, который можно заменить на любой другой encryptedCard, err := EncryptCard(pan) if err != nil { fmt.Println("Error:", err) return } fmt.Println("Encrypted Card:", encryptedCard) } ``` {% endcode %} {% endtab %} {% tab title="1C" %} ```bsl Процедура ТестированиеEncryptCard() // Пример PAN для тестирования PAN = "4049121234345656"; // Вызов функции шифрования Попытка ЗашифрованнаяКарта = EncryptCard(PAN); Сообщить("Зашифрованная карта: " + ЗашифрованнаяКарта); Исключение Сообщить("Ошибка: " + ОписаниеОшибки()); КонецПопытки; КонецПроцедуры Процедура EncryptCard(PAN) // Данные карты ДанныеКарты = Новый Структура; ДанныеКарты.Вставить("pan", PAN); // Преобразование данных карты в JSON JSONСтрока = ПреобразованиеВJSON(ДанныеКарты); // Получение публичного ключа Запрос = Новый HTTPЗапрос("https://prapi.tarlanpayments.kz/card/api/v1/encryption/public-key"); HTTPСоединение = Новый HTTPСоединение("prapi.tarlanpayments.kz"); Ответ = HTTPСоединение.Получить(Запрос); Если Ответ.КодСостояния <> 200 Тогда Сообщить("Ошибка получения публичного ключа: " + Ответ.КодСостояния); Возврат ""; КонецЕсли; // Чтение тела ответа ТелоОтвета = Ответ.ПолучитьТелоКакСтроку(); Декодер = Новый JSONДекодер; ОтветJSON = Декодер.ПрочитатьJSON(ТелоОтвета); ПубличныйКлючСтрока = ОтветJSON.result; // Декодирование PEM и извлечение публичного ключа ПубличныйКлючБайты = КодировкаBase64.СтрокаВБайты(ПубличныйКлючСтрока); ПубличныйКлючPEM = ПолучитьPEM(ПубличныйКлючБайты); // Шифрование данных карты ЗашифрованнаяКарта = ШифрованиеRSA(ПубличныйКлючPEM, JSONСтрока); // Кодирование зашифрованных данных в Base64 ЗашифрованнаяКартаBase64 = КодировкаBase64.СтрокаИзБайтов(ЗашифрованнаяКарта); Возврат ЗашифрованнаяКартаBase64; КонецПроцедуры Функция ПреобразованиеВJSON(Данные) JSONЗапись = Новый ЗаписьJSON; JSONЗапись.УстановитьСтроку(); JSONЗапись.ЗаписатьЗначение(Данные); Возврат JSONЗапись.Закрыть(); КонецФункции Функция ПолучитьPEM(ПубличныйКлючБайты) ОткрытыйКлюч = Новый ОткрытыйКлючШифрования; ОткрытыйКлюч.Установить(ПубличныйКлючБайты); Возврат ОткрытыйКлюч; КонецФункции Функция ШифрованиеRSA(ОткрытыйКлюч, Данные) Результат = Новый Массив; Для Каждого Байт Из ОткрытыйКлюч.Шифровать(Данные, "RSA/ECB/PKCS1Padding") Цикл Результат.Добавить(Байт); КонецЦикла; Возврат Результат; КонецФункции ``` {% endtab %} {% endtabs %} # Вспомогательные методы Методы для оптимизации корректировки процесса оплаты {% content-ref url="/pages/99YRVWP5mG9I9XMni1Ol" %} [Проверка статуса транзакции](/platezhnyi-shlyuz/vspomogatelnye-metody/proverka-statusa-tranzakcii) {% endcontent-ref %} {% content-ref url="/pages/9gGuP8FIAkLieWm0soPd" %} [Получение списка карт](/platezhnyi-shlyuz/vspomogatelnye-metody/poluchenie-spiska-kart) {% endcontent-ref %} {% content-ref url="/pages/o7X3T9L7UzUu5oY8tYwE" %} [Возврат платежа](/platezhnyi-shlyuz/vspomogatelnye-metody/vozvrat-platezha) {% endcontent-ref %} # Удаление привязанной карты ## Удаление привязанной карты пользователя `DELETE` `https://prapi.tarlanpayments.kz/card/api/v1/system/client/card` #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ | | Authorization\* | String | Bearer Авторотационный хэш (см [Формирование подписи](/platezhnyi-shlyuz/formirovanie-podpisi)) | #### Request Body | Name | Type | Description | | ---------------------------------------------- | ------- | ------------------------------- | | project\_id\* | Integer | Идентификатор проекта | | card\_token\* | String | Токен карты в платежной системе | | merchant\_id\* | Integer | Идентификатор мерчанта | {% tabs %} {% tab title="200: OK Пример успешного ответа" %} ```json { "status": true, "message": "Success", "result": "success" } ``` {% endtab %} {% tab title="500: Internal Server Error Пример ответа с ошибкой" %} ```json { "status": false, "status_code": 5406, "message": "invalid project secret", "result": {} } ``` {% endtab %} {% endtabs %} {% code fullWidth="true" %} ```bash curl --location --request DELETE 'https://prapi.tarlanpayments.kz/card/api/v1/system/client/card/pay-in' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer auth_tokem' \ --data '{ "project_id": 3, "encrypted_card_id": "Qwerty12345", "merchant_id": 1 }' ``` {% endcode %} # Проверка статуса транзакции Для получения состояния транзакции есть возможность сделать запрос по идентификатору проекта (project\_id), информация о статусе хранится в поле [result.transaction\_status.code](/platezhnyi-shlyuz/statusy-tranzakcii). ## Запрос на получение статуса транзакции `GET` `https://prapi.tarlanpayments.kz/transaction/api/v1/system/transaction/status` #### Query Parameters | Name | Type | Description | | -------------------------------------------------------- | ------- | ------------------------------------------------------- | | project\_reference\_id\* | String | Номер заказа на стороне проекта | | merchant\_id\* | Integer | Идентификатор мерчанта присваиваемый платежной системой | | project\_id\* | Integer | Идентификатор проекта присваиваемый платежной системой | | type\* | String | [Тип транзакции](/platezhnyi-shlyuz/tipy-tranzakcii) | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ | | Authorization\* | String | Bearer Авторотационный хэш (см [Формирование подписи](/platezhnyi-shlyuz/formirovanie-podpisi)) | {% tabs %} {% tab title="200: OK Пример успешного ответа" %} {% code overflow="wrap" %} ```json { "status": true, "message": "Success", "result": { "finished_at": "2024-01-02T01:00:00.819045Z", "created_at": "2024-01-01T01:00:00.163609Z", "acquirer_code": "jusan", "acquirer_name": "Jusan Bank", "project_id": 99, "merchant_id": 999, "project_reference_id": "systemPayOutTest002", "project_client_id": "systemPayOutClient123", "transaction_type": { "code": "out", "name": "Вывод" }, "id": 139271, "amount": 10, "description": "System PayOut Desc", "user_phone": "+77777777777", "user_email": "mail@mail.com", "masked_pan": "", "transaction_status": { "code": "success", "name": "Транзакция прошла успешно" }, "refunds" : [] // fields: amount, date. } } ``` {% endcode %} {% endtab %} {% tab title="500: Internal Server Error Пример ответа с ошибкой" %} ```json { "status": false, "status_code": 5103, "message": "transaction not found", "result": {} } ``` {% endtab %} {% endtabs %} ```bash curl -X GET "https://prapi.tarlanpayments.kz/transaction/api/v1/system/transaction/status?merchant_id=284&project_id=81&project_reference_id=systemPayOutTest002&type=out" -H "accept: application/json" -H "Authorization: 3f37e1bc02ebe3b4b38612dea390c237de2a9e55c7083fe16bd32cc28662af4a" ``` # Получение списка карт ## Запрос на получения списка сохраненных карт `GET` `https://prapi.tarlanpayments.kz/transaction/api/v1/system/client/cards` #### Query Parameters | Name | Type | Description | | ----------------------------------------------------- | ------- | ------------------------------------------------------- | | merchant\_id\* | Integer | Идентификатор мерчанта присваиваемый платежной системой | | project\_client\_id\* | String | Идентификатор клиента на стороне проекта | | project\_id\* | Integer | Идентификатор проекта присваиваемый платежной системой | #### Headers | Name | Type | Description | | ------------- | ------ | ------------------------------------------------------------------------------------------------ | | Authorization | String | Bearer Авторотационный хэш (см [Формирование подписи](/platezhnyi-shlyuz/formirovanie-podpisi)) | {% tabs %} {% tab title="200: OK Пример успешного ответа" %} ```json { "status": true, "message": "Success", "result": [ { "card_token": "", "masked_pan": "0000-00XXXXXX-0000" }, { "card_token": "", "masked_pan": "0000-00XXXXXX-0000" }, { "card_token": "", "masked_pan": "0000-00XXXXXX-0000" } ] } ``` {% endtab %} {% tab title="500: Internal Server Error Пример ответа с ошибкой" %} ```json { "status": false, "status_code": 1021, "message": "request validation error", "result": {} } ``` {% endtab %} {% endtabs %} {% code overflow="wrap" lineNumbers="true" fullWidth="true" %} ```bash curl --location 'https://prapi.tarlanpayments.kz/transaction/api/v1/system/client/cards?merchant_id=999&project_id=999&project_client_id=999' \ --header 'Authorization: Bearer sign' \ --data '' ``` {% endcode %} # Возврат платежа `POST` `https://prapi.tarlanpayments.kz/refund/api/v1/system/refund/partial` #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ | | Authorization\* | String | Bearer Авторотационный хэш (см [Формирование подписи](/platezhnyi-shlyuz/formirovanie-podpisi)) | #### Request Body | Name | Type | Description | | ------------------------------------------------- | ------- | -------------------------------------------- | | amount\* | Integer | Сумма возврата | | transaction\_id\* | Integer | Идентификатор транзакции в платежной системе | {% tabs %} {% tab title="200: OK Пример успешного ответа" %} ```json { "status": true, "message": "Success", "result": "success" } ``` {% endtab %} {% tab title="500: Internal Server Error Пример ответа с ошибкой" %} ```json { "status": false, "status_code": 5103, "message": "transaction not found", "result": {} } ``` {% endtab %} {% endtabs %} ```bash curl --location 'prapi.tarlanpayments.kz/refund/api/v1/system/refund/partial' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer sign' \ --data '{ "amount": 10, "transaction_id": "refund" }' ``` # Расчет верхней комиссии `GET` `https://prapi.tarlanpayments.kz/commission/api/v1/system/project/upper/commission` #### Query Parameters | Name | Type | Description | | --------------------------------------------------------- | ------- | ------------------------------------------------------- | | project\_id\* | Integer | Идентификатор проекта присваиваемый платежной системой | | merchant\_id\* | Integer | Идентификатор мерчанта присваиваемый платежной системой | | transaction\_type\_code\* | String | [Тип транзакции](/platezhnyi-shlyuz/tipy-tranzakcii) | | transaction\_amount\* | Float | Сумма транзакции | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ | | Authorization\* | String | Bearer Авторотационный хэш (см [Формирование подписи](/platezhnyi-shlyuz/formirovanie-podpisi)) | {% tabs %} {% tab title="200: OK Пример успешного ответа" %} ```json { "status": true, "message": "Success", "result": { "total_commission_amount": 999.00 } } ``` {% endtab %} {% tab title="500: Internal Server Error Пример ответа с ошибкой" %} ```json { "status": false, "status_code": 5102, "message": "commission not found", "result": {} } ``` {% endtab %} {% endtabs %} {% code fullWidth="true" %} ```bash curl --location 'https://prapi.tarlanpayments.kz/comission/api/v1/system/project/upper/commission?merchant_id=999&project_id=999&transaction_amount=1000.00&transaction_type_code=in' \ --header 'Authorization: Bearer sign' \ --data '' ``` {% endcode %} # Подтверждение списания средств Метод подтверждения списания заблокированных средств пользователя. {% hint style="info" %} Данный метод можно использовать только при [двухстадийном платеже](/platezhnyi-shlyuz/welcom/process-dvukhstadiinogo-platezha). {% endhint %} `POST` `https://prapi.tarlanpayments.kz/transaction/api/v1/system/two-stage/charge` #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ | | Authorization\* | String | Bearer Авторотационный хэш (см [Формирование подписи](/platezhnyi-shlyuz/formirovanie-podpisi)) | #### Request Body | Name | Type | Description | | ------------------------------------------------- | ------- | ---------------------------------------------------------------- | | transaction\_id\* | Integer | Идентификатор транзакции, по которой необходимо сделать списание | | amount\* | Float | Сумма транзакции | {% tabs %} {% tab title="200: OK " %} ```json { "status": true, "message": "Success", "result": "success" } ``` {% endtab %} {% tab title="500: Internal Server Error " %} ```json { "status": false, "status_code": 5406, "message": "invalid project secret", "result": {} } ``` {% endtab %} {% endtabs %} {% code fullWidth="true" %} ```bash curl --location 'https://prapi.stage-tarlanpayments.kz/transaction/api/v1/system/two-stage/charge' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer sign' \ --data '{ "transaction_id": 999, "amount": 100 }' ``` {% endcode %} # Отмена списания средств Метод полной или частичной отмены блокировки заблокированных средств пользователя. {% hint style="info" %} Данный метод можно использовать только при [двухстадийном платеже](/platezhnyi-shlyuz/welcom/process-dvukhstadiinogo-platezha). {% endhint %} `POST` `https://prapi.tarlanpayments.kz/transaction/api/v1/system/two-stage/cancel` #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ | | Authorization\* | String | Bearer Авторотационный хэш (см [Формирование подписи](/platezhnyi-shlyuz/formirovanie-podpisi)) | #### Request Body | Name | Type | Description | | ------------------------------------------------- | ------- | ------------------------------------------------------------- | | transaction\_id\* | Integer | Идентификатор транзакции по которой необходимо сделать отмену | | amount\* | Float | Сумма отмены | | description\* | String | Описание причины отмены | | user\_email\* | String | Пользователь, совершивший отмену транзакции | {% tabs %} {% tab title="200: OK " %} ```json { "status": true, "message": "Success", "result": "success" } ``` {% endtab %} {% tab title="500: Internal Server Error " %} ```json { "status": false, "status_code": 5406, "message": "invalid project secret", "result": {} } ``` {% endtab %} {% endtabs %} {% code fullWidth="true" %} ```bash curl --location 'https://prapi.stage-tarlanpayments.kz/transaction/api/v1/system/two-stage/cancel' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer sign' \ --data '{ "transaction_id": 999, "amount": 100, "description": "test", "user_email": "a.ivanov@test.com" }' ``` {% endcode %} # Создание платежного поручения Метод для создания платежного поручения в разрезе одного дня `POST` `https://prapi.tarlanpayments.kz/payorder/api/v1/order` #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ | | Authorization\* | String | Bearer Авторотационный хэш (см [Формирование подписи](/platezhnyi-shlyuz/formirovanie-podpisi)) | #### Request Body | Name | Type | Description | | ------------------------------------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | payment\_order\_id\* | String | Идентификатор поручение на стороне мерчанта | | payment\_order\_date\* | Date |

Дата платежного поручение

в формате 2025-06-30

| | merchant\_id\* | String | Идентификатор мерчанта | | project\_id\* | Integer | Идентификатор проекта | | transfers \* | Array | Cписок трансферов | | transfers.name | String | Наименование субмерчанта | | transfers.bin\* | String | БИН/ИИН субмерчанта | | transfers.transfer\_id\* | String | Идентификатор трансфера на стороне мерчанта | | transfers.description | String | Описание трансфера | | transfers.amount\* | Float | Сумма трансфера | | transfers.beneficiary\_code\* | String | КБЕ | | transfers.payment\_purpose\_code\* | String | Код назначения платежа | | transfers.recipient\_account\* | String | Счет получателя | | transfers.is\_legal\* | Boolean |

Флаг, указывающий, является ли субъект юридическим лицом


Значения:
true — юридическое лицо
false — физическое лицо

| {% tabs %} {% tab title="200: OK " %} ```json { "status": true, "message": "Success", "result": "success" } ``` {% endtab %} {% tab title="500: Internal Server Error " %} ```json { "status": false, "status_code": 5406, "message": "invalid project secret", "result": {} } ``` {% endtab %} {% endtabs %} {% code fullWidth="true" %} ```bash curl --location 'https://prapi.tarlanpayments.kz/payorder/api/v1/order' \ --header 'Authorization: Bearer 123' \ --header 'Content-Type: application/json' \ --data '{ "project_id": 99, "transfers": [ { "name": "string", "bin": "11011000999", "transfer_id": "transfer_id", "description": "string", "amount": 150, "beneficiary_code": "13", "payment_purpose_code": "123", "recipient_account": "KZ111011111000011111", "is_legal": true } ], "merchant_id": 1, "payment_order_date": "2025-06-30", "payment_order_id": "payment_order_id" }' ``` {% endcode %} # Webhook платежной системы # Статус оплаты Метод предназначен для оповещения системы проекта о статусе платежа. ### Backoff Policy Для увеличения гарантий получения ответа используются BackOff-политики при выполнении запросов: * InitialInterval = 500 \* time.Millisecond, интервалы между повторными запросами * RandomizationFactor = 0.5, Разброс запроса по времени между повторами * MaxInterval = 60 \* time.Second, Максимальное время между повторами * MaxElapsedTime = 10 \* time.Minute, время в течении которого будут выполнены попытки #### Callback платежной системой после каждой операции После завершения оплаты, платежная система делает запрос в проект партнера для передачи состояния платежа. Запрос делается на адрес указанный в поле `callback_url` при инициации платежа. При получении http статуса отличного от 200 транзакция будут выполнены BackOff политики ## Отправка callback-a проект партнера `POST` `callback_url` #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ | | Authorization\* | String | Bearer Авторотационный хэш (см [Формирование подписи](/platezhnyi-shlyuz/formirovanie-podpisi)) | #### Request Body | Name | Type | Description | | -------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------- | | created\_at\* | String | Дата создания транзакции | | transaction\_id\* | Integer | Идентификатор транзакции на стороне платежной системы | | acquirer\_code\* | String | Идентификатор банка | | project\_reference\_id\* | String | Идентификатор транзакции на стороне проекта | | project\_сlient\_id\* | String | Идентификатор пользователя на стороне проекта | | status\_code\* | String | [Статус транзакции](/platezhnyi-shlyuz/statusy-tranzakcii) | | type\_code\* | String | [Тип транзакции](/platezhnyi-shlyuz/tipy-tranzakcii) | | amount\* | Float | Сумма транзакции | | description\* | String | Описание | | finished\_at\* | String | Дата завершения транзакции | | project\_id\* | Integer | Идентификатор проекта | | merchant\_id\* | Integer | Идентификатор мерчанта | | additional\_data | Object | Дополнительные поля | | card\_token | String | Токен карты в платежной системе | | masked\_pan | String | Маскированная карта платежа | | bank\_code | String | [Код ошибки](/platezhnyi-shlyuz/kody-oshibok) передается в случае ошибки в транзакции | | bank\_message | String | Описание ошибки | | ips | String | МПС система (visa/mastercard...) | | issuer | String | Эмитент карты | 
{
  "created_at": "2023-12-25T16:04:26.611025Z",
  "finished_at": "2023-12-25T16:05:47.672271Z",
  "transaction_id": 999,
  "acquirer_code": "jusan",
  "project_id": 999,
  "merchant_id": 999,
  "project_reference_id": "121adsf",
  "project_client_id": "12dfsd",
  "card_token": "qkRCjlJrAmbL7RMIqeS1OHGYLJpEbf7toQo/2zk+/8zCyaiQ",
  "masked_pan": "0000-00XXXXXX-0000",
  "year": "24",
  "month": "12",
  "ips": "VISA",
  "issuer": "JSC ALLIANCE BANK",
  "status_code": "success",
  "type_code": "in",
  "amount": 100,
  "description": "Оплата заказа",
  "additional_data": {}
}
[^1]: # Готовность проведения оплаты Метод предназначен для подтверждение оплаты заказа на стороне проекта. Системой отправляется запрос на confirm\_url проекта и ожидает ответ с обязательными параметрами: `id`, `status`, `message`, `is_payble`. Метод будет отработан если параметр `confirm_url` был передан при инициации платежа. ### Backoff Policy Для увеличения гарантий получения ответа используются BackOff политики при выполнении запросов: * InitialInterval = 500 \* time.Millisecond, интервалы между повторными запросами * RandomizationFactor = 0.5, Разброс запроса по времени между повторами * MaxInterval = 60 \* time.Second, Максимальное время между повторами * MaxElapsedTime = 10 \* time.Minute, время в течении которого будут выполнены попытки `GET` `https://merchant-website/confirm` #### Query Parameters | Name | Type | Description | | -------------------------------------------------------- | ------ | ---------------------------------------------------- | | type\* | string | [Тип транзакции](/platezhnyi-shlyuz/tipy-tranzakcii) | | project\_reference\_id\* | string | Номер заказа на стороне проекта | #### Headers | Name | Type | Description | | ------------- | ------ | ------------------------------------------------------------------------------------------------ | | Authorization | String | Bearer Авторотационный хэш (см [Формирование подписи](/platezhnyi-shlyuz/formirovanie-podpisi)) | {% tabs %} {% tab title="200: OK Пример ответа проекта. Все поля обязательны." %} ```json { "id": "121abc", // Идентификатор транзакции на стороне проекта "status": "success", // Статус заказа на стороне проекта "message": "order desciption", // Текстовое сопровождение ответа "is_payble" : true // Разрешение на проведение платежа } ``` {% endtab %} {% endtabs %} В зависимости от значения параметра `is_payble` системой принимается решение о проведении платежа: * `true` - Проект разрешает проведение платежа * `false` - Проект отказывает в проведении платежа # Smart Pay 1. Google pay # Google pay Google Pay — это система онлайн-платежей, которая позволяет совершать покупки в приложении и на веб-сайте. Система позволяет пользователям совершать платежи онлайн из Интернета, а также с помощью телефонов, планшетов и часов Android. Прежде чем интегрироваться с Tarlan Payments, Вам нужно ознакомится с документацией.\ [Виды интеграции и официальная документация Google.](https://developers.google.com/pay/api) Поддерживаемый тип интеграции для сайтов - Web. Для данной интеграции вам необходимо ознакомиться со следующими документами: * [Документация Google Pay для сайтов](https://developers.google.com/pay/api/web/overview) * [Контрольный список интеграции Google Pay для сайтов](https://developers.google.com/pay/api/web/guides/test-and-deploy/integration-checklist) * [Правила фирменного оформления Google Pay для сайтов](https://developers.google.com/pay/api/web/guides/brand-guidelines) Для работы с Google Pay Вам необходимо зарегистрироваться в [Google Pay & Wallet Console](https://pay.google.com/business/console) и получить идентификатор продавца Google. Все продавцы обязаны соблюдать [правила допустимого использования](https://payments.developers.google.com/terms/aup) и [Условия использования](https://payments.developers.google.com/terms/sellertos) Google Pay API. Для параметров: **gateway** необходимо указывать значение - tarlanpayments; **gatewayMerchantId** необходимо указывать - идентификатор продавца Google; Поддерживаемые методы аутентификации: PAN\_ONLY и CRYPTOGRAM\_3DS. Поддерживаемые платёжные системы Visa и Master Card. В передаче платежного адреса нет необходимости. Полученный от Google платежный токен необходимо передавать в поле token в формате string. Передавать его нужно в том же виде, в котором вы его получили от Google. Остальные параметры описаны ниже. # CMS # WordPress [GitHub](https://github.com/tarlanpay/tarlan-woocommerce) * Виджет * Выбор дизайна виджета * Выбор локализации виджета * Уведомления * Apple Pay и Google Pay * WordPress любая версия * WooCommerce любая версия * WooCommerce Subscriptions 2.5.3 и выше # Bitrix [GitHub](https://github.com/tarlanpay/tarlan-bitrix) Возможности: * Виджет * Настройка виджета * Локализация * Уведомления * Совместимость с Бизнесом # Tilda Подключение платежного шлюза Tarlan Payments при создании интернет-магазина в Tilda Для подключения вам необходимо: 1. Пройти все [этапы имплементации](/#etapy-implementacii) Вы получите: * Идентификатор проекта мерчанта (merchant\_id:project\_id) * Ключ (project\_key) 2. Перейдите в Tilda → Настройки сайта → Платежные системы
3. Выбираем "Универсальная платежная система"
4. В выпадющем списке выбираем [TarlanPayments](https://tarlanpayments.kz/) 5. Введите данные полученные от в поля\ "ЛОГИН" : merchant\_id:project\_id \ "СЕКРЕТ ДЛЯ ПОДПИСИ ЗАКАЗА" : project\_key
6. Поле "ЗАГОЛОВОК" редактируем на свое усмотрение\ ![](/files/VGT0m7uuHaJGMORlGiMK) *Если подключено несколько платежных систем, то они автоматически появятся в вариантах оплаты при покупке товара.* # Сводка изменений
ВерсияОписание
1.3.0 от 15.05.24
  1. Добавлена поддержка AGWS в лк
1.2.6 от 17.04.24
  1. Возможность изменения цветовой палитры платежной формы в ЛК
  2. Отправка /pages/vyIBCRLFzmwCJDsm0ETA в webhook-e /pages/J8upgdcouuqeSf3VAeOb
1.2.5 от 03.04.24
  1. Добавлена возможность блокировки пользователя
  2. Интеграция с /pages/t0cRX2KtffWCgWk5RP85
  3. Плагин для работы в /pages/xaRNePE3KXfKtE3O9kQf
1.2.4 от 20.03.24
  1. Возможность добавлять пользователей в ЛК
  2. Добавлена возможность создания ссылки на транзакцию через ЛК
  3. Причина отказа банка выведена в детализацию транзакции в ЛК
  4. Добавлены логи запроса в банк
1.2.3 от 6.03.24
  1. Добавлена возможность редиректа по таймеру на url мерчанта на странице чека
  2. Добавлена возможность выводить описание в платежную страницу
1.2.2 от 21.02.24
  1. Оптимизирована работа шифрования и улучшена криптостойкость
  2. Добавлена настройка планирование рассылки отчетов в ЛК мерчанта
1.2.1 от 07.02.24
  1. Добавлена возможность предзаполнить карту на платежной формы при их наличии у пользователя
  2. Добавлен выбор стилей платежной формы по умолчании при отсутвии настроек мерчанта
  3. Оптимизирована отрисовка платежной страницы
  4. Добалено логирование действий пользователя
1.2.0 от 24.01.24
  1. Возможность создания двухстадийного способа оплаты
    Методы для управления списанием и отменой заблокированных средств
  2. Добавлено поле project_order_id являющееся идентификатором заказа
1.1.2 от 21.11.23Добавлены коды ошибок коды ошибок провайдера.
1.1.1 от 01.11.23
  1. Получение email, phone перенесено на платежную страницу, обязательность регулируется в ЛК мерчанта.
  2. Исправлена ошибка подписи с использованием поля additional_data.
1.1.0 от 19.10.23
  1. Возврат Платежа

Раздел:
API Возврата платежа

  1. Привязка Карты: Пользователи могут привязывать свои карты для быстрых и безопасных транзакций двумя способами:
    - на платежном виджете
    - через back-to-back решение

Раздел:
API Привязки карты пользователя

  1. Прием и Вывод Средств с Сохраненной Карты Пользователя: Мы предоставляем удобный способ приема и вывода денег, используя сохраненные карты.

Разделы:

API Приёма по сохраненной карте
API Вывода по сохраненной карте

  1. Метод вызова сохраненных карт:

Возможность получения токена карты:
- в статусе транзакции
- через Webhook
Разделы:
API Вызова сохраненных карт

  1. Google Pay: Теперь поддерживается Google Pay для удобных и быстрых онлайн-платежей.

Разделы:
API для Google Pay

  1. Интеграция через iframe: Мы предоставляем возможность интеграции с нашим приложением через iframe для улучшенного пользовательского опыта.

Раздел:
Возможность интеграции через iframe

  1. Интеграция через Tilda Publishing: Теперь вы можете интегрировать наше приложение с Tilda Publishing для создания великолепных лендингов и интерактивных страниц.

Раздел:

Возможность интеграции через Tilda Publishing

  1. Изменения в формировании подписи: Мы внесли улучшения в процесс формирования подписей, обеспечивая более высокий уровень безопасности.

Раздел:
Изменения в формировании подпис

1.0.0 от 01.08.23
  1. Приём и вывод денежных средств:

Теперь вы можете принимать и выводить деньги через наше приложение, независимо от вашей роли или цели.
Мы предоставляем полную интеграцию для управления финансами

Разделы:
API Создание платежа на приём средств
API Создание платежа на вывод средств

  1. Формирование Цифровой Подписи:

Добавлена возможность создания цифровой подписи для всех финансовых операций, обеспечивающая дополнительную безопасность транзакций.
Раздел:
API Формирование подписи

  1. Отправка Call-Back-ов:

Теперь система автоматически отправляет уведомления платежной организации после успешных транзакций, улучшая процесс обработки платежей.
Раздел:
API Отправка call-back-ов

# Коды состояния аккаунта | Код состояния | Описание | | ------------- | ------------------------------ | | 0 | Аккаунт не может быть пополнен | | 1 | Аккаунт может быть пополнен | | 2 | Аккаунт не верифицирован | # Статусы транзакции | Код статуса | Сообщение | Описание | Финальность | | ----------- | -------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------- | | 1 | Transaction created | Транзакция создана(промежуточная) | Нет | | 2 | Transaction successfully processed | Транзакция успешно проведена | Да | | 3 | Transaction was canceled by user | Транзакция отменена пользователем | Да | | 4 | Transaction was failed | Транзакция завершена неуспешно | Да | | 5 | Transaction holded by service provider | Транзакция проводится на стороне поставщика услуг | Нет | | 6 | Transaction finished with error | Транзакция завершена с ошибкой | Необходимо дополнительно запрашивать статус вручную\* | | 7 | Транзакция находится в обработке | Транзакция находится в обработке, будет завершена в течении времени | Нет | **\*Транзакции со статус кодом 6 нужно запрашивать дополнительно у технической поддержки. Почта технической поддержки - ******** # Коды ошибок ## Ожидаемые ошибки **Ожидаемые ошибки** — это ошибки, которые всегда возвращаются с кодом статуса HTTP 200 OK. Эти ошибки указывают на то, что **запрос** был успешно обработан, даже если результат привел к ошибке. Стандартный формат ответа JSON для ожидаемых ошибок указан ниже: ```json { "status": true, "status_code": 0, "message": "Success", "result": { "error_code": 1042, "message": "duplicate external id", "data": null, } } ``` Детали ошибки находятся в параметре `result` в полях `error_code` и `message`. | Code | Text message | Description | HTTP Status | | ---- | ---------------------------- | --------------------------------------------------------- | ----------- | | 0 | Success | Запрос успешно обработан | 200 | | 8301 | Unexpected db error | Неопознанная ошибка при обработке ресурса | 200 | | 1407 | Cache: item not found | Запрашиваемый ресурс не найден | 200 | | 1041 | Order not found | Платеж с таким идентификатором не найден | 200 | | 1042 | duplicate external id | Повторное проведение платежа с одинаковым идентификатором | 200 | | 9718 | provider not found | Запрашиваемый поставщик не найден | 200 | | 8015 | account doesn't exist | Запрашиваемый баланс не найден | 200 | | 9724 | showcase not found | Запрашиваемая витрина не найдена | 200 | | 9721 | showcase service not found | Запрашиваемая услуга витрины не найдена | 200 | | 5103 | transaction not found | Запрашиваемая транзакция не найдена | 200 | | 5413 | transaction already finished | Запрашиваемая транзакция финализирована | 200 | | 8008 | project doesn't exist | Запрашиваемый проект не найден | 200 | | 1410 | not enough balance | Недостаточно средств на балансе витрины | 200 | | 9902 | parking doesn't exists | Parking doesn't exists | 200 | | 9726 | project limit not found | Ошибка на стороне платежной организации | 200 | | 2012 | project commission not found | Ошибка на стороне платежной организации | 200 | | 1600 | amount limit exceeded | Сумма транзакции выходит за допустимые пределы проекта | 200 | ## Неожидаемые ошибки **Неожидаемые ошибки** — это ошибки, которые возвращаются с кодом HTTP, указывающим на сбой (например, 400 или 500). Эти ошибки сигнализируют о том, что запрос не был выполнен из-за таких проблем, как ошибки валидации, проблемы аутентификации или системные ошибки. Стандартный формат ответа JSON для неожиданных ошибок указан ниже: ```json { "status": false, "status_code": 1014, "message": "Invalid signature", "result": {} } ``` Поля`status_code` и`message` предоставляют основную информацию об ошибке.
CodeText messageDescriptionHTTP Status
500Internal Server ErrorНеопознанна ошибка сервера500
1014Invalid signatureНеправильно сформулированная подпись400
1021request validation errorНеправильное тело запроса400
1404Invalid action requestНе передано значение поля400
5629empty service codeне передано значение service_code400
5610invalid project codeне передано значение project, либо неверное значение400
1301login is not verifiedне передано значение username400
999999Unknown errorНепредвиденная ошибка500
# Причина отклонения операции **Причина отклонения операции** описывает обстоятельства или условия, из-за которых операция не был успешно завершен. Это может включать ошибки пользователя (например, недостаточно средств), проблемы с верификацией или ограничения на стороне платежной системы или банка. Структура поля: ```json "fail_reason": { "code": 100, "message": "Unknown reason, clarification required" } ``` Причина отклонения платежа, передаются как доп. параметры в следующих методах: * [Callback платежной системы ](/agws/callback-platezhnoi-sistemy) ```json { "project": "Testing", "service_code": "70958", "external_id": "proident", "status_code": "4", "status_message": "Transaction was failed", "amount": 100.82, "datetime": "2022-12-01T15:45:00Z", "username": "enim", "fail_reason": { "code": 100, "message": "Unknown reason, clarification required" } } ``` * [Проверка статуса пополнения](/agws/proverka-statusa-popolneniya) ```json { "status": true, "status_code": 0, "message": "Success", "result":{ "error_code" : 0, "message": "", "data": { "status_code": "4", "status_message": "Transaction was failed", "username": "989898", "amount": 100, "datetime": "2022-12-01T15:45:00Z", "project": "mobile", "fail_reason": { "code": 100, "message": "Unknown reason, clarification required" } "service_code": "201106", "external_id": "200001", } } ``` * [Проверка состояния аккаунта](/agws/proverka-sostoyaniya-akkaunta) ```json { "status": true, "status_code": 0, "message": "Success", "result": { "error_code": 0, "message": "This account is inactive", "account_status": 0, "fail_reason": { "code": 100, "message": "Unknown reason, clarification required" }, "info": { "parking": { "in_date": "2024-08-02T12:24:07+05:00", "left_free_time_minutes": 0, "sum": 118, "current_balance": -1 } } } } ``` * [Проведение платежа](/agws/provedenie-platezha), передаются при статусе [Transaction was failed](/agws/statusy-tranzakcii) ```json { "status": true, "status_code": 0, "message": "Success", "result": { "error_code": 0, "message": "", "data": { "status_code": "4", "status_message": "Transaction was failed", "username": "12345", "amount": 1000, "datetime": "2024-01-01T00:00:00", "project": "project", "service_code": "service", "external_id": "200001", "fail_reason": { "code": 100, "message": "Unknown reason, clarification required" }, } } } ``` * [Подтверждение списания средств](/agws/podtverzhdenie-spisaniya-sredstv), передаются при статусе [Transaction was failed](/agws/statusy-tranzakcii) ```json { "status": true, "status_code": 0, "message": "Success", "result": { "is_success": true, "transaction_status_id": "4", "external_id": "200001", "message": "", "otp_status": false, "fail_reason": { "code": 402, "message": "Incorrect confirmation code" } } } ```
codemessageОписание
100Unknown reason, clarification requiredНеизвестная причина, необходимо уточнение
101Error on the service provider sideОшибка на стороне поставщика услуг
102Request validation errorОшибка валидации запроса
103A payment with the specified ID already exists in the systemплатеж с указанным идентификатором уже присутствует в системе
104Transaction with the specified ID is not found in the systemтранзакция с указанным идентификатором отсутствует в системе
105Authorization errorОшибка авторизации
106Verification via the provider's server is unavailable. You can make a payment if you are confident in the parametersПроверка через сервер поставщика недоступна
107Transaction failed by timeoutОперация была отклонена по истечению времени жизни
200Insufficient balanceНедостаточно баланса
201Invalid ID formatНеверный формат идентификатора
202Unverified accountНеверифицированный аккаунт
203Phone number not available for top-upНомер телефона, недоступный для пополнения
204Operation limit exceeded for a user with simplified identificationПревышение лимита по операции для упрощенно идентифицированного пользователя
205Operation limit exceeded for an identified userПревышение лимита по операции для идентифицированного пользователя
206Operation limit exceeded for an unidentified userПревышение лимита по операции для не идентифицированного пользователя
207Invoices are not yet generated. The provider may generate new month invoices during a period when they cannot be obtained.Инвойсы ещё не сформированы
300The payment amount is too largeСлишком большое значение суммы платежа
301Limit exceededПревышение лимита
302Incorrect payment amountНекорректная сумма платежа
303The payment amount is less than the minimum valueСумма платежа меньше установленного значения
304Amount out of acceptable rangeСумма вне допустимого диапазона
400Receiving two confirmation requests for the same operation with a minimal intervalПолучение 2 запросов на подтверждение одной операции с минимальным интервалом
401Transaction lifespan expiredИстек срок жизни транзакции
402Incorrect confirmation codeНеверный код подтверждения
403The service has already been paidУслуга уже была оплачена
404The specified zone does not existУказанная зона не существует
405The specified zone is inactiveУказанная зона не активна
406A parameter required for payment is missingПропущен параметр для оплаты
407Exceeded the number of confirmation code attemptsПревышено количество попыток ввода кода подтверждения
# Время жизни транзакции Каждая транзакция имеет параметр "время жизни" означающий временной промежуток в рамках которого система будет дожидаться подтверждения транзакции. Если по истечению данного срока транзакция не была подтверждена - она будет автоматически переведена в статус [Transaction was failed ](/agws/statusy-tranzakcii)и в случае если был указан параметр сallback\_url в [Проведение платежа](/agws/provedenie-platezha) будет отправлен [callback](/agws/callback-platezhnoi-sistemy) с указанием причины в поле [fail\_reason](/agws/prichina-otkloneniya-operacii). Финализации подлежат только транзакции находящие в статусе [Transaction created](/agws/statusy-tranzakcii) Параметр "время жизни" устанавливается индивидуально для мерчанта при заведении его услуги в системе. # Формирование подписи Запросы для взаимодействия с сервисом подписываются с использованием алгоритма SHA256. Подпись формируется отдельно для каждого запроса. Для формирования подписи, выполните следующие шаги: 1. **Тело запроса сортируется по алфавиту и кодируется в BASE64.** 2. **Конкатенируем кодированное тело запроса и secret\_key(предоставляется отдельно)** 3. **Используя хэш функцию SHA256 хэшируем полученный результат конкатенации** 4. **Добавляем подпись в заголовках запроса X-Signature** {% hint style="warning" %} В формировании подписи не учавствуют ключи имеющие вложенную структуру: * info {% endhint %} Поля запроса заполненные как **""** не участвуют в формировании подписи./ {% tabs %} {% tab title="Python3" %} ```python import json import base64 import hashlib #Тело запроса меняется в зависимости от запроса request_data = { "agent": "tarlan", "project": "mobile", "service_code": "101", } #Для примера взяли secret 12345 secret = "12345" sorted_data = json.dumps( request_data, sort_keys=True, ensure_ascii=False, separators=(',', ':'), ) base64_encoded_data = base64.b64encode(sorted_data.encode()).decode() data_to_sign = base64_encoded_data + secret sha256_hash = hashlib.sha256(data_to_sign.encode()).hexdigest() print("Sign:",sha256_hash) ``` {% endtab %} {% tab title="Golang" %} ```go package main import ( "crypto/sha256" "encoding/base64" "encoding/json" "fmt" ) //Тело запроса меняется в зависимости от запроса type Request struct { Agent string `json:"agent"` Project string `json:"project"` ServiceCode string `json:"service_code"` } //Для примера secret 12345 const secret = "12345" func main() { request := Request{ Agent: "tarlan", Project: "mobile", ServiceCode: "101", } notSortedJson, err := json.Marshal(&request) if err != nil { panic(err) } var notSortedMap map[string]interface{} if err = json.Unmarshal(notSortedJson, ¬SortedMap); err != nil { panic(err) } sortedJson, err := json.Marshal(¬SortedMap) if err != nil { panic(err) } signData := base64.StdEncoding.EncodeToString(sortedJson) sign := sha256.Sum256([]byte(signData + secret)) fmt.Printf("Sign: %x", sign) } ``` {% endtab %} {% endtabs %} # Проверка состояния аккаунта {% hint style="danger" %} **ВНИМАНИЕ: Новый формат ответа для ошибок** В ближайшее время в нашей системе ошибки будут разделены на **ожидаемые** и **неожидаемые**. Это приведет к изменению формата JSON-ответа в зависимости от типа ошибки. Пожалуйста, ознакомьтесь с изменениями на странице [**Коды Ошибок**](/agws/kody-oshibok). Изменения будут применены ко всем API в системе AGWS, за исключением методов «[Проведение платежа](/agws/provedenie-platezha)». Нажмите [здесь](#primery-otvetov-ob-oshibkakh-do-vneseniya-izmenenii), чтобы просмотреть старые и новые ответы об ошибках JSON. Обратите внимание на это обновление и убедитесь, что ваша система готова к изменениям, если это необходимо. {% endhint %} ## Проверка статуса аккаунта по username `POST` `https://agwsapi.tarlanpayments.kz/showcase-gateway/api/v1/user/check` **Headers** | Name | Value | | ------------ | -------------------------------------------------------------- | | Content-Type | `application/json` | | X-Signature | [Авторизационный хэш](/platezhnyi-shlyuz/formirovanie-podpisi) | **Body**
NameTypeDescription
username*StringИдентификатор пользователя
agent*StringКод витрины в системе Tarlanpayments
project*StringКод Проекта присваиваемый Tarlanpayments
service_code*StringИдентификатор услуги на стороне витрины
infoObjectДополнительные параметры зависящие от категории услуг
```json { "username": "1234AAA05", "agent": "agent1", "project": "project1", "service_code": "123", "info": { "parking": { "in_date": "2024-08-02T12:24:07+05:00", "left_free_time_minutes": 0, "sum": 118, "current_balance": -1, "zone": "1223-123", "duration":1, "coordinates": { "latitude": 123.12, "longitude": 123.0212 }, "phone": "77077777777" } } } ``` **Response**
NameTypeDescription
statusboolСтатус обработки запроса
status_codeuintКод ошибки
messagestringОписание ошибки
resultObjectРезультат запроса, в котором содержится информация
-error_codeIntegerКод ошибки
-messageStringОписание ошибки
-account_statusIntegerСостояние аккаунта. Подробнее см. в справочнике состояния аккаунта
-amountFloatФиксированная сумма платежа
-upper_commissionFloatВерхняя коммиссия
-fail_reasonObjectПричина неуспеха проведения платежа
-infoObjectДополнительные параметры зависящие от категории услуг
## Дополнительные параметры (info) В теле ответа приходят дополнительные параметры зависящие от категории услуги, тип услуги записывается как ключ в объекте info
{% tabs %} {% tab title="parking" %} 
"info": {
    "parking": {
        "in_date": "2024-08-02T12:24:07+05:00",
        "left_free_time_minutes": 0,
        "sum": 118,
        "current_balance": -1,
        "zone":"1223-123",
        "coordinates": {
            "latitude":123.12,
            "longitude":123.0212
        },
        "duration":1,
        "phone":"77077777777"
    }
}
paramtypeDesc
in_datetimestampВремя начала парковки
left_free_time_minutesFloatКол-во оставшихся минут на выезд
sumFloatСтоимость парковки
current_balanceFloatТекущий баланс
zone stringЗона парковки
coordinatesobjectОбъект с координатами
├latitudefloat64Широта
├longitudefloat64Долгота
durationuintДлительность в секундах
phonestringНомер телефона
{% endtab %} {% tab title="finance" %} 
"info": {
    "finance": {
        "phone": "7777777777",
        "credit_days": 10,
        "contracts": [
            {
                "contract_id":"123456789",
                "contract_name":"Contract name",
                "contract_date": "03.01.2025 12:59:59",
                "client": "John Doe",
                "amount": 12.12,
                "total_amount": 12.12,
                "min": 1.23,
                "max": 12.12
            },
            {
                "contract_id":"987654321",
                "contract_name":"Name Contract",
                "contract_date": "17.02.2025 23:23:39",
                "client": "Doe John",
                "amount": 1292.64,
                "total_amount": 1292.64,
                "min": 100.21,
                "max": 1292.64
            }
        ]
    }
}
paramtypeDesc
phonestringНомер телефона
credit_daysuintКоличество дней для продления кредита
contractsarrayМассив контрактов
├contract_idstringID договора
├contract_namestringНазвание контракта
├contract_datestringДата контракта
├clientstringИмя клиента
├amountfloatСумма ежемесячного погашения
├total_amountfloatОстаток суммы по кредиту
├minfloatМинимальная сумма погашения
├maxfloatМаксимальная сумма погашения
{% endtab %} {% tab title="utilities" %} 
"info": {
    "utilities": {
        "customer": {
            "address": "г.Алматы, ул. Пушкина д. 10008 кв. 111112"
        },
        "invoice": {
            "invoice_id": "89878766212421",
            "period_date": "2025-01",
            "formed_date": "2025-01-11 21:39:00",
            "expire_date": "2025-01-21"
        },
        "service": [
            {
                "fix_sum": 1234.32,
                "service_id": "1123",
                "service_name": "Service Name",
                "measure": "тг/кВт.сағ.",
                "fix_count": 0,
                "prev_count": 500,
                "last_count": 570,
                "debt_sum": 0,
                "debt_info": "",
                "prev_count_date": "2024-12-31",
                "last_count_date": "2025-01-25",
                "sum": 0,
                "pay_sum": 0,
                "is_counter_service": true
            },
            {
                "fix_sum": 1234.32,
                "service_id": "1123",
                "service_name": "Service Name",
                "measure": "тг/кВт.сағ.",
                "fix_count": 0,
                "prev_count": 500,
                "last_count": 570,
                "debt_sum": 0,
                "debt_info": "",
                "prev_count_date": "2024-12-31",
                "last_count_date": "2025-01-25",
                "sum": 0,
                "pay_sum": 0,
                "is_counter_service": false
            }                
        ]
    }
}
paramtypeDesc
customerobjectОбъяект с информацией о клиенте
├addressstringАдрес клиента
invoiceobjectОбъект с данными о счете
├invoice_idstringУникальный идентификатор счета
├period_datestringПериод счета
├formed_datestringДата формирования счета
├expire_datestringДата окончания срока оплаты
servicearrayМассив сервисов
├fix_sumfloatФиксированная сумма к оплате
├service_idstringИдентификатор услуги
├service_namestringНазвание сервиса
├measurestringЕдиница измерения услуги
├fix_countfloatФиксированное показание счетчика
├prev_countfloatПредыдущие показания счетчика
├last_countfloatПоследние показания счетчика
├debt_sumfloatСумма задолженности
├debt_infostringИнформация о задолженности
├prev_count_datestringДата предыдущих показаний
├last_count_datestringДата текущих показаний
├sumfloatОбщая сумма
├pay_sumfloatСумма которую платит клиент
├is_counter_serviceboolЯвляется ли услуга счетчиком (true – да, false – нет)
{% endtab %} {% tab title="confirmation" %} ```json "info": { "confirmation": { "code": "967056", "expiration_date": "2025-09-09T13:22:18Z" //Дата и Время в стандарте RFC 3339 } } ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="200: OK Пример успешного ответа" %} ```json { "status": true, "message": "Success", "status_code": 0, "result": { "error_code": 0, "message": "This account is active", "account_status": 1, "info": { "parking": { "in_date": "2025-01-06T16:32:00Z", "left_free_time_minutes": 0, "sum": 1137, "current_balance": -1, "coordinates": { "latitude": 0, "longitude": 0 }, "zone": "", "duration": 0, "phone": "" } }, "fail_reason": {}, "amount": 1138, "upper_commission": 122 } } ``` {% endtab %} {% tab title="200: OK Пример неуспешного ответа" %} ```json { "status": true, "status_code": 0, "message": "Success", "result":{ "error_code" : 0, "message": "This account is inactive", "account_status": 0, "additional_data": {}, "fail_reason": { "code": 100, "message": "Unknown reason, clarification required" } } } ``` {% endtab %} {% endtabs %} #### Примеры ответов об ошибках *до* внесения изменений {% tabs %} {% tab title="404 Not Found" %} ```json { "status": false, "status_code": 1407, "message": "Cache: item not found", "result": {} } ``` {% endtab %} {% tab title="400 Bad Request" %} ```json { "status": false, "status_code": 1014, "message": "Invalid signature", "result": {} } ``` {% endtab %} {% endtabs %} #### Примеры ответов об ошибках *после* внесения изменений {% tabs %} {% tab title="200 OK: Ожидаемая ошибка" %} ```json { "status": true, "status_code": 0, "message": "Success", "result": { "error_code": 1407, "message": "Cache: item not found", "data": null, } } ``` {% endtab %} {% tab title="400 Bad Request: Неожидаемая ошибка" %} ```json { "status": false, "status_code": 1014, "message": "Invalid signature", "result": {} } ``` {% endtab %} {% endtabs %} Проверка аккаунта {% tabs %} {% tab title="Golang" %} {% code fullWidth="true" %} ```go package main import ( "bytes" "crypto/sha256" "encoding/base64" "encoding/hex" "encoding/json" "io/ioutil" "log" "net/http" "sort" ) const ( // agent - код витрины на стороне Tarlan agent = "agent" // serviceCode - идентификатор услуги витрины serviceCode = "service" // project - код проекта на стороне Tarlan project = "project" // requestURL - URL для отправки запроса requestURL = "https://agwsapi.tarlanpayments.kz/showcase-gateway/api/v1/user/check" // secretKey - secret проекта secretKey = "12345" ) // Response представляет ответ от сервера type Response struct { Status bool `json:"status"` StatusCode uint32 `json:"status_code"` Message string `json:"message"` Result Result `json:"result"` } type Result struct { ErrorCode int `json:"error_code"` Message string `json:"message"` AccountStatus uint64 `json:"account_status"` } // Body представляет структуру запроса type Body struct { Agent string `json:"agent"` UserName string `json:"username"` Project string `json:"project"` ServiseCode string `json:"service_code"` } // MakeSign генерирует подпись для HTTP-запроса func MakeSign(body Body, secretKey string) (string, error) { // Конвертируем структуру в map для сортировки dataMap := make(map[string]interface{}) jsonData, _ := json.Marshal(body) json.Unmarshal(jsonData, &dataMap) // Удаляем "additional_data", если нужно delete(dataMap, "additional_data") // Сортируем ключи по алфавиту keys := make([]string, 0, len(dataMap)) for key := range dataMap { keys = append(keys, key) } sort.Strings(keys) // Создаем отсортированный JSON sortedData := make(map[string]interface{}) for _, key := range keys { sortedData[key] = dataMap[key] } // Преобразуем отсортированные данные в JSON sortedJson, err := json.Marshal(sortedData) if err != nil { return "", err } // Кодируем JSON в base64 base64EncodedData := base64.StdEncoding.EncodeToString(sortedJson) // Конкатенируем base64-данные с секретом dataToSign := base64EncodedData + secretKey // Хешируем SHA-256 sha256Hash := sha256.Sum256([]byte(dataToSign)) sign := hex.EncodeToString(sha256Hash[:]) return sign, nil } // CheckLogin отправляет POST-запрос и обрабатывает ответ func CheckLogin(body Body, url, signature string) (string, error) { // Конвертируем структуру в JSON для отправки jsonData, err := json.Marshal(body) if err != nil { return "", err } // Создаем и отправляем POST-запрос req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData)) if err != nil { return "", err } // Устанавливаем подпись запроса req.Header.Set("X-Signature", signature) req.Header.Set("Content-Type", "application/json") client := &http.Client{} resp, err := client.Do(req) if err != nil { return "", err } defer resp.Body.Close() // Чтение и обработка ответа bodyBytes, err := ioutil.ReadAll(resp.Body) if err != nil { return "", err } jsonResponse := string(bodyBytes) // Структура для парсинга ответа var response Response err = json.Unmarshal([]byte(jsonResponse), &response) if err != nil { return "", err } log.Printf("Status-%v, %v", resp.StatusCode, jsonResponse) // Определение поля message var message string // Извлечение ответа if resp.StatusCode == http.StatusOK { if response.StatusCode == 0 { message = response.Result.Message + " " + body.UserName } else { message = response.Message } } if resp.StatusCode != http.StatusOK { message = response.Message } // Вывод ответа и результата return message, nil } func main() { // login пользователя var login string = "login" // requestBody тело запроса requestBody := Body{ Agent: agent, UserName: login, Project: project, ServiseCode: serviceCode, } // Генерация заголовка sign, err := MakeSign(requestBody, secretKey) if err != nil { log.Println("Error generating signature: ", err) return } // Отправка запроса Message, err := CheckLogin(requestBody, requestURL, sign) if err != nil { log.Panic("Error sending request ", err) return } // Вывод message из лога if Message != "" { log.Println(Message) } } ``` {% endcode %} {% endtab %} {% endtabs %} # Проведение платежа `POST` `https://agwsapi.tarlanpayments.kz/showcase-gateway/api/v1/action/cash-in` **Headers** | Name | Value | | ------------ | -------------------------------------------------------------- | | Content-Type | `application/json` | | X-Signature | [Авторизационный хэш](/platezhnyi-shlyuz/formirovanie-podpisi) | **Body**
NameTypeDescription
username*StringИдентификатор пользователя
amount*FloatСумма транзакции
agent*StringКод витрины в системе Tarlan
project*StringКод Проекта присваиваемый Tarlan-ом
service_code*StringИдентификатор услуги на стороне витрины
external_id*StringУникальный идентификатор платежа на стороне витрины
datetime*StringВремя инициации платежа в системе витрины. Формат ISO 8601 Current Timestamp
callback_urlStringURL на который будет отправлен callback запрос
**Response**
ПараметрыФорматОписание
statusboolСтатус обработки запроса
status_codeuintКод ошибки
messagestringОписание ошибки
resultObjectРезультат запроса, в котором содержится информация
-error_codeuintКод ошибки
-messageStringОписание ошибки
-dataObjectИнформация о данных
--status_codeStringКод статуса транзакции
--status_messageStringОписание статуса транзакции
--usernameStringИдентификатор пользователя
--amountFloatЗачисленная сумма
--datetimeStringВремя инициации платежа в системе витрины. Формат ISO 8601 Current Timestamp
--projectStringКод Проекта присваиваемый Tarlan-ом
--service_codeStringИдентификатор услуги на стороне витрины
--external_idStringИдентификатор платежа на стороне витрины
--fail_reasonObjectПричина неуспеха проведения платежа
---codeIntКод причины отклонения операции
---messageStringОписание причины отклонения операции
--infoObjectДополнительные параметры зависящие от категории услуг
{% tabs %} {% tab title="200: OK Пример успешного ответа" %} 
{
    "status": true,
    "message": "Success",
    "status_code": 0,
    "result": {
        "error_code": 0,
        "message": "",
        "data": {
            "external_id": "111111111111111",
            "project": "project-1",
            "service_code": "service_code1",
            "username": "415304197",
            "amount": 9.56,
            "datetime": "2025-01-01T01:01:01+05:00",
            "status_code": "2",
            "status_message": "Transaction successfully processed"
        },
        "fail_reason": {},
        "info": {
            "confirmation": {
                "code": "967056",
                "expiration_date": "2025-09-09T13:22:18Z"
            }
        }
    }
}
{% endtab %} {% tab title="200: OK Пример временного статуса" %} ```json { "status": true, "message": "Success", "status_code": 0, "result": { "error_code": 0, "message": "", "data": { "external_id": "111111111111111", "project": "project-1", "service_code": "service_code1", "username": "415304197", "amount": 9.56, "datetime": "1747393302", "status_code": "1", "status_message": "Transaction created" }, "fail_reason": {}, "info": { "confirmation": { "code": "967056", "expiration_date": "2025-09-09T13:22:18Z" } } } } ``` {% endtab %} {% tab title="200 OK: Ожидаемая ошибка" %} ```json { "status": true, "status_code": 0, "message": "Success", "result" : { "error_code" : 1042, "message": "Duplicate external_id", "data": null, "additional_data":null } } ``` {% endtab %} {% tab title="400 Bad Request: Неожидаемая ошибка" %} ```json { "status": false, "status_code": 1014, "message": "Invalid signature", "result": {} } ``` {% endtab %} {% endtabs %} Проведение платежа {% tabs %} {% tab title="Golang" %} ```go package main import ( "bytes" "crypto/sha256" "encoding/base64" "encoding/hex" "encoding/json" "io/ioutil" "log" "net/http" "sort" "time" ) const ( // agent - код витрины на стороне Tarlan agent = "agent" // serviceCode - идентификатор услуги витрины serviceCode = "service" // project - код проекта на стороне Tarlan project = "project" // requestURL - URL для отправки запроса requestURL = "https://agwsapi.tarlanpayments.kz/showcase-gateway/api/v1/action/cash-in" // secretKey - secret проекта secretKey = "12345" ) // Response представляет ответ от сервера type Response struct { Status bool `json:"status"` StatusCode uint32 `json:"status_code"` Message string `json:"message"` Result Result `json:"result"` } type Result struct { ErrorCode uint32 `json:"error_code"` Message string `json:"message"` Data Data `json:"data"` } type Data struct { StatusCode string `json:"status_code"` StatusMessage string `json:"status_message"` Username string `json:"username"` Amount float64 `json:"amount"` Datetime time.Time `json:"datetime"` Project string `json:"project"` ServiceCode string `json:"service_code"` ExternalID string `json:"external_id"` } // Body представляет структуру запроса type Body struct { UserName string `json:"username"` Agent string `json:"agent"` Project string `json:"project"` ServiseCode string `json:"service_code"` Amount float64 `json:"amount"` ExternalID string `json:"external_id"` DateTime string `json:"datetime"` CallBackUrl string 'json:"callback_url,omitempty"` } // MakeSign генерирует подпись для HTTP-запроса func MakeSign(body Body, secretKey string) (string, error) { // Конвертируем структуру в map для сортировки dataMap := make(map[string]interface{}) jsonData, _ := json.Marshal(body) err := json.Unmarshal(jsonData, &dataMap) if err != nil { return "", err } // Сортируем ключи по алфавиту keys := make([]string, 0, len(dataMap)) for key := range dataMap { keys = append(keys, key) } sort.Strings(keys) // Создаем отсортированный JSON sortedData := make(map[string]interface{}) for _, key := range keys { sortedData[key] = dataMap[key] } // Преобразуем отсортированные данные в JSON sortedJson, err := json.Marshal(sortedData) if err != nil { return "", err } // Кодируем JSON в base64 base64EncodedData := base64.StdEncoding.EncodeToString(sortedJson) // Конкатенируем base64-данные с секретом dataToSign := base64EncodedData + secretKey // Хешируем SHA-256 sha256Hash := sha256.Sum256([]byte(dataToSign)) sign := hex.EncodeToString(sha256Hash[:]) return sign, nil } // MakeCashIn отправляет POST-запрос и обрабатывает ответ func MakeCashIn(body Body, url, signature string) (string, error) { // Конвертируем структуру в JSON для отправки jsonData, err := json.Marshal(body) if err != nil { return "", err } // Создаем и отправляем POST-запрос req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData)) if err != nil { return "", err } // Устанавливаем подпись запроса req.Header.Set("X-Signature", signature) req.Header.Set("Content-Type", "application/json") client := &http.Client{} resp, err := client.Do(req) if err != nil { return "", err } defer resp.Body.Close() // Чтение и обработка ответа bodyBytes, err := ioutil.ReadAll(resp.Body) if err != nil { return "", err } jsonResponse := string(bodyBytes) // Структура для парсинга ответа var response Response err = json.Unmarshal([]byte(jsonResponse), &response) if err != nil { return "", err } log.Printf("Status-%v, %v", resp.StatusCode, jsonResponse) // Определение поля message var message string // Извлечение ответа if resp.StatusCode == http.StatusOK { if response.StatusCode == 0 && response.Result.ErrorCode == 0 { message = response.Result.Data.StatusMessage + ", reference " + response.Result.Data.ExternalID } else { message = response.Result.Message } } if resp.StatusCode != http.StatusOK { message = response.Message } // Вывод ответа и результата return message, nil } func main() { var ( // login - логин пользователя login string = "login" // externalID - номер заказа externalID string = "reference" // amount - сумма платежа amount float64 = 10.01 ) // Тело запроса requestBody := Body{ UserName: login, Agent: agent, Project: project, ServiseCode: serviceCode, Amount: amount, ExternalID: externalID, DateTime: time.Now().Format(time.RFC3339), } // Генерация заголовка sign, err := MakeSign(requestBody, secretKey) if err != nil { log.Println("Error generating signature:", err) return } // Отправка запроса Message, err := MakeCashIn(requestBody, requestURL, sign) if err != nil { log.Panic("Error sending request", err) return } // Вывод message из лога if Message != "" { log.Println(Message) } } ``` {% endtab %} {% endtabs %} # Проверка статуса пополнения {% hint style="danger" %} **ВНИМАНИЕ: Новый формат ответа для ошибок** В ближайшее время в нашей системе ошибки будут разделены на **ожидаемые** и **неожидаемые**. Это приведет к изменению формата JSON-ответа в зависимости от типа ошибки. Пожалуйста, ознакомьтесь с изменениями на странице [**Коды Ошибок**](/agws/kody-oshibok). Изменения будут применены ко всем API в системе AGWS, за исключением методов «[Проведение платежа](/agws/provedenie-platezha)». Нажмите [здесь](#primery-otvetov-ob-oshibkakh-do-vneseniya-izmenenii), чтобы просмотреть старые и новые ответы об ошибках JSON. Обратите внимание на это обновление и убедитесь, что ваша система готова к изменениям, если это необходимо. {% endhint %} `POST` `https://agwsapi.tarlanpayments.kz/showcase-gateway/api/v1/action/status` **Headers** | Name | Value | | ------------ | -------------------------------------------------------------- | | Content-Type | `application/json` | | X-Signature | [Авторизационный хэш](/platezhnyi-shlyuz/formirovanie-podpisi) | **Body**
NameTypeDescription
agent*StringКод витрины в системе Tarlanpayments
project*StringКод Проекта присваиваемый Tarlanpayments
service_code*StringИдентификатор услуги на стороне витрины
external_id*StringИдентификатор платежа на стороне витрины
**Response**
NameTypeDescription
statusboolСтатус обработки запроса
status_codeuintКод ошибки
messagestringОписание ошибки
resultObjectРезультат запроса, в котором содержится информация
-error_codeuintКод ошибки
-messageStringОписание ошибки
-dataObjectИнформация о данных
--status_codeStringКод статуса транзакции
--status_messageStringОписание статуса транзакции
--usernameStringИдентификатор пользователя
--amountFloatЗачисленная сумма
--fail_reasonObjectПоле содержащее причину неуспеха
--datetimeStringВремя инициации платежа в системе витрины.Формат ISO 8601 Current Timestamp
--projectStringКод Проекта присваиваемый Tarlan-ом
--service_codeStringИдентификатор услуги на стороне витрины
--external_idStringИдентификатор платежа на стороне витрины
{% tabs %} {% tab title="200: OK Пример успешного ответа" %} ```json { "status": true, "status_code": 0, "message": "Success", "result":{ "error_code" : 0, "message": "", "data": { "status_code": "4", "status_message": "Transaction was failed", "username": "989898", "amount": 100, "datetime": "2022-12-01T15:45:00Z", "project": "mobile", "service_code": "201106", "external_id": "200001", }, "fail_reason": { "code": 100, "message": "Unknown reason, clarification required" } } ``` {% endtab %} {% endtabs %} #### Примеры ответов об ошибках *до* внесения изменений {% tabs %} {% tab title="404 Not Found" %} 
{
    "status": false,
    "status_code": 1041,
    "message": "Order not found",
    "result": {}
}
{% endtab %} {% tab title="400 Bad Request" %} ```json { "status": false, "status_code": 1014, "message": "Invalid signature", "result": {} } ``` {% endtab %} {% endtabs %} #### Примеры ответов об ошибках *после* внесения изменений {% tabs %} {% tab title="200: OK Ожидаемая ошибка" %} 
{
    "status": true,
    "status_code": 0,
    "message": "Success",
    "result": {
        "error_code" : 1041,
        "message": "Order not found",
        "data": null
    }
}
{% endtab %} {% tab title="400 Bad Request: Неожидаемая ошибка" %} ```json { "status": false, "status_code": 1014, "message": "Invalid signature", "result": {} } ``` {% endtab %} {% endtabs %} Проверка статуса пополнения {% tabs %} {% tab title="Golang" %} ```go package main import ( "bytes" "crypto/sha256" "encoding/base64" "encoding/hex" "encoding/json" "io/ioutil" "log" "net/http" "sort" "time" ) const ( // agent - код витрины на стороне Tarlan agent = "agent" // serviceCode - идентификатор услуги витрины serviceCode = "service" // project - код проекта на стороне Tarlan project = "project" // url - URL для отправки запроса url = "https://agwsapi.tarlanpayments.kz/showcase-gateway/api/v1/action/status" // secret -secret проекта secret = "12345" ) // Response представляет тело ответа от сервера type Response struct { Status bool `json:"status"` StatusCode uint32 `json:"status_code"` Message string `json:"message"` Result Result `json:"result"` } type Result struct { ErrorCode uint32 `json:"error_code"` Message string `json:"message"` Data Data `json:"data"` } type Data struct { StatusCode string `json:"status_code"` StatusMessage string `json:"status_message"` Username string `json:"username"` Amount float64 `json:"amount"` Datetime time.Time `json:"datetime"` Project string `json:"project"` ServiceCode string `json:"service_code"` ExternalID string `json:"external_id"` } // Body представляет структуру запроса type Body struct { Agent string `json:"agent"` Project string `json:"project"` ServiseCode string `json:"service_code"` ExternalID string `json:"external_id"` } // MakeSign генерирует подпись для HTTP-запроса func MakeSign(body Body, secretKey string) (string, error) { // Конвертируем структуру в map для сортировки dataMap := make(map[string]interface{}) jsonData, _ := json.Marshal(body) err := json.Unmarshal(jsonData, &dataMap) if err != nil { return "", err } // Сортируем ключи по алфавиту keys := make([]string, 0, len(dataMap)) for key := range dataMap { keys = append(keys, key) } sort.Strings(keys) // Создаем отсортированный JSON sortedData := make(map[string]interface{}) for _, key := range keys { sortedData[key] = dataMap[key] } // Преобразуем отсортированные данные в JSON sortedJson, err := json.Marshal(sortedData) if err != nil { return "", err } // Кодируем JSON в base64 base64EncodedData := base64.StdEncoding.EncodeToString(sortedJson) // Конкатенируем base64-данные с секретом dataToSign := base64EncodedData + secretKey // Хешируем SHA-256 sha256Hash := sha256.Sum256([]byte(dataToSign)) sign := hex.EncodeToString(sha256Hash[:]) return sign, nil } // CheckStatus отправляет POST-запрос и обрабатывает ответ func CheckStatus(body Body, url, signature string) (string, error) { // Конвертируем структуру в JSON для отправки jsonData, err := json.Marshal(body) if err != nil { return "", err } // Создаем и отправляем POST-запрос req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData)) if err != nil { return "", err } // Устанавливаем подпись запроса req.Header.Set("X-Signature", signature) req.Header.Set("Content-Type", "application/json") client := &http.Client{} resp, err := client.Do(req) if err != nil { return "", err } defer resp.Body.Close() // Чтение и обработка ответа bodyBytes, err := ioutil.ReadAll(resp.Body) if err != nil { return "", err } jsonResponse := string(bodyBytes) // Структура для парсинга ответа var response Response err = json.Unmarshal([]byte(jsonResponse), &response) if err != nil { return "", err } log.Printf("Status-%v, %v", resp.StatusCode, jsonResponse) // Определение поля message var message string // Извлечение ответа if resp.StatusCode == http.StatusOK { if response.StatusCode == 0 && response.Result.ErrorCode == 0 { message = response.Result.Data.StatusMessage + ", reference " + response.Result.Data.ExternalID } else { message = response.Result.Message } } else { message = response.Message } // Вывод ответа и результата return message, nil } func main() { // URL Запроса RequestURL := url // Secret Проекта SecretKey := secret // externalID - номер заказа var externalID string = "reference" // Тело запроса requestBody := Body{ Agent: agent, Project: project, ServiseCode: serviceCode, ExternalID: externalID, } // Генерация заголовка sign, err := MakeSign(requestBody, SecretKey) if err != nil { log.Println("Error generating signature:", err) return } // Отправка запроса Message, err := CheckStatus(requestBody, RequestURL, sign) if err != nil { log.Panic("Error sending request", err) return } // Вывод message из лога if Message != "" { log.Println(Message) } } ``` {% endtab %} {% endtabs %} # Проверка остатка баланса на счету {% hint style="danger" %} В ближайшее время в нашей системе ошибки будут разделены на **ожидаемые** и **неожидаемые**. Это приведет к изменению формата JSON-ответа в зависимости от типа ошибки. Пожалуйста, ознакомьтесь с изменениями на странице [**Коды Ошибок**](/agws/kody-oshibok). Изменения будут применены ко всем API в системе AGWS, за исключением методов «[Проведение платежа](/agws/provedenie-platezha)». Нажмите [здесь](#primery-otvetov-ob-oshibkakh-do-vneseniya-izmenenii), чтобы просмотреть старые и новые ответы об ошибках JSON. Обратите внимание на это обновление и убедитесь, что ваша система готова к изменениям, если это необходимо. {% endhint %} `POST` `https://agwsapi.tarlanpayments.kz/showcase-gateway/api/v1/showcase/balance` **Headers** | Name | Value | | ------------ | -------------------------------------------------------------- | | Content-Type | `application/json` | | X-Signature | [Авторизационный хэш](/platezhnyi-shlyuz/formirovanie-podpisi) | **Body** | Name | Type | Description | | --------------------------------------- | ------ | ---------------------------- | | agent\* | String | Код витрины в системе Tarlan | **Response**
NameTypeDescription
statusboolСтатус обработки запроса
status_codeuintКод ошибки
messagestringОписание ошибки
resultObjectРезультат запроса, в котором содержится информация
-showcase_codeStringКод витрины в системе Tarlan
-balancefloatТекущий баланс
{% tabs %} {% tab title="200: OK Пример успешного ответа" %} ```json { "status": true, "status_code": 0, "message": "Success", "result": { "showcase_code": "daw", "balance": 0 } } ``` {% endtab %} {% endtabs %} #### Примеры ответов об ошибках *до* внесения изменений {% tabs %} {% tab title="404 Not Found" %} ```json { "status": false, "status_code": 8015, "message": "account doesn't exist", "result": {} } ``` {% endtab %} {% tab title="400 Bad Request" %} ```json { "status": false, "status_code": 1014, "message": "Invalid signature", "result": {} } ``` {% endtab %} {% endtabs %} #### Примеры ответов об ошибках *после* внесения изменений {% tabs %} {% tab title="200 OK: Ожидаемая ошибка" %} ```json { "status": true, "status_code": 0, "message": "Success", "result": { "error_code": 8015, "message": "account doesn't exist", "data": null } } ``` {% endtab %} {% tab title="400 Bad Request: Неожидаемая ошибка" %} ```json { "status": false, "status_code": 1014, "message": "Invalid signature", "result": {} } ``` {% endtab %} {% endtabs %} Проверка баланса {% tabs %} {% tab title="Go" %} ```go package main import ( "bytes" "crypto/sha256" "encoding/base64" "encoding/hex" "encoding/json" "io/ioutil" "log" "net/http" "sort" "strconv" ) const ( // agent - код витрины на стороне Tarlan agent = "agent" // url - URL для отправки запроса url = "https://agwsapi.tarlanpayments.kz/showcase-gateway/api/v1/showcase/balance" // secret -secret проекта secret = "12345" ) // Response представляет ответ от сервера type Response struct { Status bool `json:"status"` StatusCode int `json:"status_code"` Message string `json:"message"` Result Result `json:"result"` } type Result struct { ShowcaseCode string `json:"showcase_code"` Message string `json:"message"` Balance float64 `json:"balance"` } // Body представляет структуру запроса type Body struct { Agent string `json:"agent"` } // MakeSign генерирует подпись для HTTP-запроса func MakeSign(body Body, secretKey string) (string, error) { // Конвертируем структуру в map для сортировки dataMap := make(map[string]interface{}) jsonData, _ := json.Marshal(body) json.Unmarshal(jsonData, &dataMap) // Сортируем ключи по алфавиту keys := make([]string, 0, len(dataMap)) for key := range dataMap { keys = append(keys, key) } sort.Strings(keys) // Создаем отсортированный JSON sortedData := make(map[string]interface{}) for _, key := range keys { sortedData[key] = dataMap[key] } // Преобразуем отсортированные данные в JSON sortedJson, err := json.Marshal(sortedData) if err != nil { return "", err } // Кодируем JSON в base64 base64EncodedData := base64.StdEncoding.EncodeToString(sortedJson) // Конкатенируем base64-данные с секретом dataToSign := base64EncodedData + secretKey // Хешируем SHA-256 sha256Hash := sha256.Sum256([]byte(dataToSign)) sign := hex.EncodeToString(sha256Hash[:]) return sign, nil } // CheckBalance отправляет POST-запрос и обрабатывает ответ func CheckBalance(body Body, url, signature string) (string, error) { // Конвертируем структуру в JSON для отправки jsonData, err := json.Marshal(body) if err != nil { return "", err } // Создаем и отправляем POST-запрос req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData)) if err != nil { return "", err } // Устанавливаем подпись запроса req.Header.Set("X-Signature", signature) req.Header.Set("Content-Type", "application/json") client := &http.Client{} resp, err := client.Do(req) if err != nil { return "", err } defer resp.Body.Close() // Чтение и обработка ответа bodyBytes, err := ioutil.ReadAll(resp.Body) if err != nil { return "", err } jsonResponse := string(bodyBytes) // Структура для парсинга ответа var response Response err = json.Unmarshal([]byte(jsonResponse), &response) if err != nil { return "", err } log.Printf("Status-%v, %v", resp.StatusCode, jsonResponse) // Определение поля message var message string // Извлечение ответа if resp.StatusCode == http.StatusOK { if response.StatusCode == 0 { balance := strconv.FormatFloat(response.Result.Balance, 'f', -1, 64) message = "Showcase " + response.Result.ShowcaseCode + " balance is " + balance } else { message = response.Result.Message } } else { message = response.Message } // Вывод ответа и результата return message, nil } func main() { // URL Запроса RequestURL := url // Secret Проекта SecretKey := secret // Тело запроса requestBody := Body{ Agent: agent, } // Генерация заголовка sign, err := MakeSign(requestBody, SecretKey) if err != nil { log.Println("Error generating signature:", err) return } // Отправка запроса Message, err := CheckBalance(requestBody, RequestURL, sign) if err != nil { log.Panic("Error sending request", err) return } // Вывод message из лога if Message != "" { log.Println(Message) } } ``` {% endtab %} {% endtabs %} # Подтверждение списания средств {% hint style="danger" %} **ВНИМАНИЕ: Новый формат ответа для ошибок** В ближайшее время в нашей системе ошибки будут разделены на **ожидаемые** и **неожидаемые**. Это приведет к изменению формата JSON-ответа в зависимости от типа ошибки. Пожалуйста, ознакомьтесь с изменениями на странице [**Коды Ошибок**](/agws/kody-oshibok). Изменения будут применены ко всем API в системе AGWS, за исключением методов «[Проведение платежа](/agws/provedenie-platezha)». Нажмите [здесь](#primery-otvetov-ob-oshibkakh-do-vneseniya-izmenenii), чтобы просмотреть старые и новые ответы об ошибках JSON. Обратите внимание на это обновление и убедитесь, что ваша система готова к изменениям, если это необходимо. {% endhint %} Для некоторых услуг необходимо подтверждать списание используя дополнительные атрибуты например отп-код. `POST` `https://agwsapi.tarlanpayments.kz/showcase-gateway/api/v1/action/confirm/invoice` **Headers** | Name | Value | | ------------ | -------------------------------------------------------------- | | Content-Type | `application/json` | | X-Signature | [Авторизационный хэш](/platezhnyi-shlyuz/formirovanie-podpisi) | **Body**
NameTypeDescription
agent*StringКод витрины в системе Tarlanpayments
confirm_codeStringКод подтверждения платежа
external_id*StringИдентификатор платежа на стороне витрины
**Response**
NameTypeDescription
statusboolСтатус обработки запроса
status_codeuintКод ошибки
messagestringОисание ошибки
resultObjectОбъект хранящий информацию о платеже
-is_successStringФлаг успешности платежа
-transaction_status_idStringСтатус транзакции
-fail_reasonObjectПоле содержащее причину неуспеха
-external_idStringИдентификатор платежа на стороне витрины
-otp_statusboolФлаг успешности проверки otp
{% tabs %} {% tab title="200: OK Пример успешного ответа" %} ```json { "status": true, "status_code": 0, "message": "Success", "result": { "is_success": true, "transaction_status_id": "4", "external_id": "200001", "message": "", "otp_status": false, "fail_reason": { "code": 402, "message": "Incorrect confirmation code" } } } ``` {% endtab %} {% endtabs %} #### Примеры ответов об ошибках *до* внесения изменений {% tabs %} {% tab title="400 Bad Request" %} ```json { "status": false, "status_code": 1041, "message": "Order not found", "result": {} } ``` {% endtab %} {% tab title="400 Bad Request" %} ```json { "status": false, "status_code": 1014, "message": "Invalid signature", "result": {} } ``` {% endtab %} {% endtabs %} #### Примеры ответов об ошибках *после* внесения изменений {% tabs %} {% tab title="200 OK: Ожидаемая ошибка" %} ```json { "status": true, "status_code": 0, "message": "Success", "result": { "error_code": 1041, "message": "Order not found", "data": null } } ``` {% endtab %} {% tab title="400 Bad Request: Неожидаемая ошибка" %} ```json { "status": false, "status_code": 1014, "message": "Invalid signature", "result": {} } ``` {% endtab %} {% endtabs %} ```bash curl --location 'https://agwsapi.tarlanpayments.kz/showcase-gateway/api/v1/action/confirm/invoice' \ --header 'Content-Type: application/json' \ --data '{ "agent": "test_agent", "confirm_code": "104000", "external_id": "externa312" }' ``` # Создание ссылки на оплату {% hint style="danger" %} **ВНИМАНИЕ: Новый формат ответа для ошибок** В ближайшее время в нашей системе ошибки будут разделены на **ожидаемые** и **неожидаемые**. Это приведет к изменению формата JSON-ответа в зависимости от типа ошибки. Пожалуйста, ознакомьтесь с изменениями на странице [**Коды Ошибок**](/agws/kody-oshibok). Изменения будут применены ко всем API в системе AGWS, за исключением методов «[Проведение платежа](/agws/provedenie-platezha)». Нажмите [здесь](#primery-otvetov-ob-oshibkakh-do-vneseniya-izmenenii), чтобы просмотреть старые и новые ответы об ошибках JSON. Обратите внимание на это обновление и убедитесь, что ваша система готова к изменениям, если это необходимо. {% endhint %} `POST` `https://agwsapi.tarlanpayments.kz/showcase-gateway/api/v1/action/link` **Headers** | Name | Value | | ------------ | -------------------------------------------------------------- | | Content-Type | `application/json` | | X-Signature | [Авторизационный хэш](/platezhnyi-shlyuz/formirovanie-podpisi) | **Body**
NameTypeDescription
agent*StringКод витрины в системе Tarlanpayments
username*StringИдентификатор пользователя
amount*IntegerСумма транзакции
service*StringНазвание услуги
return_urlStringСсылка для перехода после оплаты
refer_host*StringДомен с которого производится оплата
**Response** {% tabs %} {% tab title="200: OK Пример успешного ответа" %} ```json { "status": true, "message": "Success", "status_code": 0, "result": { "code": 0, "redirect_url": "https://kaspi.kz/pay/quickpayment?quick_pay_id=Betssonkzad1e50a5-6afd-481e-8e14-37487734ed292517:52:00", "message": "Успешно обработано", "qr_code_image": "" } } ``` {% endtab %} {% endtabs %} #### Примеры ответов об ошибках *до* внесения изменений {% tabs %} {% tab title="404 Not Found" %} ```json { "status": false, "status_code": 9718, "message": "provider not found", "result": {} } ``` {% endtab %} {% tab title="400 Bad Request" %} ```json { "status": false, "status_code": 1014, "message": "Invalid signature", "result": {} } ``` {% endtab %} {% endtabs %} #### Примеры ответов об ошибках *после* внесения изменений {% tabs %} {% tab title="200 OK: Ожидаемая ошибка" %} ```json { "status": true, "status_code": 0, "message": "Success", "result": { "error_code": 1881, "code": -1, "message": "provider doesn't exists", "redirect_url": "", "qr_code_image": "" } } ``` {% endtab %} {% tab title="400 Bad Request: Неожидаемая ошибка" %} ```json { "status": false, "status_code": 1014, "message": "Invalid signature", "result": {} } ``` {% endtab %} {% endtabs %} ```bash curl --location 'https://agwsapi.tarlanpayments.kz/showcase-gateway/api/v1/action/link' \ --header 'X-Signature: qfqer1231' \ --header 'Content-Type: application/json' \ --data '{ "agent": "test1", "user_id": "e41e6e7b-a0b9-46cf-ac10-bb8333fd6391", "amount": 10000, "service": "service1", "return_url": "https://www.youresite.com/", "refer_host": "site.kz" }' ``` # Информация по услугам Получение дополнительной информации о услуге #### Получение дополнительной информации о услуге `GET` `https://agwsapi.tarlanpayments.kz/showcase-gateway/api/v1/info/service/{service_group}` #### Получение дополнительной информации о пользователях `GET` `https://agwsapi.tarlanpayments.kz/showcase-gateway/api/v1/info/user/{service_group}` **Headers** | Name | Value | | ------------ | -------------------------------------------------------------- | | Content-Type | `application/json` | | X-Signature | [Авторизационный хэш](/platezhnyi-shlyuz/formirovanie-podpisi) | **Path params**
NameTypeDescription
service_group*StringГруппа услуг (Влияет на тело ответа в API)
**Query params**
NameTypeDescription
service_code*StringНазвание услуги
project*StringКод Проекта присваиваемый Tarlan-ом
agent*StringКод витрины в системе Tarlanpayments
**Response** [информации о услуге](#poluchenie-dopolnitelnoi-informacii-o-usluge) {% tabs %} {% tab title="200: OK service\_group=parking" %} 
{
    "status": true,
    "message": "Success",
    "status_code": 0,
    "result": {
        "error_code": 0,
        "message": "success",
        "data": [
            {
                "location": [
                    {
                        "lat": 10.0,
                        "lon": 10.0
                    }
                ],
                "center": {
                    "lat": 10.0,
                    "lon": 10.0
                },
                "description": "",
                "type": "",
                "amount": 10.0,
                "name": "",
                "id": "",
                "date": "2024-10-21T08:43:33Z", // Формат ISO 8601 Current Timestamp
                "active": true
            }
        ]
    }
}
{% endtab %} {% tab title="200 OK: Не может быть пополнен" %} ```json { "status": true, "message": "Success", "status_code": 0, "result": { "error_code" : 1041, "message": "Order not found", "data": null, "additional_data": null } } ``` {% endtab %} {% tab title="400 Bad Request" %} ```json { "status": false, "status_code": 1014, "message": "Invalid signature", "result": {} } ``` {% endtab %} {% endtabs %} **Response** [информации о пользователях](#poluchenie-dopolnitelnoi-informacii-o-polzovatelyakh) {% tabs %} {% tab title="200: OK service\_group=parking" %} ```json { "status": true, "message": "Success", "status_code": 0, "result": { "error_code": 5202, "message": "success", "data": [ { "id": "123", "username": "123@gmail.com", "amount": 10.0, "date": "2024-10-21T08:43:33Z" //Формат ISO 8601 Current Timestamp } ] } } ``` {% endtab %} {% endtabs %} # Получение информации о юзере Проверка состояния аккаунта и получение информации о юзере `GET``https://agwsapi.tarlanpayments.kz/showcase-gateway/api/v1/service/{service_group}/users/{login}` **Headers** | Name | Value | | ------------ | -------------------------------------------------------------- | | Content-Type | `application/json` | | X-Signature | [Авторизационный хэш](/platezhnyi-shlyuz/formirovanie-podpisi) | **Path params**
NameTypeDescription
service_group*StringГруппа услуг (Влияет на тело ответа в API)
login*String Идентификатор пользователя
**Query params**
NameTypeDescription
service_code*StringНазвание услуги
project*StringКод Проекта присваиваемый Tarlan-ом
agent*StringКод витрины в системе Tarlan
identifierStringДополнительный параметр, передаваемый в зависимости от услуги
**Response** {% tabs %} {% tab title="200: OK Успешный ответ" %} ```json { "status": true, "message": "Success", "status_code": 0, "result": { "error_code": 0, "message": "This account is active", "account_status": 1, "invoice": [ { "amount": 100.5, "min_amount": 10.0, "contract_name": "test", "contract_number": "12345", "fio": "Иванов Иван" }, ] } } ``` {% endtab %} {% tab title="200: OK Неуспешный ответ" %} ```json { "status": true, "message": "Success", "status_code": 0, "result": { "error_code": 0, "message": "This account is inactive", "account_status": 0, "invoice": null, "additional_data": { "error_message": "" } } } ``` {% endtab %} {% tab title="200 OK: Ожидаемая ошибка" %} ```json { "status": true, "message": "Success", "status_code": 0, "result": { "error_code": 9718, "message": "provider not found", "account_status": 0, "invoice": null, "additional_data": null } } ``` {% endtab %} {% tab title="400 Bad Request: Неожидаемая ошибка" %} ```json { "status": false, "status_code": 1014, "message": "Invalid signature", "result": {} } ``` {% endtab %} {% endtabs %} # Callback платежной системы Метод предназначен для оповещения системы проекта о статусе платежа. ### Backoff Policy Для увеличения гарантий получения ответа используются BackOff-политики при выполнении запросов: * интервалы между повторными запросами = 500 Millisecond * Разброс запроса по времени между повторами = 0.5 * Максимальное время между повторами = 60 Second * Время в течении которого будут выполнены попытки = 10 Minute #### Callback платежной системой после каждой операции После завершения оплаты, платежная система делает запрос в проект партнера для передачи состояния платежа. Запрос делается на адрес указанный в поле `callback_url` при [проведении платежа.](/agws/provedenie-platezha) При получении http статуса отличного от 200 будут выполнены BackOff политики ## Отправка callback-a `POST``https://merchant-website/result` #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ----------------------------------------------------------------------------------- | | Authorization\* | String | Bearer Авторотационный хэш (см [Формирование подписи](/agws/formirovanie-podpisi)) | #### Request Body
NameTypeDescription
status_codeStringКод статуса транзакции
status_messageStringОписание статуса транзакции
usernameStringИдентификатор пользователя
amountFloatЗачисленная сумма
datetimeStringВремя инициации платежа в системе витрины.Формат ISO 8601 Current Timestamp
projectStringКод Проекта присваиваемый Tarlan-ом
service_codeStringИдентификатор услуги на стороне витрины
external_idStringИдентификатор платежа на стороне витрины
fail_reasonObjectПоле содержащее причину неуспеха
-codeIntКод причины отклонения операции
-messageStringОписание причины отклонения операции
```json { "project": "Testing", "service_code": "70958", "external_id": "proident", "status_code": "4", "status_message": "Transaction was failed", "amount": 100.82, "datetime": "fugiat sed", "username": "enim culpa eiusmod laborum", "fail_reason": { "code": 6132012, "message": "nulla Ut eu dolore" } } ``` # Получение фискального чека Метод получения фискального номера и чека по идентифиакатору платежа `GET``https://agwsapi.tarlanpayments.kz/fiscalization/api/v1/payment/fiscalization/order` ### Headers | Name | Value | | ------------ | -------------------------------------------------------------- | | Content-Type | `application/json` | | X-Signature | [Авторизационный хэш](/platezhnyi-shlyuz/formirovanie-podpisi) | ### Query Params
KeyDescription
provider_order_idИдентификатор платежа на стороне поставщика услуг
provider_codeКод поставщика услуг
provider_service_codeКод услуги поставщика услуг
### Response body parameters
NameTypeDescription
statusbooleanСтатус обработки запроса
status_codeuintКод ошибки
messagestringОписание ошибки
resultobjectОбъект хранящий результат запроса
-fiscal_numberstringФискальный признак чека
-fiscal_check_urlstringСсылка для отображения фискального чека
{% tabs %} {% tab title="200: OK Пример успешного ответа" %} {% code overflow="wrap" %} ```json { "status": true, "message": "Success", "result": { "fiscal_number": "123456789123", "fiscal_check_url": "https://link.kz" } } ``` {% endcode %} {% endtab %} {% tab title="400: Bad Request Пример ответа с ошибкой" %} ```json { "status": false, "status_code": 1014, "message": "Invalid signature", "result": {} } ``` {% endtab %} {% endtabs %} ```bash curl --location 'https://agwsapi.tarlanpayments.kz/fiscalization/api/v1/payment/fiscalization/order?provider_order_id=pr10010&provider_code=code&provider_service_code=service_code' --header 'X-Signature: 3eec10e27f3b9ee198d2edfbf7ff7bce431940d88ed4201assadzxczxczxasd' ``` # Расчет верхней комиссии Метод для расчета верхней комиссии без фактического списания средств `POST``https://agwsapi.tarlanpayments.kz/showcase-gateway/api/v1/calculate/upper/commission` ### Headers | Name | Value | | ------------ | -------------------------------------------------------------- | | Content-Type | `application/json` | | X-Signature | [Авторизационный хэш](/platezhnyi-shlyuz/formirovanie-podpisi) | ### Request body parameters
NameTypeDescription
agentstringКод витрины в системе Tarlanpayments
projectstringКод Проекта в системе Tarlanpayments
service_codestringИдентификатор услуги в системе Tarlanpayments
amountfloat64Сумма для которой необходимо расчитать верхнюю комиссию
### Response body parameters
NameTypeDescriotion
statusbooleanСтатус обработки запроса
status_codeuintКод ошибки
messagestringОписание ошибки
resultObjectОбъект хранящий результат запроса
-amountfloat64Сумма для которой необходимо было расчитать верхнюю комиссию
-amount_with_commissionfloat64

Итоговая сумма с верхней комиссией

(amount + commission)

-commissionfloat64Сумма верхней комиссией
### Response examples {% tabs %} {% tab title="200: OK Пример успешного ответа" %} ```json { "status": true, "message": "Success", "status_code": 0, "result": { "amount": 10.4, "amount_with_commission": 11.84, "commission": 1.44 } } ``` {% endtab %} {% tab title="400: Bad Request Пример ответа с ошибкой" %} ```json { "status": false, "status_code": 1014, "message": "Invalid signature", "result": {} } ``` {% endtab %} {% endtabs %} ```bash curl --location 'https://agwsapi.tarlanpayments.kz/showcase-gateway/api/v1/calculate/upper/commission' \ --header 'X-Signature: 7ff51c9f26c287e42fa37537df719974e297a751c4e2eba26d7622sgwgf225543sa' \ --header 'Content-Type: application/json' \ --data '{ "agent":"agent", "project":"project", "service_code":"service", "amount": 10.42 }' ``` # Жалпы ақпарат **Төлем шлюзі** мен сіздің қосымшаңыз немесе веб-сайтыңыз арасындағы интеграцияны қамтамасыз ететін бағдарламалық шешім болып табылады. Бұл құжат төлем шлюзімен өзара іс-қимыл жасау үшін қажетті әдістердің егжей-тегжейлерін сипаттайды. *** ### Терминдер мен қысқартулар **API: Application Programming Interface** — Application Programming Interface – сыртқы бағдарламалық өнімдерде пайдалану үшін қосымшамен (жүйемен) ұсынылатын дайын әдістердің жиынтығы. **REST: Representational State Transfer** — желідегі үлестірілген қосымша компоненттерінің өзара іс-қимылының архитектуралық стилі. **JSON: JavaScript Object Notation** — RFC 7159 JavaScript негізделген деректер алмасудың мәтіндік форматы. **3DS: 3-D Secure** — интернет арқылы төлем операцияларын жасау кезінде банк картасын ұстаушыны сәйкестендіру үшін пайдаланылатын карточкалық деректерді қорғау хаттамасы. Tarlan Payments хаттаманың 3DS 1.0 нұсқасын да, 3DS 2.0 нұсқасын да қолдайды. **ТСП, Мерчант** — Жүйемен жұмыс істейтін сауда-сервистік кәсіпорын. **Проект (Жоба)—** әріптестің (мерчанттың) еншілес мәні. Мерчантқа заңды тұлғаларды, терминалдарды, сондай-ақ есептерді ажыратуға мүмкіндік береді. **Мерчант(серіктес)** – қызметтерді жүзеге асыру, тауарларды сату және т.б. үшін ақшалай қаражат алуға мүмкіндігі бар заңды тұлға. Сондай-ақ жобалардың біріктіруші мәні болып табылады. **Құпия кілт** – Жобаны сәйкестендіру үшін пайдаланылатын оны авторландыруға арналған символдық жол. **Төлем токені** – Акцептісіз төлемдер үшін картаның деректері бойынша жасалған символ жолы. *** ### Имплементациялау кезеңдері 1. Қосылуға өтінімді [tarlanpayments.kz ](https://tarlanpayments.kz/)сайтында қалдырыңыз *Өтінімді өңдегеннен кейін Қолдау қызметінің менеджері сіздермен қосылудың ықтимал нұсқаларын талқылайды, қажетті құжаттарды сұрайды, банктермен бірігу процесін, шартты, терминалды құруды іске қосады.* 2. Жеке кабинетке рұқсаттама алыңыз.\ *Төлемдерді қабылдау хаттамасына қосылған кезде сіз мерчанттың бірегей сәйкестендіргішін және Жеке кабинетке рұқсаттама аласыз. Қол жеткізу параметрлері тіркелу кезінде көрсетілген e-mail-ге жіберіледі.* 3. API-ге рұқсаттама кілтін шығарыңыз. *API-ге рұқсаттама кілті API-мен өзара әрекеттесу үшін пайдаланылады. Аккаунт-менеджерден API кілтін алыңыз.* 4. Өзара әрекеттестікті тестілеңіз.\ *Қосылғанда сіздің сәйкестендіргішіңіз тестілік режимде болады. Осы режимде сіз операцияларды банк картасынан қаражатты есептен шығармай жүргізе аласыз.* Сіздің тарапыңыздағы интеграция аяқталған кезде, біз сіздің project\_id сәйкестендіргішіңізді өндірістік режимге ауыстырамыз. **Назар аударыңыз!** Өндірістік режимде қаражатты картадан нақты есептен шығару орындалады. ### Кері байланыс Сұрақтар мен ұсыныстарды мына мекенжайға жіберуге болады: [support@tarlanpayments.kz](mailto:support@onevision.kz) Сондай-ақ, [ресми сайттағы](https://tarlanpayments.kz/) «Байланыстар» бөлімінде көрсетілген деректемелер бойынша # Төлемді жүргізу құрылымы #### Төлем жүргізу қадамдары 1. Әріптес Клиенті Мерчант жобасында төлем жасауға сұрау салады 2. Жоба транзакцияны жасауға сұрау жібереді 3. Жоба төлем бетінің URL-ін алады 4. Жоба клиентті төлем бетіне қайта бағыттайды 5. Клиент карта деректерін енгізіп, «Төлеу» батырмасын басады 6. Төлем жүйесі сұрау алады, егер транзакцияны құру кезінде confirm\_url параметрі көрсетілсе, төлем жүйесі Мерчант жобасына сұрау салады 7. Жоба confirm\_url параметрінде көрсетілген мекенжай бойынша жауап береді. Егер жоба «200»-ден ерекшеленетін http-кодпен жауап берсе, транзакция үзіледі 8. Төлем жүйесі банкке сауал жібереді 9. Төлем жүйесі банктен транзакция мәртебесі көрсетілген жауап алады 10. Төлем жүйесі төлем бетінде чекті шығарады 11. Төлем жүйесі жобаға транзакция мәртебесін callback\_url параметрінде көрсетілген мекенжайға жібереді #### Төлемді жүргізудің UML диаграммасы # Екі сатылы төлем жүргізу құрылымы #### Төлем жүргізу қадамдары 1. Әріптес Клиенті Is\_hold = true параметрін көрсете отырып, Мерчант жобасында төлем жасауға сұрау салады 2. Жоба транзакцияны жасауға сұрау жібереді 3. Жоба төлем бетінің URL-ін алады 4. Жоба клиентті төлем бетіне қайта бағыттайды 5. Клиент карта деректерін енгізіп, «Төлеу» батырмасын басады 6. Төлем жүйесі сұрау алады, егер транзакцияны құру кезінде confirm\_url параметрі көрсетілсе, төлем жүйесі Мерчант жобасына сұрау салады 7. Жоба confirm\_url параметрінде көрсетілген мекенжай бойынша жауап береді. Егер жоба «200»-ден ерекшеленетін http-кодпен жауап берсе, транзакция үзіледі 8. Төлем жүйесі қаражатты бұғаттауға банкке сұрау жібереді 9. Төлем жүйесі банктен транзакция мәртебесі көрсетілген жауап алады 10. Төлем жүйесі төлем бетінде чекті шығарады 11. Төлем жүйесі жобаға транзакция мәртебесін callback\_url параметрінде көрсетілген мекенжайға жібереді 12. Мерчант жобасы API немесе ЖК қолдана отырып, қаражатты есепті шығарады немесе қаражатты бұғаттаудан бас тартады 13. Төлем жүйесі қаражатты есептен шығаруға немесе бұғаттаудан бас тарту үшін банкке сұрау жібереді {% hint style="warning" %} Белгілі бір уақыт өткеннен кейін қолма-қол ақшаны автоматты түрде есептен шығару жүзеге асырылады, осы кезеңді орнату ЖК-те жүзеге асырылады және 3-тен 13 күнге дейін болуы мүмкін {% endhint %} {% hint style="info" %} Барлық бұғатталған қаражатты есептен шығару немесе жою **қол жетімді** {% endhint %} #### UML-төлем жүргізу диаграммасы # Операциялардың түрлері **Қабылдау (pay in)** – Банк карталарын пайдалана отырып, Интернет арқылы жасалған тауарлар/қызметтерге ақы төлеу операциясы. Төлем кезінде ақша қаражаты төлем картасын ұстаушының шотынан Серіктестің пайдасына аударылады. **Шығару (pay out)** – Шығару кезінде ақша қаражаты Серіктестің шотынан Серіктес клиентінің карточкалық шотына аударылады **Қайтару (refund)** – Ақша қаражатын қайтару. Ақша қаражатын табысты қабылдағаннан кейін ғана қолжетімді. *** **Екі сатылы төлем (pay in)** – Қосымша растауды талап ететін банк карталарын пайдалана отырып, Интернет арқылы жасалған тауарларға/қызметтерге ақы төлеу жөніндегі операция. Екі сатылы жұмыс тетігі банк картасының төлем қабілеттілігін тексеру (авторландыру) және ақша алу (қаржылық растау) процесін бөлуге мүмкіндік береді. Екі сатылы төлемнің бірінші сатысында картаны ұстаушының шотындағы қаражатты бұғаттау, ал екінші сатыда есептен шығару жүргізіледі * **Есептен шығару** – Ақша қаражатын авторландырылғаннан кейін екі сатылы төлем кезінде ғана қолжетімді операция. Бұғатталған соманы толық және ішінара есептен шығаруға болады. * **Жою** – Ақша қаражатын авторландырылғаннан кейін екі сатылы төлем кезінде ғана қолжетімді операция. Бұғатталған соманы толық және ішінара есептен шығаруға болады. *** **Картаны байластыру (card link)** – Ақша қаражатын банк картасынан тiркелген есептен шығару (pay in) және одан әрi ақша қаражатын картаға қайтару (refund) кезiндегi операция. **Акцептсіз қабылдау (one click pay in)** – Карточкалық деректерді енгізбей және 3DS аутентификациясыз төлем жүйесінде сақталған картаны пайдалана отырып ақша қаражатын қабылдау операциясы **Акцептсіз шығару (one click pay out)** – Карточкалық деректерді енгізбей төлем жүйесінде сақталған картаны пайдалана отырып, ақша қаражатын шығару операциясы. # 3D-Secure **3-D Secure** – пайдаланушының екі факторлы аутентификациясы үшін онлайн-кредиттік және дебеттік карталардың қосымша қауіпсіздік деңгейі ретінде пайдаланылатын хаттама. Мақсаты – ұстаушының түпнұсқалығын тексеру және картаны рұқсатсыз пайдаланудан қорғау. **Бұл қалай жұмыс істейді:** картаның иесі картаның деректемелерін көрсетеді, одан әрі эмитенттің сайты ашылады, онда ұстаушыға құпиясөзді немесе құпия кодты енгізу ұсынылады. Көп жағдайда код СМС-хабарламада жіберіледі. Егер код дұрыс көрсетілсе, төлем жүргізіледі. Егер жоқ болса, қабылданбайды. # PCI DSS PCI DSS – Visa және Mastercard төлем карталары индустриясында қабылданған ақпараттық қауіпсіздік стандарты. Карталарды төлеуге қабылдайтын барлық компаниялар стандарттың талаптарын сақтауға міндетті. Кейбір компаниялар өздерінің сәйкестігін растауы қажет. ***Қауіпсіздік стандарттарын сақтау*** Осы стандарт бағдарланған негізгі қағидат төлем карталарына байланысты деректерге қол жеткізуді барынша шектеуге ұмтылу болып табылады. Ең жақсы шешім мұндай деректерді өңдеуден мүлдем аулақ болу және оның орнына төлемдерді қабылдау үшін сертификатталған провайдерлерге жүгіну деп есептеледі. Бұл іс жүзінде біз карта нөмірлерін сұрамауымыз керек және бермеуіміз керек дегенді білдіреді. Егер клиент картаның нөмірін, мысалы, төлем проблемасымен қоңырау шалу кезінде хабарлауға тырысса, біздің міндетіміз – бұл әрекетті дереу тоқтатып, неге мұндай деректерді қабылдай алмайтынымызды түсіндіру. Егер деректер электрондық пошта арқылы немесе мессенджерлер арқылы келіп түссе, біз оларды жойып, карта деректерін жіберу қаупі туралы жіберушіге ескертуіміз керек. Қорғалатын деректер деп біз мыналарды түсінеміз: * Картаның толық нөмірі * CVV2/CVC2 коды (картаның артқы жағында орналасқан үш сан). * Карта иелерінің аттары * Қолданылу мерзімі Картаның бүркемеленген нөмірлері (алғашқы 6 және соңғы 4 сан) стандарт талаптарына сәйкес осындай қатаң қорғауды талап етпейді және ақылға қонымды шектерде пайдаланылуы мүмкін. Tarlan Payments жыл сайын осы сертификаттаудан өтеді және PCI DSS-тің барлық талаптарына сәйкес келеді
# Транзакция түрлері
кодсипаты
inПайдаланушының картасынан қаражатты есептен шығару
outЖоба шотынан пайдаланушының картасына ақша қаражатын шығару
one_click_pay_inПайдаланушының сақталған картасы бойынша қаражатты есептен шығару
one_click_pay_outЖоба шотынан сақталған пайдаланушы картасына қаражатты шығару
refundАқша қаражатын қайтару
google_payGoogle Pay технологиясының құралдары бойынша төлем
apple_payApple Pay технологиясының құралдары бойынша төлем
card_linkТөлем жүйесінде пайдаланушының картасын байластыру (акцептсіз төлемдер үшін пайдаланылады)
# Жүйе жауаптарының құрылымы Әрбір сұраудың жауабында: `status`, `status_code`, `message`, `result` өрістері бар. Сұрауды сәтті өңдегенде, жауапта `status` параметрі әрқашан `true`-ге тең, ал `status_code` `0`-ге тең. Басқа жағдайларда, `status_code` өрісі сұраудың дұрыс өңделмеу себебін көрсетеді. | Өріс атауы | Деректер типі | Сипаты | | :-----------: | :-----------: | :--------------------------------------: | | `status` | `bool` | Өріс сұраудың сәтті өңделгенін көрсетеді | | `status_code` | `integer` | Қате коды | | `message` | `string` | Қате кодының мәтіндік сипаты | | `result` | `object` | Сұралған ресурстың нәтижесі | # Қате кодтары
Қате кодыМәтіндік қолдауСипатыHTTP status
1021request validation errorСұраныс өрісін тексеру қатесі400
5102undefined transaction typeАнықталмаған транзакция түрі404
8301unexpected db errorРесурсты өңдеу кезінде анықталмаған қате500
5400couldn't receive project dataЖоба деректерін алу кезінде қате орын алды500
5406invalid project secretДұрыс емес хэш қалыптастыруы400
8008project doesn't existЖоба табылмады404
5000transaction already existsТранзакция әлдеқашан жасалған400
5101undefined transaction statusБелгісіз транзакция күйі404
5107transaction limit doesn't existТранзакция шектеулері орнатылмаған404
5006transaction amount limit is overТранзакция сомасы шегінен асып кетті400
5003an error occurred while creating transactionТранзакция жасау кезінде қате орын алды500
5202request failedЖобаға сұрау жіберу кезінде қате500
1022couldn't parse response bodyПолучен некорректный ответ500
5205unavailable project serverНе доступен сервер мерчанта при проведении запроса на подтверждение транзакции500
3108card doesn't exist Карта не найдена 500
3010inoperable transaction status for this methodСтатус транзакции не позволяет сделать повторный возврат400
**Провайдердің қате кодтары** Төлемді қабылдамау себебін сипаттайтын қателер[ failed ](/az/t-lem-shlyuzi/tranzakciyalar-m-rtebeleri)күйімен жіберіледі Бұл қателер қосымша ретінде жіберіледі. параметрлері: * Төлем күйі туралы [Webhook](broken://pages/J8upgdcouuqeSf3VAeOb) * Транзакция күйінің сұрауында * Транзакция күйінің сұрауында * Төлем беті жоқ «One click» арқылы
Қате кодыМәтіндік қолдауСипаты
100undefined errorАнықталмаған қате
1013DS authentication failed3DSecure тексеру мүмкін болмады
102invalid cardЖарамсыз карта
103exceeds amount limitСома лимитінен асып кетті
104exceeds transaction frequency limitТранзакциялар жиілігінің шегінен асып кетті
105transaction declined by an issuerТранзакцияны эмитент банк қабылдамады
106transaction declined by an acquirerТранзакцияны эквайер банк қабылдамады
107unavailable issuerЭмитент банк қолжетімді емес
108unavailable acquirerЭквайер-банк қолжетімді емес
109payment is forbidden for the merchantСатушыға төлем жасауға тыйым салынады
110stolen cardКарта ұрланған
111blocked cardКарта бұғатталған
112non existent cardКарта жоқ
113lost cardКарта жоғалған
114card has expiredКартаның жарамдылық мерзімі аяқталды
115incorrect CVV/CVCCVV/CVC дұрыс емес
116incorrect card numberКартаның нөмірі дұрыс емес
117incorrect card expiration dateКартаның қолданыс мерзімі дұрыс емес
118insufficient fundsҚаражат жеткіліксіз
119suspicious clientКүдікті клиент
120user did not payПайдаланушы төлем жасамады
121invalid threeD secure parametersЖарамсыз 3D Secure параметрлері
122Declined. Matches the Anti-Fraud Center list. Please contact [source_organization].Қабылданбады. Ақпарат Алаяқтықты бақылау орталығының тізіміне сәйкес келеді. [source_organization] компаниясына хабарласыңыз.
# Транзакциялар мәртебелері | код | атауы | сипаты | | :---------------: | :------------------------------------: | :-------------------------------------------------------------------------------------------------------------------: | | new | Транзакция жасалды | Транзакцияны құру кезіндегі мәртебе | | processed | Жұмыстағы транзакция | Пайдаланушы «Төлеу» батырмасын басты. Транзакция валидацияның барлық кезеңдерінен өтті. | | threeds\_waiting | Транзакция 3ds серверінен жауап күтуде | 3D-Secure тексеруді күтуде | | threeds\_received | Транзакция 3ds серверінен жауап алды | 3DS серверінен жауап алынды | | failed | Транзакция сәтсіз өтті | Транзакция жүргізу кезінде эквайер банкі тарапынан болған қате | | refund | Транзакция қайтарылды | Пайдаланушы картасына ақшалай қаражат қайтарылды | | canceled | Транзакция болдырылмады | Екі сатылы төлем кезінде транзакцияны болдырмау | | retry | Транзакция қайталау мәртебесінде | Қайта төлем жасау әрекеті. Пайдаланушы тарапынан енгізу қатесі болған жағдайда | | success | Транзакция сәтті өтті | Ақша қаражаты пайдаланушының картасынан алынды (Қабылдау). Ақша қаражаты пайдаланушының картасына шығарылды (Шығару). | | holded | Транзакция күту мәртебесінде | Эквайер банкінен жауап күтуде | | refund\_waiting | Транзакция қайтаруды күту мәртебесінде | Қаражатты қайтару процесі іске қосылды. Транзакция қайтаруды күтуде. | | authorized | Транзакция авторландырылды | Қаражат бұғатталды. Екі сатылы төлем кезінде пайдаланылады. | | error | Транзакция кезінде қате орын алды | Транзакция кезіндегі қате | # Қолтаңбаны қалыптастыру Төлем жүйесімен өзара іс-қимыл жасау үшін сұрау салуларға SHA256 алгоритмін пайдалана отырып қол қойылады. Қолтаңбаны қалыптастыру үшін: 1. POST сауал жағдайында requestData сауалының денесі әліпби бойынша сұрыпталады және BASE64-те кодталады. 2. GET сауал жағдайында, Query params-ты JSON-ға түрлендіреміз. В: { "merchant\_id" : 123, "project\_client\_id" : "999", "project\_id" : 124} Түрлендіргеннен кейін әліпби бойынша сұрыптаймыз және BASE64-те кодтаймыз. 3. Сауалдың (base64EncodedData) кодталған денесін және secret (мерчантқа төлем ұйымы береді) байланыстырамыз 4. SHA256 хеш-функциясын пайдалана отырып, алынған нәтижені хэштейміз (dataToSign) 5. Қолтаңбаны сауалының тақырыбына қосамыз Authorization: Bearer sign {% hint style="warning" %} **"" бос жол мәні бар өрістерді қоспағанда, бүкіл сұрау мәтіні қолтаңбаға қосылады.** {% endhint %} {% hint style="warning" %} **Additional\_data өрісі қолтаңбаны қалыптастыруға қатыспайды** {% endhint %} {% code lineNumbers="true" %} ```bash curl --location 'https://prapi.tarlanpayments.kz/transaction/...' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ff1a38a78ccca1b313ae172307e49112066ec2f5a1dfa2a76110104da3012896' --data-raw '{}' ``` {% endcode %} {% tabs %} {% tab title="PHP" %} {% code lineNumbers="true" %} ```php "9999", "merchant_id" => 1, "project_id" => 1, "additional_data" => ["key" => "This should be excluded"] ]; $secret = "12345"; // Remove the "additional_data" field from the request data unset($requestData["additional_data"]); // Sort the request data by keys in alphabetical order ksort($requestData); // Encode the sorted request data to JSON $sortedJson = json_encode($requestData, JSON_UNESCAPED_SLASHES); // Encode the sorted JSON to base64 $base64EncodedData = base64_encode($sortedJson); // Concatenate the base64-encoded data with the secret $dataToSign = $base64EncodedData . $secret; // Hash the result to SHA-256 $sha256Hash = hash("sha256", $dataToSign); echo $sha256Hash; ``` {% endcode %} {% endtab %} {% tab title="Python3" %} {% code lineNumbers="true" %} ```python import json import base64 import hashlib request_data = { "project_client_id": "9999", "merchant_id": 1, "project_id": 1, "additional_data": {"key":"This should be excluded"} } secret = "12345" # Remove the "additional_data" field from the request data if "additional_data" in request_data: del request_data["additional_data"] # Sort the request data by keys in alphabetical order sorted_data = json.dumps( request_data, sort_keys=True, ensure_ascii=False, separators=(',', ':'), ) # Encode the sorted JSON to base64 base64_encoded_data = base64.b64encode(sorted_data.encode()).decode() # Concatenate the base64-encoded data with the secret data_to_sign = base64_encoded_data + secret # Hash the result to SHA-256 sha256_hash = hashlib.sha256(data_to_sign.encode()).hexdigest() print(sha256_hash) ``` {% endcode %} {% endtab %} {% tab title="Golang" %} 
package main

import (
	"crypto/sha256"
	"encoding/base64"
	"encoding/json"
	"fmt"
)  // Тело берется из создания транзакции 

type Request struct {
	ProjectClientID string `json:"project_client_id"`
	MerchantId      uint64 `json:"merchant_id"`
	ProjectId       uint64 `json:"project_id"`
	AdditionalData  map[string]string `json:"additional_data"`
}

const secret = "12345"

func main() {
	request := Request{
		ProjectClientID: "9999",
		MerchantId:      1,
		ProjectId:       1,
		AdditionalData: map[string]string{
			"key": "This should be excluded",
		},
	}

	notSortedJson, err := json.Marshal(&request)
	if err != nil {
		panic(err)
	}

	var notSorteddMap map[string]interface{}

	
	if err = json.Unmarshal(notSortedJson, &notSorteddMap); err != nil {
		panic(err)
	}

	delete(notSortedMap, "additional_data")
	
	sortedJson, err := json.Marshal(&notSorteddMap)
	if err != nil {
		panic(err)
	}

	signData := base64.StdEncoding.EncodeToString(sortedJson)
	
	sign := sha256.Sum256([]byte(signData + secret))

	fmt.Printf("%x", sign)

}
{% endtab %} {% tab title="Dart" %} ```dart const paymentSecretKey = "123"; String hashedSecretKey({ required Map requestData, }) { // Sort the request data by keys in alphabetical order List> sortedEntries = requestData.entries.toList() ..sort((a, b) => a.key.compareTo(b.key)); Map sortedData = Map.fromEntries(sortedEntries); // Sort the request data by keys in alphabetical order String encodedData = json.encode(sortedData); // Encode the sorted JSON to base64 String base64EncodedData = base64.encode(Utf8Encoder().convert(encodedData)); // Concatenate the base64-encoded data with the secret String dataToSign = base64EncodedData + paymentSecretKey; // Hash the result to SHA-256 Digest sha256Hash = sha256.convert(Utf8Encoder().convert(dataToSign)); final result = sha256Hash.toString(); log('auth token $result'); return result; } ``` {% endtab %} {% endtabs %} [^1]: [https://app.gitbook.com/o/gxK1VbNmJ8bcGc8xM5wD/s/dkkz4EKtpaWVPlq7ZwsC/\~/changes/61/spravochnik-metodov-api/vzaimodeistvie-s-formoi-oplaty](broken://pages/rssHNRC5ER4AUkwJxprp) # Қосымша параметрлер Төлем нысанымен өзара іс-қимыл кезінде additional\_data өрісі беріледі. Бұл өрісте төлем жүйесінде сақталатын және мерчантқа webhook-e-де төлем мәртебесі бар және транзакция мәртебесін сұрауда берілетін серпінді өлшем параметрлері бар. {% hint style="warning" %} **Additional\_data өрісі қолтаңбаны қалыптастыруға қатыспайды** {% endhint %} # Төлем нысанымен өзара іс-қимыл Жүйенің төлем бетін пайдалана отырып транзакция құру {% content-ref url="/pages/yacNAg6We8EcA7SXesJF" %} [Ақша қаражатын қабылдауға бастамашылық жасау](/az/t-lem-shlyuzi/t-lem-nysanymen-zara-is-imyl/a-sha-arazhatyn-abyldau-a-bastamashyly-zhasau) {% endcontent-ref %} {% content-ref url="/pages/DuZft7hhZBasPvfyyNyU" %} [Ақша қаражатын шығаруға бастамашылық жасау](/az/t-lem-shlyuzi/t-lem-nysanymen-zara-is-imyl/a-sha-arazhatyn-shy-aru-a-bastamashyly-zhasau) {% endcontent-ref %} {% content-ref url="/pages/SBB6MXqU0rDlsNLq2NWQ" %} [Картаны байластыру](/az/t-lem-shlyuzi/t-lem-nysanymen-zara-is-imyl/kartany-bailastyru) {% endcontent-ref %} # Ақша қаражатын қабылдауға бастамашылық жасау ## Сақталған картасыз төлем ## Қабылдауға транзакция құру `POST` `https://prapi.tarlanpayments.kz/transaction/api/v1/transaction/primal/pay-in` #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------- | | Authorization\* | String | Bearer Авторотациялық хэш ([Қолтаңбаны қалыптастыруға ](/az/t-lem-shlyuzi/olta-bany-alyptastyru)қараңыз) | #### Request Body | Name | Type | Description | | -------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | amount\* | Float | Төлем сомасы | | project\_client\_id | String | Жоба жағындағы клиент сәйкестендіргіші | | callback\_url | String | Транзакция мәртебесімен коллбэкті түзету үшін жобаның URL-і (Сallback жіберуді қараңыз) | | failure\_redirect\_url\* | String | Сәтсіз төлемнен кейін пайдаланушының редиректісі орындалатын жоба беті. Егер параметр берілмесе, редирект `success_redirect_url`-де орындалатын болады | | merchant\_id\* | Integer | Төлем жүйесі беретін мерчант сәйкестендіргішіх | | project\_id\* | Integer |

Төлем жүйесі беретін жобаның сәйкестендіргіші

| | project\_reference\_id\* | String | Жоба жағындағы тапсырыс нөмірі | | success\_redirect\_url\* | String | Сәтті төлегеннен кейін пайдаланушының редиректісі орындалатын жоба беті | | shipment | String | Жеткізу мекенжайы | | confirm\_url | String | Төлемді жүргізуді растау үшін Жобаның URL-і (Төлемді жүргізуді растауды қараңыз) | | description\* | String | Төлемнің сипаты | | additional\_data | Object | Қосымша параметрлер | {% tabs %} {% tab title="200: OK Сәтті жауап үлгісі" %} ```json { "status": true, "message": "Success", "result": "https://process.tarlanpayments.kz?hash=$2a$10$nhrUYWm9sDVYqCL4LKxn9ugrdC4Pszz5wGaUsDYYIqCGc8ZA4Vu0y&transaction_id=100474" } ``` {% endtab %} {% tab title="500: Internal Server Error Қатесі бар жауап үлгісі" %} ```json { "status": false, "status_code": 5000, "message": "transaction already exists", "result": {} } ``` {% endtab %} {% endtabs %} CURL сауалының мысалы: {% code fullWidth="true" %} ```bash curl --location 'https://prapi.tarlanpayments.kz/transaction/api/v1/transaction/primal/pay-in' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer sign' \ --data-raw '{ "amount": 10, "callback_url": "https://test.site/callback_url", "confirm_url": "https://test.site/confirm_url", "description": "999", "failure_redirect_url": "https://www.test.com", "merchant_id": 9999, "project_client_id": "999", "project_id": 9999, "project_reference_id": "999", "shipment": "Tarlan ave, Payments str.", "success_redirect_url": "https://www.test.com", "additional_data": { "test1": "value1", "test2": 2 } }' ``` {% endcode %} ### Сақталған карта бойынша төлем `project_client_id` параметрін беру кезінде пайдаланушы төлем пішінінде картаны сақтау мүмкіндігіне ие болады. Картаны сақтау үшін пайдаланушы төлем пішініндегі «картаны сақтау» түймесін басып, осы карта арқылы сәтті төлем жасауы керек. Сақталған картаны пайдаланып келесі төлемдер үшін `project_client_id` параметрін өту керек. Сақталған картаны пайдалана отырып төлем жасаудың ерекшелігі төлем процесін айтарлықтай жылдамдатып, жеңілдететін 3DS пайдаланушы аутентификациясының болмауы болып табылады. # Ақша қаражатын шығаруға бастамашылық жасау ### Сақталған картасыз қаражатты шығару ## Қаражатты алу үшін транзакция жасау `POST` `https://prapi.tarlanpayments.kz/transaction/api/v1/transaction/primal/pay-out` #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------- | | Authorization\* | String | Авторотациялық хэш ([Қолтаңбаны қалыптастыруға ](/az/t-lem-shlyuzi/olta-bany-alyptastyru)қараңыз) | #### Request Body | Name | Type | Description | | -------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | amount\* | Float | Төлем сомасы | | project\_client\_id | String | Жоба жағындағы клиент сәйкестендіргіші | | callback\_url | String | Транзакция мәртебесімен коллбэкті түзету үшін жобаның URL-і (Сallback жіберуді қараңыз) | | failure\_redirect\_url | String | Сәтсіз төлемнен кейін пайдаланушының редиректісі орындалатын жоба беті. Егер параметр берілмесе, редирект `success_redirect_url`-де орындалатын болады | | merchant\_id\* | Integer | Төлем жүйесі беретін мерчант сәйкестендіргіші | | project\_id\* | Integer | Төлем жүйесі беретін жобаның сәйкестендіргіші | | project\_reference\_id\* | String | Жоба жағындағы тапсырыс нөмірі | | success\_redirect\_url\* | String | Сәтті төлегеннен кейін пайдаланушының редиректісі орындалатын жоба беті | | shipment | String | Жеткізу мекенжайы | | confirm\_url | String | Төлемді жүргізуді растау үшін Жобаның URL-і (Төлемді жүргізуді растауды қараңыз) | | description\* | String | Төлемнің сипаты | | additional\_data | Object | Қосымша параметрлер | {% tabs %} {% tab title="200: OK Сәтті жауап үлгісі" %} 
{
    "status": true,
    "message": "Success",
    "result": "https://process-dev.tarlanpayments.kz?hash=$2a$10$nhrUYWm9sDVYqCL4LKxn9ugrdC4Pszz5wGaUsDYYIqCGc8ZA4Vu0y&transaction_id=100474"
}
{% endtab %} {% tab title="500: Internal Server Error Қатесі бар жауап үлгісі" %} 
{
    "status": false,
    "status_code": 5000,
    "message": "transaction already exists",
    "result": {}
}
{% endtab %} {% endtabs %} CURL сауалының мысалы: {% code fullWidth="true" %} ```bash curl --location 'https://prapi.tarlanpayments.kz/transaction/api/v1/transaction/primal/pay-out' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer sign' \ --data-raw '{ "amount": 10, "callback_url": "https://test.site/callback_url", "confirm_url": "", "description": "999", "failure_redirect_url": "https://www.test.com", "merchant_id": 9999, "project_client_id": "999", "project_id": 9999, "project_reference_id": "999", "shipment": "", "success_redirect_url": "https://www.test.com", "additional_data": { "test1": "value1", "test2": 2 } }' ``` {% endcode %} ## Сақталған картаға ақшаны алу `project_client_id` параметрін беру кезінде пайдаланушы төлем пішінінде картаны сақтау мүмкіндігіне ие болады. Картаны сақтау үшін пайдаланушы төлем нысанындағы «картаны сақтау» түймесін басып, осы картадан ақшаны сәтті алуы керек. Сақталған картаны пайдаланып келесі төлемдер үшін `project_client_id` параметрін өту керек. # Картаны байластыру 1. Project\_client\_id көрсете отырып, картаны байластыру үшін транзакция құру. 2. 10 теңгеге төлем жасалады. 3. Мерчант төлем бетіне қайта жібереді. 4. Төлем жүргізілгеннен кейін 10 теңге қайтарылады. {% hint style="info" %} Мерчант картасын байластыру нәтижесін пайдаланушының байластырылған карталарының тізімін алу әдісінен біле аласыз, Webhook қаражатты есептен шығарғаннан кейін жіберіледі. Келесі төлемдер кезінде пайдаланушыға бұрын байластырылған карталар қолжетімді болады. {% endhint %} ## Картаны байластыру үшін транзакция құру. `POST` `https://prapi.tarlanpayments.kz/transaction/api/v1/transaction/primal/card-link` #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------ | | Authorization\* | String | Bearer Авторотациялық хэш ([Қолтаңбаны қалыптасуына ](/az/t-lem-shlyuzi/olta-bany-alyptastyru)қараңыз) | #### Request Body | Name | Type | Description | | -------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | project\_id\* | Integer | Төлем жүйесі беретін жобаның сәйкестендіргіші | | merchant\_id\* | Integer | Төлем жүйесі беретін мерчант сәйкестендіргіші | | project\_client\_id\* | String | Жоба жағындағы клиент сәйкестендіргіші | | success\_redirect\_url\* | String | Сәтті төлегеннен кейін пайдаланушының редиректісі орындалатын жоба беті | | failure\_redirect\_url\* | String | Сәтсіз төлемнен кейін пайдаланушының редиректісі орындалатын жоба беті. Егер параметр берілмесе, редирект success\_redirect\_url-де орындалатын болады | | description\* | String | Төлемнің сипаты | | additional\_data | Object | Қосымша параметрлер | | callback\_url | String | Транзакция мәртебесімен коллбэкті түзету үшін жобаның URL-і (Сallback жіберуді қараңыз) | {% tabs %} {% tab title="200: OK Сәтті жауап үлгісі " %} ```json { "status": true, "message": "Success", "result": "https://process.tarlanpayments.kz?hash=$2a$10$nhrUYWm9sDVYqCL4LKxn9ugrdC4Pszz5wGaUsDYYIqCGc8ZA4Vu0y&transaction_id=100474" } ``` {% endtab %} {% tab title="500: Internal Server Error Қатесі бар жауап үлгісі" %} ```json { "status": false, "status_code": 5000, "message": "transaction already exists", "result": {} } ``` {% endtab %} {% endtabs %} {% code fullWidth="true" %} ```bash curl --location 'https://prapi.tarlanpayments.kz/transaction/api/v1/transaction/primal/card-link' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer sign' \ --data-raw '{ "callback_url": "https://test.site/callback_url", "description": "desc", "failure_redirect_url": "https://www.test.com", "merchant_id": 2222, "project_client_id": "999", "project_id": 111, "success_redirect_url": "https://www.test.com", "additional_data": { "test": "value", "qwerty": "123" } }' ``` {% endcode %} # Iframe Төлем нысанын енгізу сыртқы сайт пайдаланушыларына төлемдерді өз сайты арқылы жүзеге асыруға мүмкіндік береді. Құжаттама төлем нысанын жасау, төлем деректерін өңдеу және Iframe өлшемін баптау бойынша қадамдарды ұсынады. Іframe өлшемін орнату үшін width және height төлсипаттарын өзіңіздің iframe-нің HTML-кодында орнатыңыз: ```html ``` Мұнда width (ені) 360 пиксель болып орнатылған, ал height (биіктігі) 700 пиксель болып орнатылған. Бұл мәндер сіздің қалауларыңызға және сыртқы сайт дизайнына сәйкес бапталуы мүмкін. # Төлем нысанынсыз төлемдер # One click Платеж по сохраненной карте ## Сақталған карта бойынша төлем `POST` `https://prapi.tarlanpayments.kz/transaction/api/v1/system/one-click/pay-in` #### Request Body | Name | Type | Description | | -------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------- | | amount\* | Float | Төлем сомасы | | callback\_url | String | Транзакция мәртебесімен коллбэкті түзету үшін жобаның URL-і (Сallback жіберуді қараңыз) | | card\_token\* | String | Webhook-тeн, карталар тізімінде немесе транзакция мәртебесінде картаны байластырғаннан кейін алынған төлем жүйесінің токені | | description\* | String | Төлем сипаттамасы (50 таңба) | | merchant\_id\* | Integer | Төлем жүйесі беретін мерчант сәйкестендіргіші | | project\_client\_id\* | String | Жоба жағындағы клиент сәйкестендіргіші | | project\_id\* | Integer | Төлем жүйесі беретін жобаның сәйкестендіргіші | | project\_reference\_id\* | String | Жоба жағындағы тапсырыс нөмірі | | additional\_data | Object | Қосымша параметрлер | {% tabs %} {% tab title="200: OK Сәтті жауап үлгісі" %} ```json { "status": true, "message": "Success", "result": { "transaction_id": 140001455, "transaction_status_code": "success", "bank_code":"101", "bank_message":"3DS authentication failed" } } ``` {% endtab %} {% tab title="500: Internal Server Error Қатесі бар жауап үлгісі" %} ```json { "status": false, "status_code": 5000, "message": "transaction already exists", "result": {} } ``` {% endtab %} {% endtabs %} {% code lineNumbers="true" fullWidth="true" %} ```bash curl --location 'https://prapi.tarlanpayments.kz/transaction/api/v1/system/one-click/pay-in' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer 123gf4d260ab38694d10833asdf3030d9a1cc75df4c598b0wer3230680923b1da7' \ --data-raw '{ "amount": 10, "callback_url": "", "card_token": "sdsd13123", "description": "test", "merchant_id": 9999, "project_client_id": "9999", "project_id": 9999, "project_reference_id": "9999" }' ``` {% endcode %} # Көмекші әдістер Төлем процесін оңтайландыру әдістері {% content-ref url="/pages/4MvvIbMZ9D1L9qAU6Gfx" %} [Транзакциялар мәртебелері](/az/t-lem-shlyuzi/tranzakciyalar-m-rtebeleri) {% endcontent-ref %} {% content-ref url="/pages/HCYEWvnTB4n3Hpbp9k9p" %} [Карталар тізімін алу](/az/t-lem-shlyuzi/k-mekshi-dister/kartalar-tizimin-alu) {% endcontent-ref %} {% content-ref url="/pages/2xL2uTgRZj8hpWPsuabM" %} [Төлемді қайтару](/az/t-lem-shlyuzi/k-mekshi-dister/t-lemdi-aitaru) {% endcontent-ref %} # Байластырылған пайдаланушы картасын жою ## Байластырылған пайдаланушы картасын жою `DELETE` `https://prapi.tarlanpayments.kz/card/api/v1/system/client/card/pay-in` #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------- | | Authorization\* | String | Bearer Авторотациялық хэш ([Қолтаңбаны қалыптастыруға ](/az/t-lem-shlyuzi/olta-bany-alyptastyru)қараңыз) | #### Request Body | Name | Type | Description | | ---------------------------------------------- | ------- | --------------------------------------------- | | project\_id\* | Integer | Төлем жүйесі беретін жобаның сәйкестендіргіші | | card\_token\* | String | Төлем жүйесіндегі карта токені | | merchant\_id\* | Integer | Төлем жүйесі беретін мерчант сәйкестендіргіші | {% tabs %} {% tab title="200: OK Сәтті жауап үлгісі" %} ```json { "status": true, "message": "Success", "result": "success" } ``` {% endtab %} {% tab title="500: Internal Server Error Қатесі бар жауап үлгісі" %} ```json { "status": false, "status_code": 5406, "message": "invalid project secret", "result": {} } ``` {% endtab %} {% endtabs %} {% code fullWidth="true" %} ```bash curl --location --request DELETE 'https://prapi.tarlanpayments.kz/card/api/v1/system/client/card/pay-in' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer auth_tokem' \ --data '{ "project_id": 3, "encrypted_card_id": "Qwerty12345", "merchant_id": 1 }' ``` {% endcode %} # Транзакция мәртебесін тексеру Транзакция күйін алу үшін жоба идентификаторы (project\_id) арқылы сұрау жасауға болады, күй туралы ақпарат нәтиже transaction\_status.code өрісінде сақталады. ## Транзакция мәртебесін алуға сауал `GET` `https://prapi.tarlanpayments.kz/transaction/api/v1/system/transaction/status` #### Query Parameters | Name | Type | Description | | -------------------------------------------------------- | ------- | --------------------------------------------- | | project\_reference\_id\* | String | Жоба жағындағы тапсырыс нөмірі | | merchant\_id\* | Integer | Төлем жүйесі беретін мерчант сәйкестендіргіші | | project\_id\* | Integer | Төлем жүйесі беретін жобаның сәйкестендіргіші | | type\* | String | Транзакция типі | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------- | | Authorization\* | String | Bearer Авторотациялық хэш ([Қолтаңбаны қалыптастыруға ](/az/t-lem-shlyuzi/olta-bany-alyptastyru)қараңыз) | {% tabs %} {% tab title="500: Internal Server Error Қатесі бар жауап үлгісі" %} ```json { "status": false, "status_code": 5103, "message": "transaction not found", "result": {} } ``` {% endtab %} {% tab title="200: OK Сәтті жауап үлгісі" %} 
{
    "status": true,
    "message": "Success",
    "result": {
        "id": 99999,
        "amount": 10,
        "description": "test",
        "user_phone": "87757715130",
        "user_email": "test@inbox.ru",
        "card_token": "sdfasdf23",
        "masked_pan": "0000-00XXXXXX-0000",
        "bank_code": "0", Код ошибки
        "bank_message": ""
        "additional_data": {
            "abc": "111",
            "lkk": "123"
        },
        "transaction_status": {
            "code": "success",
            "name": "Транзакция прошла успешно"
        },
        "bank_reference_id": "100885",
        "created_at": "2023-10-04T10:05:02.93843Z"
    },
    "transaction_type": {
      "code": "out",
      "name": "Вывод"
    },
    "refunds" : [] // fields: amount, date.
}
{% endtab %} {% endtabs %} ```bash curl --location 'https://prapi.tarlanpayments.kz/transaction/api/v1/system/transaction/status?merchant_id=1&project_id=42&project_reference_id=sanch92116&type=in' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer sign' ``` [^1]: [Код ошибки](broken://pages/NabOIjsudi6LZteJxIS7) передается в случае ошибки в транзакции # Карталар тізімін алу ## Сақталған карталар тізімін алуға сауал `GET` `https://prapi.tarlanpayments.kz/transaction/api/v1/system/client/cards` #### Query Parameters | Name | Type | Description | | ----------------------------------------------------- | ------- | --------------------------------------------- | | merchant\_id\* | Integer | Төлем жүйесі беретін мерчант сәйкестендіргіші | | project\_client\_id\* | String | Жоба жағындағы клиент сәйкестендіргіші | | project\_id\* | Integer | Төлем жүйесі беретін жобаның сәйкестендіргіші | #### Headers | Name | Type | Description | | ------------- | ------ | --------------------------------------------------------------------------------------------------------- | | Authorization | String | Bearer Авторотациялық хэш ([Қолтаңбаны қалыптастыруға ](/az/t-lem-shlyuzi/olta-bany-alyptastyru)қараңыз) | {% tabs %} {% tab title="200: OK Сәтті жауап үлгісі" %} ```json { "status": true, "message": "Success", "result": [ { "card_token": "", "masked_pan": "0000-00XXXXXX-0000" }, { "card_token": "", "masked_pan": "0000-00XXXXXX-0000" }, { "card_token": "", "masked_pan": "0000-00XXXXXX-0000" } ] } ``` {% endtab %} {% tab title="500: Internal Server Error Қатесі бар жауап үлгісі" %} ```json { "status": false, "status_code": 1021, "message": "request validation error", "result": {} } ``` {% endtab %} {% endtabs %} {% code overflow="wrap" lineNumbers="true" fullWidth="true" %} ```bash curl --location 'https://prapi.tarlanpayments.kz/transaction/api/v1/system/client/cards?merchant_id=999&project_id=999&project_client_id=999' \ --header 'Authorization: Bearer sign' \ --data '' ``` {% endcode %} # Төлемді қайтару `POST` `https://prapi.tarlanpayments.kz/refund/api/v1/system/refund/partial` #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------- | | Authorization\* | String | Bearer Авторотациялық хэш ([Қолтаңбаны қалыптастыруға ](/az/t-lem-shlyuzi/olta-bany-alyptastyru)қараңыз) | #### Request Body | Name | Type | Description | | ------------------------------------------------- | ------- | --------------------------------------------- | | amount\* | Integer | Қайтару сомасы | | transaction\_id\* | Integer | Төлем жүйесіндегі транзакция сәйкестендіргіші | {% tabs %} {% tab title="200: OK Сәтті жауап үлгісі" %} ```json { "status": true, "message": "Success", "result": { "transaction_id": 999, "transaction_status_code": 999 } } ``` {% endtab %} {% tab title="500: Internal Server Error Қатесі бар жауап үлгісі" %} ```json { "status": false, "status_code": 5103, "message": "transaction not found", "result": {} } ``` {% endtab %} {% endtabs %} ```bash curl --location 'prapi.tarlanpayments.kz/refund/api/v1/system/refund/partial' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer sign' \ --data '{ "amount": 10, "transaction_id": "refund" }' ``` # Жоғарғы комиссияның есебі `GET` `https://prapi.tarlanpayments.kz/commission/api/v1/system/project/upper/commission` #### Query Parameters | Name | Type | Description | | --------------------------------------------------------- | ------- | --------------------------------------------- | | project\_id\* | Integer | Төлем жүйесі беретін жобаның сәйкестендіргіші | | merchant\_id\* | Integer | Төлем жүйесі беретін мерчант сәйкестендіргіші | | transaction\_type\_code\* | String | Транзакция типі | | transaction\_amount\* | Float | Транзакция сомасы | #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------- | | Authorization\* | String | Bearer Авторотациялық хэш ([Қолтаңбаны қалыптастыруға ](/az/t-lem-shlyuzi/olta-bany-alyptastyru)қараңыз) | {% tabs %} {% tab title="200: OK Сәтті жауап үлгісі" %} ```json { "status": true, "message": "Success", "result": { "total_commission_amount": 999.00 } } ``` {% endtab %} {% tab title="500: Internal Server Error Қатесі бар жауап үлгісі" %} ```json { "status": false, "status_code": 5102, "message": "commission not found", "result": {} } ``` {% endtab %} {% endtabs %} {% code fullWidth="true" %} ```bash curl --location 'https://prapi.tarlanpayments.kz/comission/api/v1/system/project/upper/commission?merchant_id=999&project_id=999&transaction_amount=1000.00&transaction_type_code=in' \ --header 'Authorization: Bearer sign' \ --data '' ``` {% endcode %} # Smart Pay 1. Google pay # Google pay Google Pay – қосымшада және веб-сайтта сатып алуға мүмкіндік беретін онлайн төлем жүйесі. Жүйе пайдаланушыларға интернеттен, сондай-ақ телефондар, планшеттер және Android сағаттарының көмегімен онлайн төлем жасауға мүмкіндік береді. Tarlan Payments-пен біріктірмес бұрын, Сізге [құжаттамамен ](https://developers.google.com/pay/api)танысу керек. Сайттар үшін aқолдау көрсетілетін интеграция типі – Web. Осы интеграция үшін келесі құжаттармен танысуыңыз қажет: * [Веб-сайттардың Google Pay құжаттамасы](https://developers.google.com/pay/api/web/overview?hl=ru) * [Веб-сайттарға арналған Google Pay интеграциясының бақылау тізімі](https://developers.google.com/pay/api/web/guides/test-and-deploy/integration-checklist?hl=ru) * [Веб-сайттарға арналған Google Pay брендингінің нұсқаулары](https://developers.google.com/pay/api/web/guides/brand-guidelines?hl=ru) Google Pay қызметімен жұмыс істеу үшін сізге [Google Pay & Wallet ](https://pay.google.com/business/console/)консолінде тіркеліп, Google сатушы сәйкестендіргішін алу қажет. Барлық сатушылар Google Pay API рұқсат етілген [пайдалану нұсқаулары ](https://payments.developers.google.com/terms/aup)мен [пайдалану шарттарын](https://payments.developers.google.com/terms/sellertos) орындауға міндетті. Параметрлер үшін: gateway мәнін көрсету қажет – tarlanpayments; gatewayMerchantId көрсету қажет - Google сатушысының сәйкестендіргіші; Аутентификацияның қолдау көрсетілетін әдістері: PAN\_ONLY және CRYPTOGRAM\_3DS. Қолдау көрсетілетін төлем жүйелері: Visa және Master Card. Төлем мекенжайын берудің қажеті жоқ. Google-дан алынған төлем токенін token өрісіне string форматында беру қажет. Оны Google-ден алған түрінде беру керек. Қалған параметрлер төменде сипатталған. # Төлем жүйесінің Webhook # Төлем мәртебесі Әдіс жоба жүйесін төлем мәртебесі туралы хабардар етуге арналған. ### Backoff Policy Жауап алу кепілдіктерін ұлғайту үшін BackOff-саясат сауалдарды орындау кезінде пайдаланылады: * InitialInterval = 500 \* time.Millisecond, қайталама сұрау аралықтары * RandomizationFactor = 0.5, Қайталаушылар арасындағы уақыт бойынша сұрау салуды шашу * MaxInterval = 60 \* time.Second, Қайталаулар арасындағы максималды уақыт * MaxElapsedTime = 10 \* time.Minute, оның ішінде әрекеттер орындалатын уақыт **Әрбір операциядан кейін төлем жүйесімен Callback** Төлем аяқталғаннан кейін төлем жүйесі төлем жағдайын беру үшін әріптестің жобасына сауал жібереді. Сауал төлем бастамашылығы кезінде `callback_url` өрісінде көрсетілген мекенжайға жасалады. 200 транзакциядан ерекшеленетін http мәртебесін алу кезінде BackOff саясаты орындалады ## Серіктес жобасының callback-a жіберу `POST` `callback_url` #### Headers | Name | Type | Description | | ----------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------- | | Authorization\* | String | Bearer Авторотациялық хэш ([Қолтаңбаны қалыптастыруға ](/az/t-lem-shlyuzi/olta-bany-alyptastyru)қараңыз) | #### Request Body | Name | Type | Description | | -------------------------------------------------------- | ------- | -------------------------------------------------------- | | created\_at\* | String | Транзакцияның жасалған күні | | transaction\_id\* | Integer | Төлем жүйесі жағындағы транзакция сәйкестендіргіші | | acquirer\_code\* | String | Банк сәйкестендіргіші | | project\_reference\_id\* | String | Жоба жағындағы транзакция сәйкестендіргіші | | project\_сlient\_id\* | String | Жоба жағындағы пайдаланушы сәйкестендіргіші | | status\_code\* | String | Транзакция мәртебесі | | type\_code\* | String | Транзакция типі | | amount\* | Float | Транзакция сомасы | | description\* | String | Сипаты | | finished\_at\* | String | Транзакцияның аяқталу күні | | project\_id\* | Integer | Жоба сәйкестендіргіші | | merchant\_id\* | Integer | Мерчант сәйкестендіргіші | | additional\_data | Object | Қосымша өрістер | | card\_token | String | Төлем жүйесіндегі карта токені | | masked\_pan | String | Бүркемеленген төлем картасы | | bank\_code | String | Транзакцияда қате болған жағдайда қате коды жіберіледі | | bank\_message | String | Қатені сипаттау | | issuer | String | Карта эмитенті | | ips | String | Халықаралық төлем жүйесі (B (Visa/Mastercard тағы басқа) | # Ақы төлеуді жүргізуге әзірлік Әдіс жоба жағынан тапсырысты төлеуді растауға арналған. Жүйе жобаның confirm\_url-не іске қосуға сауал жібереді және мынадай міндетті параметрлері бар жауап күтеді: `id`, `status`, `message`, `is_payble`. Егер `confirm_url` параметрі төлем бастамашылығы кезінде берілсе, әдіс пысықталады. ### Backoff Policy Жауап алу кепілдіктерін ұлғайту үшін сауалдарды орындау кезінде BackOff саясаттар пайдаланылады: * InitialInterval = 500 \* time.Millisecond, қайталама сұрау аралықтары * RandomizationFactor = 0.5, қайталау арасындағы сұраныс уақытының таралуы * MaxInterval = 60 \* time.Second, қайталау арасындағы максималды уақыт * MaxElapsedTime = 10 \* time.Minute, талпыныстар жасалатын уақыт `GET` `https://merchant-website/confirm` #### Query Parameters | Name | Type | Description | | -------------------------------------------------------- | ------ | ------------------------------ | | type\* | string | Транзакция типі | | project\_reference\_id\* | string | Жоба жағындағы тапсырыс нөмірі | #### Headers | Name | Type | Description | | ------------- | ------ | --------------------------------------------------------------------------------------------------------- | | Authorization | String | Bearer Авторотациялық хэш ([Қолтаңбаны қалыптастыруға ](/az/t-lem-shlyuzi/olta-bany-alyptastyru)қараңыз) | {% tabs %} {% tab title="200: OK Жоба жауабының мысалы. Барлық өрістер міндетті." %} ```json { "id": "121abc", // Идентификатор транзакции на стороне проекта "status": "success", // Статус заказа на стороне проекта "message": "order desciption", // Текстовое сопровождение ответа "is_payble" : true // Разрешение на проведение платежа } ``` {% endtab %} {% endtabs %} `is_payble` параметрінің мәніне байланысты жүйе төлем жасау туралы шешім қабылдайды: * `true` - Жоба төлемді жүргізуге рұқсат береді * `false` - Жоба төлем жүргізуден бас тартады # CMS # Tilda Publishing Tilda-да интернет-дүкен құру кезінде Tarlan Payments төлем шлюзін қосу Қосылу үшін мыналар қажет: 1. Іске асырудың барлық кезеңдерінен өтіңіз Сіз мынаны аласыз: * Мерчант жобасының сәйкестендіргіші (merchant\_id:project\_id) * Құпия кілт (Secret Key) 2. Tilda → Сайттың баптаулары → Төлем жүйелері → Tarlan Payments өтіңіз 3. "Мерчант жобасының сәйкестендіргіші" және "Құпия кілт" өрістеріне деректерді енгізіңіз 4. Валютаны таңдаңыз – Қазақстан теңгесі (KZT)
Төлем жүйесі қосылған. *Егер бірнеше төлем жүйесі қосылған болса, онда олар тауар сатып алу кезінде төлем нұсқаларында автоматты түрде пайда болады.* # Өзгерістер жиынтығы
НұсқаСипаты
1.1.2 от 21.11.23Провайдердің қате кодтары қосылды
1.1.1 от 01.11.23
  1. Email, phone алу төлем бетіне көшірілді, міндеттілік мерчанттың ЖК-де реттеледі.
  2. additional_data өрісі арқылы қолтаңба қатесі түзетілді.
1.1.0 от 19.10.23
  1. Төлемді қайтару

Бөлім:
API Төлемді қайтару

  1. Картаны Байластыру

Пайдаланушылар жылдам және қауіпсіз транзакциялар үшін өз карталарын екі жолмен байластыра алады:

  • төлем виджетінде
  • back-to-back шешімі арқылы

Бөлім:
API Картаны Байластыру

  1. Пайдаланушының Сақталған Картасынан Қаражатты Қабылдау және Шығару: Біз сақталған карталарды пайдалана отырып, ақшаны қабылдау мен шығарудың ыңғайлы тәсілін ұсынамыз.

Бөлімдер:

API Қаражатты Қабылдау
API Қаражатты Шығару

  1. Сақталған карталарды шақыру әдісі:

Карта токенін алу мүмкіндігі:

  • транзакция мәртебесінде
  • Webhook арқылы

Бөлімдер:
API Сақталған карталарды шақыру әдісі

  1. Google Pay: Енді ыңғайлы және жылдам онлайн-төлемдер үшін Google Pay қолдауға ие.

Бөлімдер:
API Google Pay

  1. Iframe арқылы біріктіру: Біз жақсартылған пайдаланушылық тәжірибе үшін iframe арқылы өз қосымшамызбен біріктіру мүмкіндігін ұсынамыз.

Бөлімдер:
iframe арқылы біріктіру мүмкіндігі

  1. Tilda Publishing арқылы біріктіру: Енді сіз тамаша лендингтер мен интерактивті беттер жасау үшін біздің қосымшаны Tilda Publishing-пен біріктіре аласыз.

Бөлімдер:

Tilda Publishing арқылы біріктіру мүмкіндігі

  1. Қолтаңбаны қалыптастырудағы өзгерістер: Біз қауіпсіздік деңгейінің жоғарылығын қамтамасыз ете отырып, қолтаңбаларды қалыптастыру процесіне жақсартулар енгіздік.

Бөлімдер:
Қолтаңбаны қалыптастырудағы өзгерістер

1.0.0 от 01.08.23
  1. Ақша қаражатын қабылдау және шығару:

Енді сіздің рөліңізге немесе мақсатыңызға қарамастан, біздің қосымша арқылы ақшаны қабылдай және шығара аласыз.

Бөлімдер:
API Ақша қаражатын қабылдау
API Ақша қаражатын шығару

  1. Цифрлық Қолтаңбаны қалыптастыру:

Транзакциялардың қосымша қауіпсіздігін қамтамасыз ететін барлық қаржылық операциялар үшін цифрлық қолтаңба жасау мүмкіндігі қосылды.


Бөлімдер:
API Цифрлық Қолтаңбаны қалыптастыру

  1. Call-Back-терді жіберу:

Енді жүйе төлемдерді өңдеу процесін жақсарта отырып, сәтті транзакциялардан кейін төлем ұйымына автоматты түрде хабарлама жібереді.


Бөлімдер:
API Call-Back-терді жіберу

# Жүйе жауаптарының құрылымы Әрбір сауалға жауапта: result өріс бар, онда: error\_code, message өрістері болады Сауал сәтті өңделген кезде error\_code 0-ге тең болады. Басқа жағдайларда error\_code өрісі сауалды дұрыс өңдемеу себебін және тиісті message көрсетеді. # Қолтаңбаны қалыптастыру Сервиспен өзара іс-қимыл жасау үшін сауалдарға SHA256 алгоритмін пайдалана отырып қол қойылады. Қолтаңба әрбір сауал үшін жеке қалыптастырылады. Қолтаңбаны қалыптастыру үшін келесі қадамдарды орындаңыз: 1. **Сауал денесі әліпби бойынша сұрыпталады және BASE64-те кодталады.** 2. **Сауалдың кодталған денесі мен secret\_key (жеке ұсынылады) тіркесімін жасаймыз** 3. **SHA256 хеш функциясын пайдалана отырып, алынған тіркесім нәтижесін хэштейміз** 4. **X-Signature сауалының тақырыптарына қолтаңбаны қосамыз** "" ретінде толтырылған сауал өрістері қолтаңбаны қалыптастыруға қатыспайды. # Golang-та қолтаңбаны қалыптастыру мысалы: ```go package main import ( "crypto/sha256" "encoding/base64" "encoding/json" //Сауал денесі сауалға байланысты өзгереді type Request struct { Agent string `json:"agent"` Project string `json:"project"` ServiceCode string `json:"service_code"` } //Мысал үшін secret 12345 const secret = "12345" func main() { request := Request{ Agent: "tarlan", Project: "mobile", ServiceCode: "101", } notSortedJson, err := json.Marshal(&request) if err != nil { panic(err) } var notSortedMap map[string]interface{} if err = json.Unmarshal(notSortedJson, ¬SortedMap); err != nil { panic(err) } sortedJson, err := json.Marshal(¬SortedMap) if err != nil { panic(err) } signData := base64.StdEncoding.EncodeToString(sortedJson) sign := sha256.Sum256([]byte(signData + secret)) fmt.Printf("Sign: %x", sign) } ``` # python3-тегі қолтаңбаны қалыптастыру мысалы: ```go import json import base64 import hashlib # Сауал денесі сауалға байланысты өзгереді request_data = { "agent": "tarlan", "project": "mobile", "service_code": "101", } #Мысал үшін secret 12345 алынды secret = "12345" sorted_data = json.dumps( request_data, sort_keys=True, ensure_ascii=False, separators=(',', ':'), ) base64_encoded_data = base64.b64encode(sorted_data.encode()).decode() data_to_sign = base64_encoded_data + secret sha256_hash = hashlib.sha256(data_to_sign.encode()).hexdigest() print("Sign:",sha256_hash) ``` # \[POST] /showcase-gateway/api/v1/test/check Host: https\://agwsapi.dev-tarlanpayments.kz/ Аккаунт күйін тексеру {% content-ref url="/spaces/dkkz4EKtpaWVPlq7ZwsC/pages/nqRkFjSFbXjz6VU8fsA2" %} [Broken mention](broken://spaces/dkkz4EKtpaWVPlq7ZwsC/pages/nqRkFjSFbXjz6VU8fsA2) {% endcontent-ref %} {% content-ref url="/spaces/dkkz4EKtpaWVPlq7ZwsC/pages/Ocah8pk2xGzMMdt5yeaC" %} [Broken mention](broken://spaces/dkkz4EKtpaWVPlq7ZwsC/pages/Ocah8pk2xGzMMdt5yeaC) {% endcontent-ref %} # Parameters Parameters:
ПараметрлерФорматСипатыМіндеттілік
usernameStringПайдаланушы сейкестендіргішіИә
agentStringTarlan жүйесіндегі витрина кодыИә
projectStringЖобаның Tarlan берген кодыИә
service_codeStringВитрина жағындағы қызмет сәйкестендіргішіИә
**Мысал:** **Headers**\ Content-Type : *application/json* X-Signature: *227e9c6513a43f71f4cb6acb3c73f26f3ea90f7e36305afc6d37f9923f12d8c8* Body: ```go { "username": "989898", "agent": "tarlan", "project": "mobile", "service_code": "201106" } ``` --- [Next Page](/llms-full.txt/1)