Tarlanpayments
Рус
Рус
  • Платежный шлюз
    • Общая информация
      • Процесс одностадийного платежа
      • Процесс двухстадийного платежа
      • Виды операций
      • 3D-Secure
      • PCI DSS
    • Типы транзакций
    • Структура ответов системы
    • Коды ошибок
    • Статусы транзакций
    • Формирование подписи
    • Дополнительные параметры
    • Взаимодействие с формой оплаты
      • Инициация приёма денежных средств
      • Инициация вывода денежных средств
      • Привязка карты
      • Инициация приёма денежных средств посредством Apple Pay
      • Инициация приёма денежных средств посредство Google Pay
      • Iframe
    • Платежи без формы оплаты
      • Платеж по сохраненной карте (one click)
      • Вывод денежных средств (pay-out)
      • Шифрование платежной карты
    • Вспомогательные методы
      • Удаление привязанной карты
      • Проверка статуса транзакции
      • Получение списка карт
      • Возврат платежа
      • Расчет верхней комиссии
      • Подтверждение списания средств
      • Отмена списания средств
    • Webhook платежной системы
      • Статус оплаты
      • Готовность проведения оплаты
    • Smart Pay
      • Google pay
    • CMS
      • WordPress
      • Bitrix
      • Tilda
    • Сводка изменений
  • AGWS
    • Коды состояния аккаунта
    • Статусы транзакции
    • Коды ошибок
    • Причина отклонения операции
    • Время жизни транзакции
    • Формирование подписи
    • Проверка состояния аккаунта
    • Проведение платежа
    • Проверка статуса пополнения
    • Проверка остатка баланса на счету
    • Подтверждение списания средств
    • Создание ссылки на оплату
    • Информация по услугам
    • Получение информации о юзере
    • Callback платежной системы
  • Получение фискального чека
  • Расчет верхней комиссии
Powered by GitBook
On this page
  • Проверка статуса аккаунта по username
  • Дополнительные параметры (info)
  1. AGWS

Проверка состояния аккаунта

Last updated 1 day ago

ВНИМАНИЕ: Новый формат ответа для ошибок

В ближайшее время в нашей системе ошибки будут разделены на ожидаемые и неожидаемые. Это приведет к изменению формата JSON-ответа в зависимости от типа ошибки. Пожалуйста, ознакомьтесь с изменениями на странице . Изменения будут применены ко всем API в системе AGWS, за исключением методов «».

Нажмите , чтобы просмотреть старые и новые ответы об ошибках JSON. Обратите внимание на это обновление и убедитесь, что ваша система готова к изменениям, если это необходимо.

Проверка статуса аккаунта по username

POST https://agwsapi.tarlanpayments.kz/showcase-gateway/api/v1/user/check

Headers

Name
Value

Content-Type

application/json

X-Signature

Body

Name
Type
Description

username*

String

Идентификатор пользователя

agent*

String

Код витрины в системе Tarlanpayments

project*

String

Код Проекта присваиваемый Tarlanpayments

service_code*

String

Идентификатор услуги на стороне витрины

info

Object

{
    "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

Name
Type
Description

status

bool

Статус обработки запроса

status_code

uint

Код ошибки

message

string

Описание ошибки

result

Object

Результат запроса, в котором содержится информация

-error_code

Integer

Код ошибки

-message

String

Описание ошибки

-account_status

Integer

-amount

Float

Фиксированная сумма платежа

-upper_commission

Float

Верхняя коммиссия

-fail_reason

Object

-info

Object

Дополнительные параметры (info)

В теле ответа приходят дополнительные параметры зависящие от категории услуги, тип услуги записывается как ключ в объекте info

"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"
    }
}
param
type
Desc

in_date

timestamp

Время начала парковки

left_free_time_minutes

Float

Кол-во оставшихся минут на выезд

sum

Float

Стоимость парковки

current_balance

Float

Текущий баланс

zone

string

Зона парковки

coordinates

object

Объект с координатами

├latitude

float64

Широта

├longitude

float64

Долгота

duration

uint

Длительность в секундах

phone

string

Номер телефона

"info": {
    "finance": {
        "phone": "7777777777",
        "contracts": [
            {
                "contract_id":"123456789",
                "contract_name":"Contract name",
                "contract_date": "03.01.2025 12:59:59",
                "client": "John Doe",
                "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,
                "min": 100.21,
                "max": 1292.64
            }
        ]
    }
}
param
type
Desc

phone

string

Номер телефона

contracts

array

Массив контрактов

├contract_id

string

ID договора

├contract_name

string

Название контракта

├contract_date

string

Дата контракта

├client

string

Имя клиента

├amount

float

Сумма

├min

float

Минимальная сумма погашения

├max

float

Максимальная сумма погашения

"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
            }                
        ]
    }
}

param
type
Desc

customer

object

Объяект с информацией о клиенте

├address

string

Адрес клиента

invoice

object

Объект с данными о счете

├invoice_id

string

Уникальный идентификатор счета

├period_date

string

Период счета

├formed_date

string

Дата формирования счета

├expire_date

string

Дата окончания срока оплаты

service

array

Массив сервисов

├fix_sum

float

Фиксированная сумма к оплате

├service_id

string

Идентификатор услуги

├service_name

string

Название сервиса

├measure

string

Единица измерения услуги

├fix_count

float

Фиксированное показание счетчика

├prev_count

float

Предыдущие показания счетчика

├last_count

float

Последние показания счетчика

├debt_sum

float

Сумма задолженности

├debt_info

string

Информация о задолженности

├prev_count_date

string

Дата предыдущих показаний

├last_count_date

string

Дата текущих показаний

├sum

float

Общая сумма

├pay_sum

float

Сумма которую платит клиент

├is_counter_service

bool

Является ли услуга счетчиком (true – да, false – нет)

{
  "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
  }
}
{
    "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"
        }
    }
}

Примеры ответов об ошибках до внесения изменений

{
    "status": false,
    "status_code": 1407,
    "message": "Cache: item not found",
    "result": {}
}
{
    "status": false,
    "status_code": 1014,
    "message": "Invalid signature",
    "result": {}
}

Примеры ответов об ошибках после внесения изменений

{
    "status": true,
    "status_code": 0,
    "message": "Success",
    "result": {
        "error_code": 1407,
        "message": "Cache: item not found",
        "data": null,
    }
}
{
    "status": false,
    "status_code": 1014,
    "message": "Invalid signature",
    "result": {}
}

Проверка аккаунта

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

зависящие от категории услуг

Состояние аккаунта. Подробнее см.

неуспеха проведения платежа

зависящие от категории услуг

Коды Ошибок
Проведение платежа
здесь
Авторизационный хэш
в справочнике состояния аккаунта
Причина
Дополнительные параметры
Дополнительные параметры