Developer Guide: Paynet Integration (Developer Portal)

Welcome to the Paynet Developer Portal! Our platform is an aggregator of service providers and merchants, providing convenient ways to accept payments.

We offer 3 connection options. Use the diagram below to determine the appropriate option.

1. Choosing Integration Type

How to choose? (Decision Tree)

Model Comparison

What is required from you for each model

✅ Universal Billing — no development:

• ✅ List of fields for the payment form (e.g., phone, full name, account number)
• ✅ Telegram account or Foyda login to receive notifications
• ❌ API not required
• ❌ Server not required
• ❌ Developer not required

⚙️ UWS Connector — API implementation required:

• ✅ Implement JSON-RPC 2.0 methods on your server
• ✅ Web service URL, login and password (HTTP Basic Auth)
• ✅ List of services and their serviceId (filled out in the "Technical interaction procedure" form)
• ✅ Open IP access for Paynet servers

[!NOTE] What is serviceId? serviceId is a static internal identifier of your service, which you come up with yourself and provide to us in the "Technical interaction procedure" document. It is NOT the client's phone number or personal account number (this data is passed in the fields array). One partner can provide multiple services, and serviceId helps Paynet understand exactly which service the client is paying for.

⚠️ This is NOT your option if...

2. Architecture and Processes (Sequence Diagrams)

[!IMPORTANT] Architectural Paradigm (Unidirectionality) UWS integration works on a Push/Pull model, where Paynet always acts as the client, and your billing as the server. You do not make requests to the Paynet API. All interactions (including checks and cancellations) are initiated exclusively from Paynet servers to your Endpoint.

Integration via UWS (Universal Connector)

Main scenario of a successful payment:

Scenario 1: Network Timeout:

Scenario 2: Transaction Cancellation (CancelTransaction):

Universal Billing

Paynet processes all logic independently and only notifies the merchant.

3. Data Requirements, Security and Idempotency

3.1 Data Formats and Currency

[!WARNING] Errors in these points are the most frequent cause of failures during the testing phase.

• Protocol: HTTP 1.1, POST method, TLS v1.3 (HTTPS) protection.
• Encoding and Headers: All requests are sent and received in UTF-8 encoding. It is mandatory to use Content-Type: application/json and Accept: application/json.
• Currency (amount): All financial operations are transmitted in tiyins (1 sum = 100 tiyins, integer). For example, 10,000 sum = 1000000.
• Date Format: Strictly YYYY-MM-dd HH:mm:ss. Time zone — GMT+5 (Uzbekistan).

[!CAUTION] The only exception to the date format: the timestamp parameter in the CheckTransaction request arrives in the format EEE MMM dd HH:mm:ss z yyyy, e.g. Mon Jun 16 06:12:41 UZT 2021. This format is fixed historically (many providers already operate with it) and will not change — your parser must support it. All other dates, including timestamp in CancelTransaction and all responses from your server, use the standard format YYYY-MM-dd HH:mm:ss.

3.2 Authorization and Security

• HTTP Basic Auth: Requests from Paynet are protected by basic authentication. If the login/password pair is missing or incorrect, your server must return HTTP 401 Unauthorized (and not 200 OK with an error).
• Password Rotation: If you have implemented the optional ChangePassword method, Paynet must change the password upon the first successful connection to your billing. If the method is not implemented, the password is transmitted separately via any secure channels.
• IP Whitelisting: Access to your API must be open only for: 213.230.106.112/28 and 213.230.65.80/28.

3.3 Idempotency and Timeouts

Financial transactions require strict consistency:

• Timeouts: Your system must process a transaction for no longer than 500 ms. Processing up to 1 sec is allowed, but for no more than 30 minutes per day. If a response is not received within 30 seconds, Paynet terminates the connection by timeout. In case of systematic violation of these limits, Paynet may disconnect the provider from the payment acceptance system until the cause is fully eliminated.
• Idempotency (transactionId): Each transaction from Paynet has a unique transactionId. The partner's billing must not allow double debits for the same transactionId: return error 201 for a duplicate — after that, Paynet will call CheckTransaction to learn the original result. In case of network failures, Paynet may repeat the request or call the CheckTransaction method. In response to a successful operation, the partner returns its internal number providerTrnId.

