# Проведение платежа
`POST` `https://agwsapi.tarlanpayments.kz/showcase-gateway/api/v1/action/cash-in`
**Headers**
| Name | Value |
| ------------ | -------------------------------------------------------------------------------------------- |
| Content-Type | `application/json` |
| X-Signature | [Авторизационный хэш](https://docs.tarlanpayments.kz/platezhnyi-shlyuz/formirovanie-podpisi) |
**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 %}