Introduction

This document describes the application program interface (API) of ZPLAT PAYMENT GATEWAY web service, developed by ZPLAT LLC.

The API is a universal gateway that allows software integration to get access to payment instruments.

Terms and abbreviations

API (Application Programming Interface) - set of ready-made methods provided by the application (system) for usage in external software products.

Host-to-Host API - set of ready-made methods provided by the application (system) for usage in cross-server (internal) software products.

JSON (JavaScript Object Notation) - text data exchange format based on JavaScript RFC 7159.

JSON-RPC (JavaScript Object Notation Remote Procedure Call) - remote procedure call protocol that uses JSON to encode messages.

TLS (Transport Layer Security) - cryptographic protocol that provide secure data transfer between nodes on the Internet.

HTTP (HyperText Transfer Protocol) - application layer protocol for data transfer.

HTTP header - lines with a colon-separated name-value pair in an HTTP message. The header format follows the ARPA Common Text Network Message Header Format (RFC 822).

Agent - A legal entity, except credit organization, or an individual entrepreneur engaged in accepting payments from individuals.

Agent's balance - the Agent's deposit account in the clearing bank of ZPLAT LLC.

Widget – compact application that performs one function.

OFD - operator of fiscal data.

Payment gateway - hardware and software complex that allows you to automate the process of accepting payments on the Internet.

Supplier - supplier of goods and services for transactions using bank cards.

Service - ZPLAT PAYMENT GATEWAY payment web-service.

General principles

The API is built on the JSON-RPC 2.0 remote procedure call protocol.

RPC Request

RPC request example

{
    "method": "method.name",
    "params": {
        "param1": "Any String",
        "param2": [
            "list",
            "of",
            "items"
        ]
    },
    "id": "744a0a7a-f33b-4aa6-a609-a8d44206b2d4"
}

RPC Request is a JSON object with the following fields:

id – Request ID
method - Method name on the remote service
params – An optional object with method parameters. If the called method has no parameters, the field can be omitted or set to NULL

RPC Response

RPC Response example

{
    "id": "744a0a7a-f33b-4aa6-a609-a8d44206b2d4",
    "error": null,
    "result": {
        "param1": "Any String",
        "param2": [
            {
                "id": 123,
                "title": "item 123"
            },
            {
                "id": 124,
                "title": "item 124"
            }
        ]
    }
}

RPC Response is a JSON object with the following fields:

error - An object with information about the error. If the method was executed without errors, the parameter will be equal to NULL
result - Object with the method execution result
id - Response ID. The value must be the same as in the request

Example of an RPC Request that failed

Example of an RPC request that failed

{
    "id": 202,
    "error": {
        "code": -32400,
        "message": "System (internal error)",
        "data": {
            "error": 504,
            "message": "Gateway Time Out"
        }
    },
    "result": null
}

The answer contains:

code - Error code
message - Error description
data - Additional field with error data. May not be sent or may contain an object with arbitrary data

The section describes Acquiring UzCard/HUMO through ZPLAT payment form (payment widget).

The service provider places a payment widget on his website. ZPLAT service sends data in JSON format to verify the payment with the service provider.

The service provider's billing system is designed to make payment processing faster and more secure. It also allows to prevent repeated payments for the order and promptly inform the user about payment problems.

URLs for calling API methods are configured in the service provider’s personal account. Before using this API for real payments, it is possible to test API calls from the service provider's personal account.

You can place a simple payment widget on your website. To do this, you need to correctly form the request parameters and a signature for it inside the payment form.

The MD5 hashing algorithm is used to generate the signature.

The widget generation request is collected with data and sent to the URL https://zplat.uz/payment/payform{vendor_name}

If you plan to process payments automatically, you also need to set up receiving API requests from ZPLAT system.

Widget code implementation example

{
  "VENDOR_ID" : "105328",
  "MERCHANT_TRANS_ID" : "22080452",
  "MERCHANT_TRANS_AMOUNT" : 10000,
  "MERCHANT_CURRENCY" : "UZS",
  "MERCHANT_TRANS_NOTE" : "Service description",
  "MERCHANT_TRANS_RETURN_URL" : "https://merchant.zplat.uz/order/1/success",
  "MERCHANT_TRANS_ERROR_RETURN_URL" : "https://merchant.zplat.uz/order/1/error",
  "MERCHANT_LANG" : "UZ",
  "MERCHANT_TRANS_DATA" : "eyJrZXkxIjoidmFsdWUxIiwia2V5MiI6InZhbHVlMiJ9",
  "SIGN_TIME" : 1707912038213,
  "SIGN_STRONG": "790ff7acbba83de8592ad876ab5cfbd2"
}

List of request parameters for payment

Parameter name	Format	Description
VENDOR_ID	integer	Service provider identifier in ZPLAT system
MERCHANT_TRANS_ID	string(256)	Order ID on the service provider side
MERCHANT_TRANS_AMOUNT	float	Payment amount
MERCHANT_CURRENCY	string(10)	Payment currency
MERCHANT_TRANS_NOTE	string(256)	Description of the service that will be displayed in the list of transactions in the service provider’s account
MERCHANT_TRANS_RETURN_URL	string(256)	Link to return user after payment
MERCHANT_TRANS_ERROR_RETURN_URL	string(256)	Link to return user in case of error
MERCHANT_LANG	string(256)	Payment form language
MERCHANT_TRANS_DATA	string(256)	Arbitrary service provider data that sent to the endpoint url `/pay` to verify the order
SIGN_TIME	integer	Current time in milliseconds
SIGN_STRING	md5	Request signature

All parameters are required.

Generating a request signature

To generate a request signature you must:

Create a signature string consisting of: SECRET_KEY, VENDOR_ID, MERCHANT_TRANS_ID, MERCHANT_TRANS_AMOUNT, MERCHANT_CURRENCY, SIGN_TIME.
Calculate the MD5 hash of this string.

The encoding of the signed string is UTF-8. The request signature expires 15 minutes after signing and is invalid if a future signing time is set.

Request signature example

md5(
   SECRET_KEY . 
   VENDOR_ID .
   MERCHANT_TRANS_ID . 
   MERCHANT_TRANS_AMOUNT .
   MERCHANT_CURRENCY .
   TIMESTAMP 
);

List of request signature parameters

Parameter name	Description
SECRET_KEY	Service Provider Secret Key
VENDOR_ID	Service Provider Identifier in ZPLAT system
MERCHANT_TRANS_ID	Order ID on the service provider side
MERCHANT_TRANS_AMOUNT	Payment amount
MERCHANT_CURRENCY	Payment currency
TIMESTAMP	Signing time in milliseconds

Payment information

Method name

This method implements obtaining information about the payment before paying it.

Request example

{
  "MERCHANT_TRANS_ID": "7",
  "SIGN_TIME": 1503638389658,
  "SIGN_STRING": "5777e5ed6eda5b5cca3f56a90cf53e96"
}

Request parameters

Parameter name	Description
MERCHANT_TRANS_ID	Payment ID in the partner's billing system
SIGN_TIME	Request signing time in milliseconds
SIGN_STRING	Verification string confirming the authenticity of the sent request `md5( SECRET_KEY . MERCHANT_TRANS_ID . SIGN_TIME )`, where `SECRET_KEY` is the secret key of the service provider.

Response example

{
  "ERROR": "0",
  "ERROR_NOTE": "Success",
  "PARAMETERS": {
    "full_name": "Test Test",
    "balance": "1000",
    "email": "test@test.uz"
  }
}

Response parameters

Parameter name	Description
PARAMETERS	Additional payment parameters from the billing system. May be set `NULL`.

Payment confirmation

Method name

This method implements checking the payment relevance in the service provider billing system, namely:

Availability of a generated order/login/personal account number in the billing system of the service provider, its relevance, as well as the ability to release the product or service specified in the order.
Up-to-date order amount and payment status.

