# Проведение платежа
`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.md) |
**Body**
| Name | Type | Description |
|---|
| username* | String | Идентификатор пользователя |
| amount* | Float | Сумма транзакции |
| agent* | String | Код витрины в системе Tarlan |
| project* | String | Код Проекта присваиваемый Tarlan-ом |
| service_code* | String | Идентификатор услуги на стороне витрины |
| external_id* | String | Уникальный идентификатор платежа на стороне витрины |
| datetime* | String | Время инициации платежа в системе витрины. Формат ISO 8601 Current Timestamp |
| callback_url | String | URL на который будет отправлен callback запрос |
**Response**
| Параметры | Формат | Описание |
|---|
| status | bool | Статус обработки запроса |
| status_code | uint | Код ошибки |
| message | string | Описание ошибки |
| result | Object | Результат запроса, в котором содержится информация |
| -error_code | uint | Код ошибки |
| -message | String | Описание ошибки |
| -data | Object | Информация о данных |
| --status_code | String | Код статуса транзакции |
| --status_message | String | Описание статуса транзакции |
| --username | String | Идентификатор пользователя |
| --amount | Float | Зачисленная сумма |
| --datetime | String | Время инициации платежа в системе витрины. Формат ISO 8601 Current Timestamp |
| --project | String | Код Проекта присваиваемый Tarlan-ом |
| --service_code | String | Идентификатор услуги на стороне витрины |
| --external_id | String | Идентификатор платежа на стороне витрины |
| --fail_reason | Object | Причина неуспеха проведения платежа |
| ---code | Int | Код причины отклонения операции |
| ---message | String | Описание причины отклонения операции |
| --info | Object | Дополнительные параметры зависящие от категории услуг |
{% 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 %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.tarlanpayments.kz/agws/provedenie-platezha.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.