Overview

Description

The Installment Service lets a merchant offer customers payment by installment, loan or any other pay-later product: the merchant submits an order and the customer's phone number and receives a tokenized redirect link for checkout; application status changes are delivered by webhook.

Request Header:

Name	Value	Description
X-Request-Id	uuid v7	Unique request Id
Content-type	application/json	Request body format
X-JWS-Signature	string	Request signature
Accept	application/json	Request body format

Response Header:

Name	Value	Description
X-Request-Id	uuid v7	Unique request Id
X-Datetime	datetime	Date and time of request processing
X-Request-Status	string	Request body format

Generating the X-JWS-Signature

To send any request, a request signature must be generated using JWS technology.
The JWS format must include the mandatory blocks header and signature and should be passed in the request header X-JWS-Signature.

Header structure

{
    "uri": "/v5/installment/applications",
    "auth_id": "12345", 
    "method": "POST",
    "params": "" 
    "alg": "HS256"
}

Header description:

Field	Description	Field requirement
uri	The path to the API endpoint being called	Required
params	Reserved field	Required
method	Request method	Required
auth_id	User ID for signature verification	Required
alg	Encryption algorithm	Required

Payload structure

The payload for generating JWS includes the HTTP request body.
The supported signature encryption algorithm is HS256, and the merchant's secret_key should be used as the signing key.

{
    "external_id": "TGR1234",
    "total_amount": 1500000,
    "currency": "UZS",
    "goods": [
        {
            "name": "Смартфон Xiaomi Poco F3 256/8GB",
            "price": 1500000,
            "quantity": 1,
            "category": "electronics"
        }
    ],
    "customer": {
        "phone": "eyJhbGciOiJQQkVTMi1IUzUxMitBMjU2S1ciLCJlbmMiOiJBMjU2R0NNIiwicDJzIjoiLi4uIiwicDJjIjo2NTUzNn0....."
    },
    "callback_url": "https://shop.uz/fp/status-callback"
}

Generated JWS:

eyJwYXRoIjoiL3Y1L21lcmNoYW50L2ludm9pY2UvaW5pdCIsIm1lcmNoYW50X2lkIjoxMjM0NTYsIm1ldGhvZCI6IlBPU1QiLCJwYXJhbXMiOiIiLCJhbGciOiJIUzUxMiJ9..wCwFCAmxN0nbTm6mad8GxowIjgkCwfF7IAy2ijO9thLjsZFXnS4K_I4NPnXjkTFTMnEzqjk8rtIVmtf7NbGyvg

Errors

The service reports errors in three ways:

HTTP status	Meaning	When it occurs
422	Validation error	Invalid phone/JWE, invalid composition, amount outside the limits, or `total_amount` ≠ Σ(`price` × `quantity`)
500	Internal server error	Unexpected server-side failure
200	OK	On success; a business-level error may additionally be reported in the body via `error_code` / `error_description` (see below)

On a 200 response the following optional fields may be returned:

Name	Description	Data type	Field requirement
error_code	Error code ID	integer	Optional
error_description	Text description of the error (≤ 255 characters)	string	Optional

Error codes:

error_code	Description
1001	Invalid request
1002	Application not found
1003	Invalid status transition
1004	Application processing error

Description#

Request Header:#

Response Header:#

Generating the X-JWS-Signature#

Header structure#

Payload structure#