The service provider must return the status of the order/login/personal account number to this request:

The order/login/personal account number and amount are actual and awaiting payment. Upon receipt of this status from the system, ZPLAT will complete the payment and payment completion notification will be sent.
Order/login/personal account number is not actual (cancelled). With this response, ZPLAT will send a payment completion notification indicating that the payment has been cancelled.

Request example

{
  "ENVIRONMENT": "live",
  "VENDOR_ID": "100036",
  "PAYMENT_ID": 16,
  "PAYMENT_NAME": "ZPLAT",
  "AGR_TRANS_ID": "66cdaaaeeaf4c846568385b6",
  "MERCHANT_TRANS_ID": "BA-42545-DA",
  "MERCHANT_TRANS_AMOUNT": 244783400,
  "SIGN_TIME": 1724754765422,
  "SIGN_STRING": "c1b80d524108d22222fa4d639c7e169a"

}

Request parameters

Parameter name	Description
ENVIRONMENT	Environment for executing the method: live-actual payments, sandbox-test payments
VENDOR_ID	Service Provider Identifier in ZPLAT system
PAYMENT_ID	Payment system identifier in ZPLAT system
PAYMENT_NAME	Name of payment system
AGR_TRANS_ID	Payment ID in ZPLAT system
MERCHANT_TRANS_ID	Order ID on the service provider side
MERCHANT_TRANS_AMOUNT	Payment amount in tiyins
SIGN_TIME	Request signing time in milliseconds
SIGN_STRING	Verification string confirming the authenticity of the sent request md5( SECRET_KEY . AGR_TRANS_ID . VENDOR_ID . PAYMENT_ID . PAYMENT_NAME . MERCHANT_TRANS_ID . MERCHANT_TRANS_AMOUNT . ENVIRONMENT . SIGN_TIME ) , where SECRET_KEY is the secret key of the service provider.

Response example

{
  "ERROR": "-2",
  "ERROR_NOTE": "Incorrect parameter amount"
}

Response parameters

Parameter name	Description
ERROR	Error code
ERROR_NOTE	Error description

Payment notification

Method name

ZPLAT system notifies about change in payment status with this request. The supplier's billing system should complete/cancel the payment only after receiving this request.

Request example

{
  "AGR_TRANS_ID": 1503642925905,
  "VENDOR_TRANS_ID": "1503642925906",
  "STATUS": 2,
  "SIGN_TIME": 1503642926295,
  "SIGN_STRING": "5a30fbd0fab44be29310e4b493c9a287"
}

Request parameters

Parameter name	Description
AGR_TRANS_ID	Payment ID in ZPLAT system
VENDOR_TRANS_ID	Payment ID in the billing system of the service provider
STATUS	Payment status (integer): `2` - Payment successfully completed, `3` - Payment cancelled, `-1` - Error
MESSAGE	Error description (string) (The field is added only if the status is `-1`)
SIGN_TIME	Request signing time in milliseconds
SIGN_STRING	Verification string confirming the authenticity of the request being sent md5( SECRET_KEY . AGR_TRANS_ID . VENDOR_TRANS _ID . STATUS . SIGN_TIME ) , where SECRET_KEY is the secret key of the service provider.

Response example

{
  "ERROR": "0",
  "ERROR_NOTE": "Success"
}

Payment cancellation

Method name

Payment cancellations can be made within a maximum of 1 month after transaction. If more time passes, cancellation will be impossible.

Request example

{
    "jsonrpc": "2.0",
    "method": "receipt.reverse",
    "id": 2,
    "params": {
        "receipt_id": "<receipt_id>",
        "reason": "<reason>"
    }
}

Request parameters

Parameter name	Description
receipt_id	Receipt ID
reason	Transaction cancellation reason code

Response example

{
    "jsonrpc": "2.0",
    "result": {
        "agent": "<agent>",
        "method": "receipt.reverse",
        "receipt": {
            "id": "<id>",
            "amount": <amount>,
            "card": {
                "hash": "<hash>",
                "masked_pan": "<masked_pan>",
                "expire": "<expire>",
                "status": 1,
                "full_name": "<full_name>",
                "card_type": <card_type>,
                "processing": "<processing>"
            }, 
            "state": "<state>",
            "created_at": <created_at>,
            "paid_at": <paid_at>,
            "canceled_at": <canceled_at>,
            "operations": [
                {
                    "operation_type": "<operation_type>",
                    "id": "<id>",
                    "processing": "<processing>"
                },
                ...
            ],
            "product": {
              "key": "<key>"
            },
            "details": {},
            "commission": <commission>
        }
    },
    "id": 2
}

Response parameters

Parameter name	Description
agent	Agent name
method	Request type. Takes the value `receipt.reverse` when created
receipt	Payment receipt object
id	Payment receipt ID
amount	Payment amount in tiyins
card	Card object
hash	hashed card number. For example: `"1ae168da94f7a148e68b7c481e7e50becd428790"`
masked_pan	Card number in masked string
expire	Card validity period in `“YYMM”` format
status	Card status (1 - “Active”, 2 - “ActiveNoPhone”, 3 - “Blocked”)
full_name	Cardholder's full name
card_type	Card type, for example “Private” or “Corporate”
processing	Processing, for example: “uzcard” or “humo”
state	Payment status
created_at	Payment creation timestamp, in milliseconds
paid_at	Payment timestamp, in milliseconds
cancelled_at	Payment cancellation timestamp, in milliseconds
operations	Transaction detail object
operation_type	Type of transaction
id	Transaction id
processing	Description of processing
product	Product object
key	Product Key (for services that allow the customer to purchase product keys, such as PUBG keys)
details	Payment details
commission	Commission percentage

Checking for cancellation

Method name

CANCEL method is used to notify the Supplier that a payment has been canceled in ZPLAT system. After receiving the Success status in CANCEL response, ZPLAT system will send the Supplier a response to the receipt.reverse request notifying that the payment has been completed with Canceled status.

Request example

{
  "AGR_TRANS_ID": 1503642925905,
  "VENDOR_TRANS_ID": "1503642925906",
  "SIGN_TIME": 1503642926295,
  "SIGN_STRING": "5a30fbd0fab44be29310e4b493c9a287"
}

Request parameters

Parameter name	Description
AGR_TRANS_ID	Payment ID in ZPLAT system
VENDOR_TRANS_ID	Payment ID in the billing system of the service provider
SIGN_TIME	Request signing time in milliseconds
SIGN_STRING	Verification string confirming the authenticity of the request being sent md5( SECRET_KEY . AGR_TRANS_ID . VENDOR_TRANS _ID . SIGN_TIME ), where SECRET_KEY is the secret key of the service provider.

Response example

{
  "ERROR": "0",
  "ERROR_NOTE": "Success"
}

Error code	Meaning	Description
0	Success	Successful request
-1	SIGN CHECK FAILED!	Signature verification error
-2	Incorrect parameter amount	Invalid payment amount
-3	Action not found	Requested action not found
-4	Already paid	Transaction was previously confirmed (when trying to confirm or cancel a previously confirmed transaction)
-5	User does not exist	User/order not found (checking the MERCHANT_TRANS_ID parameter)
-6	Transaction does not exist	Transaction not found
-7	Failed to update user	Error when changing user data (changing account balance, etc.)
-8	Error in request from ZPLAT	Error in request from ZPLAT (not all parameters were transferred, etc.)
-9	Transaction cancelled	The transaction was previously canceled (when trying to confirm or cancel a previously canceled transaction)
-10	The vendor is not found	Supplier is not found in the system

Acquiring (host-to-host)

This section describes Acquiring UzCard/HUMO through the service provider's payment form (Host-to-Host API).

There are two possible scenarios: with holding of funds and without holding.

