Check account status

ATTENTION: New Error Response Format In the near future, errors in our system will be classified as expected and unexpected. Depending on the type of error, the format of the JSON response will be changed. Please review the new formats on the Error Codes page. This change will be applied to all APIs in the AGWS system except ''Make a payment'.

Click here to view the old and new JSON error responses. Please take note of this update and ensure your system is ready for these changes, if necessary.

Checking account status by username

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

Headers

Name

Value

Content-Type

application/json

X-Signature

Authorization hash

Body

Name

Type

Description

username*

String

User ID

agent*

String

Showcase code in the Tarlanpayments system

project*

String

Project Code assigned to Tarlanpayments

service_code*

String

Service ID on the showcase side

Response

Name

Type

Description

status

bool

Request processing status

status_code

uint

Error code

message

string

Description of error

result

Object

The result of a query that contains information

-error_code

Integer

Error code

-message

String

Error description

-account_status

Integer

Account status. For more information, see the account status code

-amount

Float

Fixed Payment Amount

-upper_commission

Float

Upper commission

-fail_reason

Object

Field Containing the Failure Reason

--code

Int

Rejection Reason Code

--massage

String

Description of the Operation Rejection Reason

Additional Parameters (info)

he response body includes additional parameters that depend on the service category. The service type is recorded as a key within the info object. These parameters provide specific details related to the type of service and are dynamically included based on the service category.

"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

Parking Start Time

left_free_time_minutes

Float

Remaining Minutes for Exit

sum

Float

Parking Fee

current_balance

Float

Current Balance

zone

string

Parking zone

coordinates

object

Object containing coordinates

├latitude

float64

Latitude

├longitude

float64

Longitude

duration

uint

Duration in seconds

phone

string

Phone number

"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

Customer's phone number

contracts

array

List of contracts

├contract_id

string

Unique contract identifier

├contract_name

string

Contract name

├contract_date

string

Contract date and time

├client

string

Client's name

├amount

float

Amount

├min

float

Minimum amount within the contract

├max

float

Maximum amount within the contract

"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

Object with customer information

├address

string

Customer's address

invoice

object

Object with invoice details

├invoice_id

string

Unique invoice identifier

├period_date

string

Invoice period

├formed_date

string

Invoice creation date

├expire_date

string

Invoice due date

service

array

List of utility services

├fix_sum

float

Fixed service amount

├service_id

string

Unique service identifier

├service_name

string

Name of the service

├measure

string

Unit of measurement for the service

├fix_count

float

Fixed quantity

├prev_count

float

Previous meter reading

├last_count

float

Current meter reading

├debt_sum

float

Outstanding debt amount

├debt_info

string

Debt-related information

├prev_count_date

string

Date of the previous meter reading

├last_count_date

string

Date of the current meter reading

├sum

float

Total accrued amount

├pay_sum

float

Amount to be paid by client

├is_counter_service

bool

Indicates whether the service is metered (true – yes, false – no)

 {
    "status": true,
    "status_code": 0,
    "message": "Success",
    "result": {
        "error_code": 0,
        "message": "This account is active",
        "account_status": 1,
        "fail_reason": {},
        "info": {
            "parking": {
                "in_date": "2024-08-02T12:24:07+05:00",
                "left_free_time_minutes": 0,
                "sum": 118,
                "current_balance": -1
            }
        },
        "amount":119,
        "upper_commission": 122
    }
}

 {
    "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": "",
                "left_free_time_minutes": 0,
                "sum": 0,
                "current_balance": 0
            }
        }
    }
}

Examples of error responses before the changes

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

{
    "status": false,
    "status_code": 1014,
    "message": "Invalid signature",
    "result": {}
}

Examples of error responses after the changes

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

Account check

package main

import (
	"bytes"
	"crypto/sha256"
	"encoding/base64"
	"encoding/hex"
	"encoding/json"
	"io/ioutil"
	"log"
	"net/http"
	"sort"
)

// Response представляет ответ от сервера

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

	// Сортируем ключи по алфавиту
	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
	}

	response := string(bodyBytes)

	// Вывод ответа и результата
	return response, nil
}

func main() {
	// URL Запроса
	RequestURL := "https://agwsapi.tarlanpayments.kz/showcase-gateway/api/v1/user/check"
	// Secret Проекта
	SecretKey := "12345"

	// Тело запроса
	requestBody := Body{
		Agent:       "agent",
		UserName:    "login",
		Project:     "project",
		ServiseCode: "servise",
	}

	// Генерация заголовка
	sign, err := MakeSign(requestBody, SecretKey)
	if err != nil {
		log.Println("Error generating signature:", err)
		return
	}

	// Отправка запроса
	Response, err := CheckLogin(requestBody, RequestURL, sign)
	if err != nil {
		log.Panic("Error sending request", err)
		return
	}

	if Response != "" {
		log.Println(Response)
	}
}

Last updated 1 year ago

Was this helpful?