4. Operations: Reconciliation and SLA

• Daily Reconciliation: Settlements are checked every day. Paynet automatically calls the GetStatement method to get a list of successful payments on your side and compares them with its database. A register of accepted payments is also sent to the partner's email.
• Maintenance Work (SLA): In case of scheduled maintenance work or equipment updates, the partner is obliged to notify Paynet technical support no later than 2 weeks before the start of the work. Unforeseen failures must be reported immediately; if a failure is not resolved within one business day, the partner must communicate the resolution deadline.

5. OpenAPI Specification for UWS

The specification is available in the file OpenAPI (UWS) in English.yaml. It includes a description of all JSON-RPC 2.0 methods: GetInformation, PerformTransaction, CheckTransaction, CancelTransaction, GetStatement, ChangePassword (optional), as well as strict JSON schemas, error codes, and formats.

6. Onboarding and Testing Guide (UWS)

To start accepting payments via the universal connector (UWS), follow these steps:

Step 1: Infrastructure Preparation

• API Implementation: Implement the mandatory methods (GetInformation, PerformTransaction, CheckTransaction, CancelTransaction, GetStatement) according to the specification.
• Protocol Support: Ensure support for HTTPS (TLS v1.3) and the JSON-RPC 2.0 data exchange format (HTTP POST method).
• Network Access (IP Whitelisting): Open access to your billing only for permitted Paynet IP addresses.
• TAS-IX: Ensure that your connection with Paynet servers is carried out through the TAS-IX network.

Step 2: Application Completion (Questionnaire)

Provide the Paynet manager with the following information:

• Web service URL: (e.g., https://api.yourdomain.uz/uws)
• Username and Password: For HTTP Basic Authentication
• List of services: List of serviceIds and their names
• Email: Address for daily registers

Step 3: Testing and Test Cases

Before launching, standard test cases must be executed:

1. Subscriber verification (GetInformation): Emulation of successful subscriber search and emulation of 302 (Client not found) error.
2. Payment execution (PerformTransaction): Successful top-up of the subscriber's balance.
3. Limits (PerformTransaction): Emulation of 413 (Invalid amount) or 101 (Quota exhausted) error.
4. Cancellation (CancelTransaction): Execution of a test payment and its full cancellation. Refund of funds (partial refunds are not technically supported). Emulation of errors 77 (client has already spent the funds), 306 (reporting period closed) and 203 (transaction not found).
5. Status check (CheckTransaction): Checking the status of an existing transaction (state 1) and a non-existent one (state 3, a success envelope — not an error). Be sure to test parsing of timestamp in the EEE MMM dd HH:mm:ss z yyyy format.

Step 4: Launch into Production (Go-Live)

After successfully passing all tests, an act of technical readiness is signed, and your services become available for payment to millions of Paynet users!

7. Paynet Error Codes Reference

When a business error occurs, the partner's billing returns a JSON-RPC response with an error object containing code and message.

[!IMPORTANT] All codes in this section (201, 412, 413, etc.) are Paynet error codes at the JSON-RPC level, not HTTP statuses. They are frequently mistaken for HTTP codes: in fact they are returned inside the error object in the response body, while the HTTP status of the response itself stays 200 OK. The only exception is authentication: invalid login/password returns HTTP 401 Unauthorized (see the note on error 412 below).

Business Error Mapping Table

Use this table to understand which error to return depending on your business case:

[!NOTE] About error 412 (Invalid login or password): authentication is performed exclusively at the HTTP level — return HTTP 401 Unauthorized for invalid credentials, not a JSON-RPC error. Code 412 is a legacy from early protocol versions and is not used in new integrations.

Full Paynet Error Codes Reference

JSON-RPC Protocol Errors:

[!NOTE] Code 0 ("Processed successfully") is a status value; it is never returned inside the error object.

8. Version History

The portal and the OpenAPI specification conform to UWS v3.4 dated 07.05.2025 with clarifications from the Paynet core team: error code 306 added (allowed cancellation period expired), the TLS v1.3 requirement fixed, and the status field in the GetInformation response confirmed as mandatory.