URL for running requests:

https://gateway.zplat.uz/api/jsonrpc

Interaction procedure with holding funds:

Interaction procedure without holding funds:

Authorization

The basic structure of Headers includes:

Content-Type – String containing the value: application/json; charset=utf-8
Authorization – String containing authorization data in Base64 encoding

Example:

Basic base64(login:key)

The login and key for the agent can be obtained from the payment service administrator.

The system uses HTTP status codes to transmit information about the success or failure of the request.

200 OK - means that the request was successfully processed by the system and no failures occurred while executing the request.

The system registers each incoming request with a unique request ID and save it in the payment service database. If the system responds successfully, this request ID is returned in the corresponding response field (x_request_id_create, x_request_id_pay, x_request_id_status). It is recommended to save this ID in the counterparty’s system to quickly search for request and resolve any arising problems.

Payment creation

Method name

Using this method, an online payment is created.

Request example

{
    "jsonrpc": "2.0",
    "method": "receipt.create",
    "id": 123,
    "params": {
        "ext_id": "avia",
        "service": "avia-ticket",
        "params": {
            "amount": 1000000
        },
        "receiver_id": "receiver",
        "hold": { 
            "holding_time": 10,
            "after_expired": "accept"
        }
    }
}

Request parameters

Parameter name	Description
ext_id	Generated on the agent side Transaction ID
service	Service name
receiver_id	Recipient ID
params	An object with parameters for created transaction
amount	Payment amount in tiyins
hold	Holding parameters
holding_time	Holding time in minutes
after_expired	Action after expiration (debiting of funds "accept" or cancel "cancel")

Response example

{
    "jsonrpc": "2.0",
    "result": {
        "agent": "avia",
        "method": "receipt.create",
        "receipt": {
            "id": "65cf2fd71390a295cc65cda6",
            "amount": 10000,
            "card": "56342b88467086165c52abb562377b28903b373d",
            "state": "4",
            "created_at": 1708077015764,
            "paid_at": 1708077042879,
            "canceled_at": 0,
            "operations": [
                {
                    "operation_type": "merchant",
                    "id": "65cf2fd7a50d380965ecd6c4",
                    "processing": null
                },
                {
                    "operation_type": "payment",
                    "id": "hold_humo_170807703187457",
                    "processing": "humo"
                }
            ],
            "product": {},
            "details": {},
            "commission": 100
        }
    },
    "id": 2
}

Response parameters

Parameter name	Description
agent	Agent name
method	Request type. Takes the value `receipt.create` when created
receipt	Payment receipt object
id	Payment receipt ID
amount	Payment amount in tiyins
card	Card number sha1
state	Payment status
created_at	Payment creation timestamp, in milliseconds
paid_at	Payment timestamp, in milliseconds
cancelled_at	Payment cancellation timestamp, in milliseconds
operations	Transaction details object
operation_type	Type of transaction
id	Transaction id
processing	Description of processing
product	Product object
details	Payment details
commission	Commission percentage

Payment with confirmation

Method name

This method allows you to pay the created payment by card with OTP confirmation.

Request example

{
    "jsonrpc": "2.0",
    "method": "receipt.web.pay",
    "id": 2,
    "params": {
        "receipt_id": "<id>",
        "card": {
            "pan": "<card>",
            "expire": "<expire>"
        }
    }
}

Request parameters

Parameter name	Description
receipt_id	Receipt ID
card	Object of the card with which payment is made
pan	Card number
expire	Card validity period in `“YYMM”` format

Response example

{
    "jsonrpc": "2.0",
    "result": {
        "agent": "<agent>",
        "method": "receipt.web.pay",
        "receipt": {
            "id": "<id>",
            "amount": <amount>,
            "card": {
                "hash": "<hash>",
                "masked_pan": "<masked_pan>",
                "expire": "<expire>",
                "status": 1,
                "full_name": "<full_name>",
                "card_type": <card_type>,
                "processing": "<processing>"
            }, 
            "state": "<state>",
            "created_at": <created_at>,
            "paid_at": <paid_at>,
            "canceled_at": <canceled_at>,
            "operations": [
                {
                    "operation_type": "<operation_type>",
                    "id": "<id>",
                    "processing": "<processing>"
                },
                ...
            ],
            "product": {
              "key": "<key>"
            },
            "details": {},
            "commission": <commission>
        }
    },
    "id": 2
}

Response parameters

Parameter name	Description
agent	Agent name
method	Request type. Takes the value `receipt.web.pay` when created
receipt	Payment receipt object
id	Payment receipt ID
amount	Payment amount in tiyins
card	Card object
hash	Hashed card number. For example: `"1ae168da94f7a148e68b7c481e7e50becd428790"`
masked_pan	Card number in masked string
expire	Card validity period in `“YYMM”` format
status	Card status (1 - “Active”, 2 - “ActiveNoPhone”, 3 - “Blocked”)
full_name	Cardholder's full name
card_type	Card type, for example “Private” or “Corporate”
processing	Processing, for example: “uzcard” or “humo”
state	Payment status
created_at	Payment creation timestamp, in milliseconds
paid_at	Payment timestamp, in milliseconds
cancelled_at	Payment cancellation timestamp, in milliseconds
operations	Transaction detail object
operation_type	Type of transaction
id	Transaction id
processing	description of processing
product	Product object
key	Product Key (for services that allow customer to purchase product keys, such as PUBG keys)
details	Payment details
commission	Commission percentage

OTP code transmit

Method name

This method allows you to transfer the OTP code to complete the verification.

Request example

{
    "id": 123,
    "jsonrpc": "2.0",
    "method": "receipt.web.verify",
    "params": {
        "receipt_id": "<receipt_id>",
        "otp": "<otp>"
    }
}

Request parameters

Parameter name	Description
receipt_id	Receipt ID
otp	OTP code

Response example

