Tarlanpayments
Eng
Eng
  • Acquiring
    • General information
      • Structure of payment processing
      • Kinds of operations
      • 3D-Secure
      • PCI DSS
    • Types of transactions
    • Structure of system responses
    • Error code
    • Transaction statuses
    • Signature Creation
    • Additional parameters
    • Interaction with the payment method
      • Initiating funds receipts
      • Initiating pay out
      • Card link
      • Initiating funds using Apple Pay
      • Initiating funds using Google Pay
      • Iframe
    • Payments without form of payment
      • One click
    • Smart Pay
      • Google pay
    • Supplementary methods
      • Removal of a linked user card
      • Verification of transaction status
      • Receiving a list of cards
      • Refund
      • Upper fee calculation
    • Webhook of the payment system
      • Payment Status
      • Payment ready to be made
    • Tilda Publishing
    • Edit summary
  • AGWS
    • Account Status Codes Guide
    • Error Codes
    • Reason for operation rejection
    • Transaction Lifetime
    • Transaction Status Guide
    • Creating a Signature
    • Check account status
    • Make a payment
    • Checking the refill status
    • Checking the remaining balance on the account
    • Confirmation of funds debit
    • Creating a payment link
    • Showcase Flow
    • Service Provider Flow
    • Payment System Callback
    • Payment Processing Scheme
  • Receiving a fiscal receipt
  • Calculation of the upper commission
Powered by GitBook
On this page
  • Checking account status by username
  • Additional Parameters (info)
  1. AGWS

Check account status

Last updated 17 days ago

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 page. This change will be applied to all APIs in the AGWS system except '''.

Click 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

Headers

Name
Value

Content-Type

application/json

X-Signature

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

-amount

Float

Fixed Payment Amount

-upper_commission

Float

Upper commission

-fail_reason

Object

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

Account status. For more information, see the

Field Containing the

Error Codes
Make a payment
https://agwsapi.tarlanpayments.kz/showcase-gateway/api/v1/user/check
here
Authorization hash
account status code
Failure Reason