{
    "jsonrpc": "2.0",
    "result": {
        "agent": "test-agent",
        "method": "receipt.web.verify",
        "receipt": {
            "id": "64a2aae138480f57b14d66ac",
            "amount": 10000,
            "state":  "0",
            "card": "<sha1_of_card_number>",
            "created_at": 1688382177500,
            "paid_at": 0,
            "canceled_at": 0
          }
    "id": 123
}

Response parameters

Parameter name	Description
agent	Agent name
method	Request type. Takes the value `receipt.web.verify` when created
receipt	Payment receipt object
id	Payment receipt ID
amount	Payment amount in tiyins
state	Payment status
card	Card number sha1
created_at	Payment creation timestamp, in milliseconds
paid_at	Payment timestamp, in milliseconds
cancelled_at	Payment cancellation timestamp, in milliseconds

Holding funds

Method name

Using this method, you can confirm or cancel the holding of funds.

Request exampleа

{
    "jsonrpc": "2.0",
    "method": "receipt.hold", 
    "id": 2,
    "params": {
        "receipt_id": "65c9c8b2cd146a40f0c138bc",
        "action": "cancel"
    }
}

Request parameters

Parameter name	Description
params	Object with parameters
receipt_id	Receipt ID
action	Action (debiting of funds "accept" or cancel "cancel")

Response example

{
    "jsonrpc": "2.0",
    "result": {
        "agent": "avia",
        "method": "hold",
        "receipt": {
            "id": "65cf2fd71390a295cc65cda6",
            "amount": 10000,
            "card": "56342b88467086165c52abb562377b28903b373d",
            "state": "4",
            "created_at": 1708077015764,
            "paid_at": 1708077042879,
            "canceled_at": 0,
            "operations": [
                {
                    "operation_type": "merchant",
                    "id": "65cf2fd7a50d380965ecd6c4",
                    "processing": null
                },
                {
                    "operation_type": "payment",
                    "id": "hold_humo_170807703187457",
                    "processing": "humo"
                }
            ],
            "product": {},
            "details": {},
            "commission": 100
        }
    },
    "id": 2
}

Response parameters

Parameter name	Description
agent	Agent name
method	Request type. Takes the value `hold` when created
receipt	Payment receipt object
id	Payment receipt ID
amount	Payment amount in tiyins
card	Card number sha1
state	Payment status
created_at	Payment creation timestamp, in milliseconds
paid_at	Payment timestamp, in milliseconds
cancelled_at	Payment cancellation timestamp, in milliseconds
operations	Transaction detail object
operation_type	Type of transaction
id	Transaction id
processing	description of processing
product	Product object
details	Payment details
commission	Commission percentage

Checking of payment status

Method name

This method allows to obtain payment information.

Request example

{
    "jsonrpc": "2.0",
    "method": "receipt.status",
    "id": 2,
    "params": {
        "receipt_id": "<receiver_id>"
    }
}

Request parameters

Parameter name	Description
receipt_id	Receipt ID

Response example

{
    "jsonrpc": "2.0",
    "result": {
        "agent": "<agent>",
        "method": "receipt.status",
        "receipt": {
            "id": "<id>",
            "amount": <amount>,
            "card": {
                "hash": "<hash>",
                "masked_pan": "<masked_pan>",
                "expire": "<expire>",
                "status": 1,
                "full_name": "<full_name>",
                "card_type": <card_type>,
                "processing": "<processing>"
            }, 
            "state": "<state>",
            "created_at": <created_at>,
            "paid_at": <paid_at>,
            "canceled_at": <canceled_at>,
            "operations": [
                {
                    "operation_type": "<operation_type>",
                    "id": "<id>",
                    "processing": "<processing>"
                },
                ...
            ],
            "product": {
              "key": "<key>"
            },
            "details": {},
            "commission": <commission>
        }
    },
    "id": 2
}

Response parameters

Parameter name	Description
agent	Agent name
method	Request type. Takes the value `receipt.status` when created
receipt	Payment receipt object
id	Payment receipt ID
amount	Payment amount in tiyins
card	Card object
hash	Hashed card number. For example: `"1ae168da94f7a148e68b7c481e7e50becd428790"`
masked_pan	Card number in masked string
expire	Card validity period in `“YYMM”` format
status	Card status (1 - “Active”, 2 - “ActiveNoPhone”, 3 - “Blocked”)
full_name	Cardholder's full name
card_type	Card type, for example “Private” or “Corporate”
processing	Processing, for example: “uzcard” or “humo”
state	Payment status
created_at	Payment creation timestamp, in milliseconds
paid_at	Payment timestamp, in milliseconds
cancelled_at	Payment cancellation timestamp, in milliseconds
operations	Transaction detail object
operation_type	Type of transaction
id	Transaction id
processing	description of processing
product	Product object
key	Product Key (for services that allow customer to purchase product keys, such as PUBG keys)
details	Payment details
commission	Commission percentage

Payment cancellation

Method name

Cancellation of payment can be made within a maximum of 1 month after the transaction. If more time passes, cancellation will not be possible.

Request example

{
    "jsonrpc": "2.0",
    "method": "receipt.reverse",
    "id": 2,
    "params": {
        "receipt_id": "<receipt_id>",
        "reason": "<reason>"
    }
}

Request parameters

Parameter name	Description
receipt_id	Receipt ID
reason	Transaction cancellation reason code

Response example

{
    "jsonrpc": "2.0",
    "result": {
        "agent": "<agent>",
        "method": "receipt.reverse",
        "receipt": {
            "id": "<id>",
            "amount": <amount>,
            "card": {
                "hash": "<hash>",
                "masked_pan": "<masked_pan>",
                "expire": "<expire>",
                "status": 1,
                "full_name": "<full_name>",
                "card_type": <card_type>,
                "processing": "<processing>"
            }, 
            "state": "<state>",
            "created_at": <created_at>,
            "paid_at": <paid_at>,
            "canceled_at": <canceled_at>,
            "operations": [
                {
                    "operation_type": "<operation_type>",
                    "id": "<id>",
                    "processing": "<processing>"
                },
                ...
            ],
            "product": {
              "key": "<key>"
            },
            "details": {},
            "commission": <commission>
        }
    },
    "id": 2
}

Response parameters

Parameter name	Description
agent	Agent name
method	Request type. Takes the value `receipt.reverse` when created
receipt	Payment receipt object
id	Payment receipt ID
amount	Payment amount in tiyins
card	Card object
hash	Hashed card number. For example: `"1ae168da94f7a148e68b7c481e7e50becd428790"`
masked_pan	Card number in masked string
expire	Card validity period in `“YYMM”` format
status	Card status (1 - “Active”, 2 - “ActiveNoPhone”, 3 - “Blocked”)
full_name	Cardholder's full name
card_type	Card type, for example “Private” or “Corporate”
processing	Processing, for example: “uzcard” or “humo”
state	Payment status
created_at	Payment creation timestamp, in milliseconds
paid_at	Payment timestamp, in milliseconds
cancelled_at	Payment cancellation timestamp, in milliseconds
operations	Transaction detail object
operation_type	Type of transaction
id	Transaction id
processing	description of processing
product	Product object
key	Product Key (for services that allow customer to purchase product keys, such as PUBG keys)
details	Payment details
commission	Commission percentage

Supplier Payment Showcase

Methods described in this section allow Agents to implement payments for various Suppliers services from own balance:

mobile phone balance replenishment
payment for internet and utilities
refill of game application balances
refill of electronic wallets and other accounts in various systems.

In order for the described methods to work, the agent must provide its IP address to the supervising manager. After the appropriate configuration of the IP address on the gateway side, you can start testing.

URL for running requests:

https://gw.zplat.uz/api/jsonrpc

To make payments, you must top up the Agent's Balance by bank transfer of funds to the agent's deposit account. Details for transfers will be provided by the supervising manager.

The possibility and timing of payment cancellation depends on the Supplier. Payment cancellations can be made within a maximum of 1 month after the transaction. If more time passes, cancellation will not be possible.

Authorization

The basic structure of Headers includes:

Content-Type – String containing the value: application/json; charset=utf-8
Authorization – String containing authorization data in Base64 encoding

Example:

Basic base64(login:key)

The login and key for the agent can be obtained from the payment service administrator.

The system uses HTTP status codes to transmit information about the success or failure of the request.

200 OK - means that the request was successfully processed by the system and no failures occurred while executing the request.

Getting list of services

This method returns a list of available services.

Method name

Request example

{
    "jsonrpc": "2.0",
    "method": "agents.getAvailableServices",
    "id": 2
}

Request parameters

There are no request parameters, and the response contains a list of all available services.

Response example

{
    "jsonrpc": "2.0",
    "result": {
        "services": [
            {
                "name": "netco",
                "title": {
                    "ru": "Netco",
                    "en": "Netco",
                    "uz": "Netco"
                },
                "category": {
                    "name": "internet-providers",
                    "title": {
                        "en": "Internet providers",
                        "ru": "Интернет провайдеры",
                        "uz": "Internet provayderlar"
                    }
                },
                "type": "service",
                "active": false,
                "fraud": false,
                "minAmount": 50000,
                "maxAmount": 200000000,
                "currency": "UZS",
                "fields": [
                    {
                        "name": "account",
                        "regexp": "",
                        "label": {
                            "uz": "Login",
                            "ru": "Логин",
                            "en": "Login"
                        },
                        "required": true
                    },
                    {
                        "name": "amount",
                        "regexp": "/[0-9]/",
                        "label": {
                            "uz": "To`lov summasi",
                            "ru": "Сумма",
                            "en": "Amount"
                        },
                        "required": true
                    }
                ]
            },
            {
                "name": "odnoklassnikiru",
                "title": {
                    "ru": "Odnoklassniki.ru",
                    "en": "Odnoklassniki.ru",
                    "uz": "Odnoklassniki.ru"
                },
                "category": {
                    "name": "social-networks",
                    "title": {
                        "en": "Social networks",
                        "ru": "Социальные сети",
                        "uz": "Ijtimoiy tarmoqlar"
                    }
                },
                "type": "product",
                "active": false,
                "fraud": false,
                "minAmount": 50000,
                "maxAmount": 200000000,
                "currency": "UZS",
                "fields": [
                    {
                        "name": "account",
                        "regexp": "",
                        "label": {
                            "uz": "Login",
                            "ru": "Логин",
                            "en": "Login"
                        },
                        "required": true
                    },
                    {
                        "name": "amount",
                        "regexp": "/[0-9]/",
                        "label": {
                            "uz": "To`lov summasi",
                            "ru": "Сумма",
                            "en": "Amount"
                        },
                        "required": true
                    }
                ]
            }
        ]
    },
    "id": 2
}

Response parameters

Parameter name	Description
name	Service name
title	Object of service names in three languages (ru,en,uz)
category	Service category object
name	Service category name
title	Object of service category names in three languages (ru,en,uz)
type	Supplier type (`service` - service, `product` - product)
active	Service activity
fraud	Antifraud activity for this service
minAmount	Minimum payment amount
maxAmount	Maximum payment amount
currency	Supplier currency
fields	Fields object for the request
name	Field name
regexp	Regular expression for field validation
label	Field names object in three languages (ru,en,uz)
required	Field required

Getting balance

Method name

This method is used to check the agent's deposit balance.

Request example

{
    "jsonrpc": "2.0",
    "method": "agents.getBalance",
    "id": 2,
    "params": {    
    }
}

Request parameters

There are no request parameters, and the response contains the agent's balance.

Response example

{
    "jsonrpc": "2.0",
    "result": {
        "balance": 0,
        "currency": "UZS",
        "max_overdraft": 0
    },
    "id": 2
}

Response parameters

Parameter name	Description
balance	Balance of funds on the Agent's deposit
currency	Agent currency in ISO
max_overdraft	Shows how much money is left before reaching the limit

Getting payment amount

Method name

This method is used for those suppliers who have a fixed payment amount.

Request example

{
    "jsonrpc": "2.0",
    "method": "transactions.products.price",
    "id": 2,
    "params": {
        "service": "twitch-usd-50-us",
    }
}

Request parameters

Parameter name	Description
service	Service name for cost checking

Response example

{
    "jsonrpc": "2.0",
    "result": {
        "price": 5400,
        "currency": "USD",
    },
    "id": 2
}

Response parameters

Parameter name	Description
price	Cost of service (product or service)
currency	Agent currency in ISO

Transaction creation

Method name

When transaction is created, the gateway performs checks, minimizing the risk of error occurring when confirming the transaction.

When this method is called, the system creates new transaction and saves it in the database with the status "0" (New Transaction). After receiving a successful response, you can submit translation confirmation request.

Important! The created transaction lifetime before automatic deletion is 30 minutes. If confirmation request is not received within 30 minutes after the transaction is created, then it goes into the status "-1" (Deleted) and further operations with it will be impossible.

Request example

{
    "id": 123,
    "jsonrpc": "2.0",
    "method": "transactions.create",
    "params": {
        "service": "pubg-60-uc",
        "account": "<account>",
        "amount": 123456,
        "ext_id": "<agent-request-id>"
    }
}

Request parameters

Parameter name	Description
service	Service code
account	The account to which the top-up is requested
amount	Account refilling amount in tiyins
ext_id	Agent Transaction ID

Response example

{
    "jsonrpc": "2.0",
    "result": {
        "method": "create",
        "receipt": {
            "id": "62b4d1046b3b706f362f7071",
            "numeric_id": "1656017156613258196",
            "ext_id": "<agent-request-id>",
            "agent": "<agent-login>",
            "service": "<service>",
            "service_account": "<account>",
            "agent_amount": 123456,
            "agent_currency": "UZS",
            "converted": false,
            "exchange_rate": 1,
            "commission_rate": 10,
            "calculated_commission": 1235,
            "provider_amount": 122221,
            "provider_currency": "UZS",
            "service_currency": "UZS",
            "service_exchange_rate": 1,
            "service_to_accrual": 122221,
            "created_at": 1656017156613,
            "paid_at": 0,
            "canceled_at": 0,
            "state": 0,
            "mode": "PROD",
            "voucher": null,
            "commission_in_uzs": 1235,
            "x_request_id_create": "3d636101-61bc-4677-9ec9-795e140266a4"
        }
    },
    "id": 123
}

Response parameters

Parameter name	Description
method	Request type
receipt	payment invoice object
id	Unique transaction identifier generated by the gateway
numeric_id	Alternative identifier format generated by the gateway
ext_id	Unique transaction identifier generated on the agent side
agent	Login of the agent who created the transaction
service	Unique service name
service_account	Account/login/phone number indicating the recipient of funds
agent_amount	Amount sent in agent request
agent_currency	Agent currency specified in the contract
converted	Indicates whether the request amount was converted on the payment gateway side itself before being sent to the service provider
exchange_rate	If the agent's currency and the service provider's currency are different, the field will indicate the exchange rate at which the conversion took place
commission_rate	Commission percentage deducted from the request amount
calculated_commssion	The amount in the agent's currency that was deducted from the request amount
provider_amount	The final amount that will be sent to the service provider after deducting all fees in the provider's currency
provider_currency	Currency accepted by the service provider
service_currency	The currency the provider works with may differ from the currency of the final service, and in such cases the conversion occurs on the side of the service provider. This field indicates the currency of the final service
service_exchange_rate	Conversion rate on the provider side
service_to_accrual	The final amount in currency of the service that will be credited to the account
created_at	UNIX timestamp, the date of transaction creation on the system, in milliseconds
paid_at	UNIX timestamp, date of successful processing of the provider request, in milliseconds
canceled_at	UNIX timestamp, transaction cancellation date, in milliseconds
state	Transaction status code
mode	Test check (TEST) or production check (PROD)
voucher	Information about the purchased voucher, if the service provides them
commission_in_uzs	Commission amount received by the gateway (required for agents on the territory of the Republic of Uzbekistan)
x_request_id_create	UUID of request to create transaction from an agent registered in the gateway

Transaction confirmation

Method name

The response to payment request can vary from 1-2 seconds to 60 seconds depending on the provider response time. If response is not received within 60 seconds, then it is necessary to check the payment status at recommended interval of 30 seconds until the final status is received.

Request example

{
    "jsonrpc": "2.0",
    "method": "transactions.pay",
    "id": 2,
    "params": {
        "receipt_id": "62b4d1046b3b706f362f7071",
        "card_hash": "FF998ABC1CE6D8F01A675FA197368E44C8916E9C"
    }
}

Request parameters

Parameter name	Description
receipt_id	Method ID obtained from the `transactions.create` request
card_hash	SHA1 hash of the card or Agent account number

Response example

{
    "jsonrpc": "2.0",
    "result": {
        "method": "pay",
        "receipt": {
            "id": "62b4d1046b3b706f362f7071",
            "numeric_id": "1656017156613258196",
            "ext_id": "<agent-request-id>",
            "agent": "<agent-login>",
            "service": "<service>",
            "service_account": "<account>",
            "agent_amount": 123456,
            "agent_currency": "UZS",
            "converted": false,
            "exchange_rate": 1,
            "commission_rate": 10,
            "calculated_commission": 1235,
            "provider_amount": 122221,
            "provider_currency": "UZS",
            "service_currency": "UZS",
            "service_exchange_rate": 1,
            "service_to_accrual": 122221,
            "created_at": 1656017156613,
            "paid_at": 1656017153678,
            "canceled_at": 0,
            "state": 4,
            "mode": "PROD",
            "voucher": null,
            "commission_in_uzs": 1235,
            "x_request_id_create": "3d636101-61bc-4677-9ec9-795e140266a4",
            "x_request_id_pay": "6e6653fa-5694-435a-ac0e-358a08ac8f10",
            "fiscal_url": "https://ofd.soliq.uz/epi",
        }
    },
    "id": 123
}

Response parameters

Parameter name	Description
method	Request type
receipt	Created payment object
id	Unique transaction identifier generated by the gateway
numeric_id	Alternative identifier format generated by the gateway
ext_id	Unique transaction identifier generated on the agent side
agent	Login of the agent who created the transaction
service	Unique service name
service_account	Account/login/phone number indicating the recipient of funds
agent_amount	Amount sent in agent request
agent_currency	Agent currency specified in the contract
converted	Indicates whether the request amount was converted on the payment gateway side itself before being sent to the service provider
exchange_rate	If the agent's currency and the service provider's currency are different, the field will indicate the exchange rate at which the conversion took place
commission_rate	Commission percentage deducted from the request amount
calculated_commssion	The amount in the agent's currency that was deducted from the request amount
provider_amount	The final amount that will be sent to the service provider after deducting all fees in the provider's currency
provider_currency	Currency accepted by the service provider
service_currency	The currency the provider works with may differ from the currency of the final service, and in such cases the conversion occurs on the side of the service provider. This field indicates the currency of the final service
service_exchange_rate	Conversion rate on the provider side
service_to_accrual	The final amount in currency of the service that will be credited to the account
created_at	UNIX timestamp, the date of transaction creation on the system, in milliseconds
paid_at	UNIX timestamp, date of successful processing of the provider request, in milliseconds
canceled_at	UNIX timestamp, transaction cancellation date, in milliseconds
reason	Transaction cancellation reason code
mode	Test check (TEST) or production check (PROD)
state	Transaction status code
voucher	Information about the purchased voucher, if the service provides them
commission_in_uzs	Commission amount received by the gateway (required for agents on the territory of the Republic of Uzbekistan)
x_request_id_create	UUID of request to create transaction from an agent registered in the gateway
x_request_id_pay	UUID of transaction confirmation request from an agent registered in the gateway
fiscal_url	URL to receive a fiscal receipt

Getting transaction status

To obtain the status of a previously created transaction, a request is used, in which parameter receipt_id is passed as a unique transaction identifier in the payment gateway system.

This method returns the status, as well as actual information on the requested transaction. Using this method, you can find out how the transaction was completed, namely, completed payment, return, error, cancellation or other options.

Method name

Request example

{
    "jsonrpc": "2.0",
    "method": "transactions.status",
    "id": 2,
    "params": {
        "receipt_id": "6227ff43c89320fb4e4c5e32"
    }
}

Request parameters

Parameter name	Description
receipt_id	Method ID obtained from the `transactions.pay` request

Response example

{
    "jsonrpc": "2.0",
    "result": {
        "method": "status",
        "receipt": {
            "id": "62b4d1046b3b706f362f7071",
            "numeric_id": "1656017156613258196",
            "ext_id": "<agent-request-id>",
            "agent": "<agent-login>",
            "service": "<service>",
            "service_account": "<account>",
            "agent_amount": 123456,
            "agent_currency": "UZS",
            "converted": false,
            "exchange_rate": 1,
            "commission_rate": 10,
            "calculated_commission": 1235,
            "provider_amount": 122221,
            "provider_currency": "UZS",
            "service_currency": "UZS",
            "service_exchange_rate": 1,
            "service_to_accrual": 122221,
            "created_at": 1656017156613,
            "paid_at": 1656017153678,
            "canceled_at": 0,
            "state": 4,
            "mode": "PROD",
            "voucher": null,
            "commission_in_uzs": 1235,
            "x_request_id_create": "3d636101-61bc-4677-9ec9-795e140266a4",
            "x_request_id_pay": "6e6653fa-5694-435a-ac0e-358a08ac8f10",
            "fiscal_url": "https://ofd.soliq.uz/epi",
        }
    },
    "id": 123
}

Response parameters

Parameter name	Description
method	Request type
receipt	Created payment object
id	Unique transaction identifier generated by the gateway
numeric_id	Alternative identifier format generated by the gateway
ext_id	Unique transaction identifier generated on the agent side
agent	Login of the agent who created the transaction
service	Unique service name
service_account	Account/login/phone number indicating the recipient of funds
agent_amount	Amount sent in agent request
agent_currency	Agent currency specified in the contract
converted	Indicates whether the request amount was converted on the payment gateway side itself before being sent to the service provider
exchange_rate	If the agent's currency and the service provider's currency are different, the field will indicate the exchange rate at which the conversion took place
commission_rate	Commission percentage deducted from the request amount
calculated_commssion	The amount in the agent's currency that was deducted from the request amount
provider_amount	The final amount that will be sent to the service provider after deducting all fees in the provider's currency
provider_currency	Currency accepted by the service provider
service_currency	The currency the provider works with may differ from the currency of the final service, and in such cases the conversion occurs on the side of the service provider. This field indicates the currency of the final service
service_exchange_rate	Conversion rate on the provider side
service_to_accrual	The final amount in currency of the service that will be credited to the account
created_at	UNIX timestamp, the date of transaction creation on the system, in milliseconds
paid_at	UNIX timestamp, date of successful processing of the provider request, in milliseconds
canceled_at	UNIX timestamp, transaction cancellation date, in milliseconds
reason	Transaction cancellation reason code
mode	Test check (TEST) or production check (PROD)
state	Transaction status code
voucher	Information about the purchased voucher, if the service provides them
commission_in_uzs	Commission amount received by the gateway (required for agents on the territory of the Republic of Uzbekistan)
x_request_id_create	UUID of request to create transaction from an agent registered in the gateway
x_request_id_pay	UUID of transaction confirmation request from an agent registered in the gateway
fiscal_url	URL to receive a fiscal receipt

Transactions checking

This method is used to query transactions for specific date. The response includes a list of transactions, divided into groups (pages) for display.

Method name

Request example

{
    "jsonrpc": "2.0",
    "method": "transactions.check",
    "id": 2,
    "params": {
        "date": 1680524563287,
        "page": 0
    }
}

Request parameters

Parameter name	Description
date	UNIX timestamp, check date
page	Starts with "0"

Response example

{
    "jsonrpc": "2.0",
    "result": {
        "pages": 15,
        "page": 0,
        "receipts": [
            {
                "_id": "642ac54d9017b321f8550bb7",
                "agent_transaction": "642ac5473cc6b94fc24ee816",
                "agent_amount": 614500000,
                "agent_currency": "UZS",
                "created_at": 1680524621948,
                "paid_at": 1680524627228,
                "canceled_at": 0,
                "mode": "PROD",
                "state": "4",
                "params": {
                    "account": "2586",
                    "amount": 6145000
                }
            },
            ….,
        ]
    },
    "id": 2
}

Response parameters

Parameter name	Description
pages	Total number of transactions in the request
page	Current transaction number in order
_id	Unique transaction ID generated by the payment gateway
agent_transaction	Unique transaction identifier generated on the agent side
agent_amount	Amount sent in agent request
agent_currency	Agent currency specified in the contract
created_at	UNIX timestamp, the date of transaction creation on the system, in milliseconds
paid_at	UNIX timestamp, date of successful processing of the provider request, in milliseconds
canceled_at	UNIX timestamp, transaction cancellation date, in milliseconds
mode	Depending on the `is_test` field in the service itself, it takes the value TEST or PROD
state	Transaction status code
params	Fields sent by agent

Test transaction creating

Method name

When creating a test transaction, no request is made to the provider, or the provider's test environment is used. All method logic follows the transactions.create method, but payments made using this method are not included in the reconciliation.

Test transaction confirmation

Method name

All the logic of this method matches the [transactions.pay] method (#transaction-confirmation).

Payments to UzCard/HUMO

Methods described in this module allow you to implement cash payments to bank cards issued in the Republic of Uzbekistan.

In order for the methods described in this section to work, the agent must provide its IP address. After the appropriate configuration of the IP address on the gateway side, you can start testing.

URL for running requests:

https://gateway.zplat.uz/api/jsonrpc

Authorization

The basic structure of Headers includes:

Content-Type – String containing the value: application/json; charset=utf-8
Authorization – String containing authorization data in Base64 encoding

Example:

Basic base64(login:key)

The login and key for the agent can be obtained from the payment service administrator.

The system uses HTTP status codes to transmit information about the success or failure of the request.

200 OK - means that the request was successfully processed by the system and no failures occurred while executing the request.

Payment preparation

Method name

Method for creating a preliminary payment transaction to a card in the Service.

Request example

{
    "jsonrpc": "2.0",
    "method": "epos2card.v2.create",
    "id": 2,
    "params": {
        "card": {
            "pan": "8600303655375959"
        },
        "ext_id": "local-1034",
        "amount": 1,
        "sender": "nizom",
        "sender_ip": "192.168.1.1"
    }
}

Request parameters

Parameter name	Description
card	Card object
pan	Card number
ext_id	Transaction ID generated on the agent side
amount	Refilling amount in tiyins
sender	Sender, including all its parameters
sender_ip	Sender's IP address

Response example

{
    "jsonrpc": "2.0",
    "id": 2,
    "result": {
        "agent": "merchant-gw",
        "method": "epos2card.v2.create",
        "receipt": {
            "id": "65a7ae272a2e716059b6d276",
            "amount": 100,
            "state": "0",
            "created_at": 1705487911212,
            "paid_at": 0,
            "cancelled_at": 0,
            "receiver": {
                "card": {
                    "id": "659fb6e0f3560a518842691d",
                    "processing": "uzcard",
                    "masked_pan": "8600**********59"
                }
            }
        }
    }
}

Response parameters

Parameter name	Description
receipt	payment receipt object
id	Payment receipt ID
amount	Payment amount in tiyins
state	Payment status
created_at	Payment creation timestamp, in milliseconds
paid_at	Payment timestamp, in milliseconds
canceled_at	Payment cancellation timestamp, in milliseconds
receiver	Payee data object
card	Recipient card object
id	Card ID
processing	Name of card processing (UZCARD, HUMO)
masked_pan	Card number in masked string

Payment confirmation

Method name

Method for confirming payment transaction to a card.

Request example

{
    "jsonrpc": "2.0",
    "method": "epos2card.v2.confirm",
    "id": 2,
    "params": {
        "receipt_id": "659fb79b0080bb7867c03ad5"
    },
}

Request parameters

Parameter name	Description
receipt_id	Payment ID

Response example

{
    "jsonrpc": "2.0",
    "id": 2,
    "result": {
        "agent": "merchant-gw",
        "method": "epos2card.v2.confirm",
        "receipt": {
            "id": "659fb79b0080bb7867c03ad5",
            "amount": 100,
            "state": "4",
            "created_at": 1704966043081,
            "paid_at": 0,
            "cancelled_at": 0,
            "receiver": {
                "card": {
                    "id": "659fb6e0f3560a518842691d",
                    "processing": "uzcard"
                }
            }
        }
    },
}

Response parameters

Parameter name	Description
receipt	payment receipt object
id	Payment receipt ID
amount	Payment amount in tiyins
state	Payment status
created_at	Payment creation timestamp, in milliseconds
paid_at	Payment timestamp, in milliseconds
canceled_at	Payment cancellation timestamp, in milliseconds
receiver	Payee data object
card	Recipient card object
id	Card ID
processing	Name of card processing (UZCARD, HUMO)

Status checking

Method name

Method for payment status checking.

Request example

{
    "jsonrpc": "2.0",
    "method": "epos2card.v2.status",
    "id": 2,
    "params": {
        "receipt_id": "659fb79b0080bb7867c03ad5"
    },
}

Request parameters

Parameter name	Description
receipt_id	Payment ID

Response example

{
    "jsonrpc": "2.0",
    "id": 2,
    "result": {
        "agent": "merchant-gw",
        "method": "epos2card.v2.status",
        "receipt": {
            "id": "659fb79b0080bb7867c03ad5",
            "amount": 100,
            "state": "4",
            "created_at": 1704966043081,
            "paid_at": 0,
            "cancelled_at": 0,
            "receiver": {
                "card": {
                    "id": "659fb6e0f3560a518842691d",
                    "processing": "uzcard"
                }
            }
        }
    },
}

Response parameters

Parameter name	Description
receipt	payment receipt object
id	Payment receipt ID
amount	Payment amount in tiyins
state	Payment status
created_at	Payment creation timestamp, in milliseconds
paid_at	Payment timestamp, in milliseconds
canceled_at	Payment cancellation timestamp, in milliseconds
receiver	Payee data object
card	Recipient card object
id	Card ID
processing	Name of card processing (UZCARD, HUMO)

Fiscalization

Fiscalization is the process of financial transactions registration in the State Tax Committee system in order to ensure transparency, preventing tax evasion and ensure compliance with tax legislation.

URL for running requests:

https://gw.zplat.uz/api/jsonrpc

Authorization

The basic structure of Headers includes:

Content-Type – String containing the value: application/json; charset=utf-8
Authorization – String containing authorization data in Base64 encoding

Example:

Basic base64(login:key)

The login and key for the agent can be obtained from the payment service administrator.

The system uses HTTP status codes to transmit information about the success or failure of the request.

200 OK - means that the request was successfully processed by the system and no failures occurred while executing the request.

Receipts registration

Method name

This method allows transactions fiscalization.

Request example

{
    "jsonrpc": "2.0",
    "method": "ofd.register",
    "id": 123,
    "params": {
        "receipt_type": 0,
        "receipt_id": "64a2aae138480f57b14d66ac",
        "items": [
            {
                "ikpu_name": "Services for transporting passengers by air (air transportation) to international destinations",
                "ikpu": "11201001001000000",
                "package_code": "1500729",
                "inn": "60000000",
                "count": 2,
                "nds": "0",
                "amount": 100000
            }
        ]
    }
}

Request parameters

Parameter name	Description
receipt_type	Type of receipt in State Tax Committee (Sale/Return = 0)
receipt_id	ZPLAT transaction ID
items	Group of receipt parameters
ikpu_name	Name of the service in the State Tax Committee
ikpu	IKPU code number in the State Tax Committee
package_code	Packaging code in the State Tax Committee
inn	Company TIN
count	Number of services in the State Tax Committee receipt
nds	VAT
amount	Amount in tiyins

Response example

{
    "jsonrpc": "2.0",
    "result": {
        "method": "register",
        "result": {
            "receipt_id": "64a2aae138480f57b14d66ac",
            "is_refund": 0,
            "message": "accepted",
            "receipt_type": 0,
            "receipt_name": "Sale/Return",
            "terminal_id": "EP000000000000",
            "fiscal_sign": "60000000",
            "qr_code_url": "https://ofd.soliq.uz/epi?t=EP000000000000&r=0000000&c=000000000000&s=000000000000",
            "date_time": "20240228140406",
            "items": [
                {
                    "ikpuName": "Services for transporting passengers by air (air transportation) to international destinations",
                    "ikpu": "11201001001000000",
                    "packageCode": "000000000000",
                    "inn": "000000000000",
                    "count": 2,
                    "nds": "0",
                    "amount": 100000
                }
            ]
        }
    },
    "id": 123
}

Response parameters

Parameter name	Description
receipt_id	ZPLAT transaction ID
is_refund	0 not cancelled, 1 canceled
message	Text of the response from the State Tax Committee
receipt_type	Type of receipt in the State Tax Committee - Sale/Return = 0
receipt_name	Name of the receipt "Sale/Return"
terminal_id	Terminal identification
fiscal_sign	Fiscal value from State Tax Committee
qr_code_url	Link to receipt from State Tax Committee
date_time	Time of fiscalization
items	Group of receipt parameters
ikpu_name	Name of the service in the State Tax Committee
ikpu	IKPU code number in the State Tax Committee
package_code	Packaging code in the State Tax Committee
inn	Company TIN
count	Number of services in the State Tax Committee receipt
nds	VAT
amount	Amount in tiyins transferred to the State Tax Committee

Payment statuses

Statuses described in this section can be returned in the state field of methods, and indicate the payment status.

The status descriptions are listed below:

Status	Meaning	Description	Sign of fatality
0	Created	Transaction created in Zplat	no
1	Paid	Client transferred money to Zplat, the supplier has not yet received payment	no
2	Suspended	Client transferred money to Zplat, gateway attempted to transfer money to supplier, but no response was received from the supplier. Transaction pending manual review	no
3	In carrying out	Client transferred money to Zplat, gateway attempted to transfer money to supplier, but no response was received from supplier. Transaction awaiting automatic execution	no
4	Successful	Transaction was completed successfully. Supplier received payment	yes
-1	Deleted	Payment was not executed by client, transaction was deleted due to timeout	yes
-2	In process of cancellation	Request to cancel the payment has been sent to Supplier, but no response has been received from Supplier regarding the successful cancellation of the payment	no
-3	Canceled	Successful cancellation of payment on the supplier side	yes
-4	Unable to carry out	Transaction was not created for this supplier	yes
-5	Payment returned	Successful payment return on the supplier side	yes

Error codes

Error descriptions are listed below:

Error code	Meaning	Description
-32700	ParseError	The server received invalid JSON. An error occurred on the server while parsing JSON text
-32600	InvalidRequest	The JSON sent is not a valid request object
-32601	MethodNotFound	Method does not exist/is not available
-32602	InvalidParams	Invalid method parameters
-32603	InternalError	Internal system error
-32200	AccessDenied	Access is denied
-32210	AgentNotFound	Agent not found
-32211	AgentDisabled	Agent is not active
-32212	AgentDepositNotEnough	The agent's balance is not sufficient to carry out this operation. Please top up your balance and try again
-32220	ServiceNotFound	Service not found
-32221	ServiceDisabled	The service is disabled
-32222	ServiceArchived	Archived service
-32223	ServiceNotAllowed	The service is not allowed for this agent. To activate the service, contact the administrator
-32224	ServiceDisabledForAgent	The service is disabled for this agent. To activate the service, contact the administrator
-32225	ServiceAmountIsLessThanAllowed	The payment amount is less than acceptable
-32226	ServiceAmountIsHigherThanAllowed	The payment amount is more than allowed
-32227	ServiceInvalidParams	This service is not configured correctly. Contact your system administrator
-32230	GatewayNotFound	Gateway not found
-32231	GatewayDisabled	Gateway disconnected
-32232	GatewayNotResponding	Gateway is not responding
-32233	GatewayRequestFailed	Gateway request failed
-32234	GatewayTransactionFailed	Gateway was unable to create a successful transaction
-32240	ReceiptNotFound	Receipt not found
-32241	ReceiptModeIsWrong	Receipt type does not allow you to perform the operation
-32242	ReceiptStateIsWrong	Incorrect receipt status for transaction
-32243	ReceiptIsNotReversible	Receipt is irreversible
-32250	AntiFraudDailyAmountReached	The daily account refill limit has been exceeded
-32251	AntiFraudDailyTransactionsReached	The daily account refill limit for the number of transactions has been exceeded
-32252	AntiFraudMonthlyAmountReached	The monthly account refill limit has been exceeded
-32253	AntiFraudMonthlyTransactionsReached	The monthly account refill limit for the number of transactions has been exceeded
-32254	AntiFraudPauseTimeForSecondTransaction	Time must pass between the first and second account refilling
-32255	AntiFraudPauseTimeForOtherTransactions	Not enough time has passed since the last top-up of your account
-32260	CardNotFound	Card not found. The card number may have been entered incorrectly
-32261	CardWrongNumber	Invalid card number
-32262	CardBlocked	Card deleted or blocked
-32263	CardNotVerifiedForAgent	Card not verified for this agent
-32264	CardAlreadyVerifiedForAgent	The card has already been verified for this agent
-32265	CardBlockedForTransfer	The card is blocked. Transfer of funds is not available
-32266	CardPhoneNotMatch	The phone number is not connected to this card
-32370	QuantityNotAvailable	Quantity not available
-32380	CurrencyRateRequestFailed	Request to get the exchange rate gave an error
-32390	CalculationFailed	Calculation failed
-32391	CalculationAgentAmountError	Agent amount calculation error
-32400	InternalSystemError	System (internal error)
-32404	AccountNotFound	Account not found
-32410	ProcessingNotFound	Processing not found
-32411	ProcessingDisabled	Processing disabled
-32412	ProcessingNotResponding	Processing did not respond
-32413	ProcessingRequestFailed	The processing request generated an error
-32414	ProcessingTransactionFailed	Processing was unable to create successful transaction
-32415	ProcessingAlreadyDone	Processing has already carried out this transaction
-32420	EposNotFound	Epos not found
-32421	EposModeIsWrong	Epos type does not correspond to the requested operation
-32430	TransactionStateIsWrong	Incorrect transaction status for the operation
-32431	CanNotPerformTransaction	Transaction cannot be completed
-32432	TransactionCanceled	Transaction was canceled
-32433	TransactionError	Transaction has an error
-32434	TransactionInProgress	Try again later! Transaction is in progress
-32440	Verification Expire	Verification period has expired
-32441	VerificationAttemptsLimitReached	Verification attempt limit reached
-32442	VerificationAlreadyPassed	Verification has already passed
-32443	VerificationNotMatch	Verification does not match
-32444	VerificationSmsAlreadySend	Confirmation SMS has already been sent
-32446	CategoryNotFound	Category not found
-32447	CallAnotherMethod	Call another method
-32448	OTP resend limit per minute reached	OTP resend limit per minute reached
-32449	OTP resend limit attempts reached	OTP resend attempt limit reached
-32450	PhoneNumberNoMatch	Phone number verification error

Introduction

Terms and abbreviations

General principles

RPC Request

RPC Response

Example of an RPC Request that failed

Acquiring (widget)

Widget genetation

Payment information

Method name

Payment confirmation

Method name

Payment notification

Method name

Payment cancellation

Method name

Checking for cancellation

Method name

Widget error codes

Acquiring (host-to-host)

Authorization

Payment creation

Method name

Request parameters

Response parameters

Payment with confirmation

Method name

Request parameters

Response parameters

OTP code transmit

Method name

Request parameters

Response parameters

Holding funds

Method name

Request parameters

Response parameters

Checking of payment status

Method name

Request parameters

Response parameters

Payment cancellation

Method name

Supplier Payment Showcase

Authorization

Getting list of services

Method name

Request parameters

Response parameters

Getting balance

Method name

Request parameters

Response parameters

Getting payment amount

Method name

Request parameters

Response parameters

Transaction creation

Method name

Request parameters

Response parameters

Transaction confirmation

Method name

Request parameters

Response parameters

Getting transaction status

Method name

Request parameters

Response parameters

Transactions checking

Method name

Request parameters

Response parameters

Test transaction creating

Method name

Test transaction confirmation

Method name

Payments to UzCard/HUMO

Authorization

Payment preparation