Bank transfers in Uzbekistan

Name The code Description

Integration type

H2C

Payment via HighHelp payment widget

Currency

UZS

Uzbek sum

Side

UZ

Republic of Uzbekistan

Deposits

Available payment methods:
- payin-p2p-card

Payments

Payments not available

Payment

Creating an application

POST https://api.hh-processing.com/api/v1/widget/payin

Parameters that must be sent in the request body when creating a P2P application.

  • general — information about the application.

    • project_id — cash ID received from HighHelp during the integration process;
      (string) (<= 32)

    • payment_id — payment identifier, unique within the merchant’s checkout. You can use any letters, numbers and symbols in UTF-8 encoding;
      (string) (<= 255)

    • merchant_callback_url— dynamic URL for receiving notifications on intermediate application statuses (changes in processing status, payment details, etc.). Final status notifications are sent to the URLs specified inmerchant_success_callback_urlmerchant_decline_callback_url;
      (string<https-url>) (<= 2048)

    • merchant_success_callback_url— dynamic URL to receive a notification upon successful completion of the operation;
      (string<https-url>) (<= 2048)

    • merchant_decline_callback_url— dynamic URL to receive an alert if the operation is not successful;
      (string<https-url>) (<= 2048)

    • redirect_url— link to redirect the user from the payment page after completing the payment;
      (string<https-url>) (<= 2048)

  • payment — payment information.

    • amount — the amount that the user intends to pay. The amount is indicated in fractional units. For more details, see sectionCurrency codes;
      (integer) (1 <= X <= 10000000000000)

    • currency — code of the currency in which the user pays, in ISO 4217 alpha-3 format. Supported currency codes are listed inCurrency codes;
      (string) (regex: ^[A-Z]{3}$)

    • lifetime— request lifetime in seconds. The maximum lifetime is 10 minutes. If the parameter is not specified, the default value of 10 minutes is used;
      (integer) (300 <= X <= 600)

    • description— payment description or comment. The value is displayed in the merchant's account;
      (string) (<= 255)

    • extra_param— an additional parameter used for individual routing of a request. Configured together with the administrator;
      (string) (regex: ^[A-Za-z0-9_-]{1,16}$)

    • widget_method— payment widget method that will be preselected on the payment page. Supported methods are listed in sectionWidget Methods (H2C);
      (string) (<= 32)

    • payment_system— code of the payment system whose details need to be obtained. If the parameter is not specified, the details of a random payment system are selected. Available values:humo, uzcard;
      (string) (<= 32)

  • sender— information about the user’s card, phone or bank from which the payment is made.

    • bank_symbol— the bank from which the client will pay for the application. Supported values ​​are listed in the sectionsBanks for pre-selectionBanks for P2P. If the required bank is not in the list or bank preselection is not used, the parameter is optional;
      (string) (<= 32)

  • customer — information about the sender.

    • id — unique identifier of the user (sender) in the merchant’s system;
      (string) (<= 255)

    • ip_address — IP address of the sender;
      (string<ip-address>) (<= 255)

    • country — user country code in ISO 3166-1 alpha-2 format. Supported countries are listed in the sectionCountry codes;
      (string) (regex: ^[A-Z]{2}$)

    • language— language code in ISO 639-1 format, which will be pre-selected on the payment page. If no language is specified, the default language for the country is used. Supported languages ​​are listed in the sectionLanguage codes;
      (string) (regex: ^[a-z]{2}$)

    • customer_type— user type:ftd— primary traffic,trust— secondary traffic;
      (string) (regex: ^(ftd|trust)$)

    • email— sender’s email address;
      (string<email>) (<= 255)

Fields marked, are mandatory.

Example request:

curl https://api.hh-processing.com/api/v1/widget/payin \
  -X POST \
  -H 'x-access-timestamp: 1706182847' \
  -H 'x-access-merchant-id: 57aff4db-b45d-42bf-bc5f-b7a499a01782' \
  -H 'x-access-signature: SIGNATURE' \
  -H 'x-access-token: API_KEY' \
  -H 'content-type: application/json' \
  -d '{
    "general": {
      "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
      "payment_id": "UZS-HUMO-123456",
      "merchant_callback_url": "https://your-callback-domain.com/internal",
      "merchant_success_callback_url": "https://your-callback-domain.com/success",
      "merchant_decline_callback_url": "https://your-callback-domain.com/decline",
      "redirect_url": "https://your-web-site-url.com/order/page"
    },
    "payment": {
      "amount": 1500000,
      "currency": "UZS",
      "lifetime": 300,
      "description": "Comment about the payment",
      "extra_param": "example",
      "widget_method": "payin-p2p-card",
      "payment_system": "humo"
    },
    "sender": {
      "bank_symbol": "sberbank"
    },
    "customer": {
      "id": "cus_12345",
      "ip_address": "192.0.2.1",
      "country": "UZ",
      "language": "uz",
      "customer_type": "ftd",
      "email": "customer@example.com"
    }
  }'

Sample answer:

{
  "status": "processing",
  "sub_status": "requisites",
  "status_description": null,
  "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "UZS-HUMO-123456",
  "integration": {
    "form_url": "https://ppage.hh-processing.com/widget/24a9249ae10e15232c123409b625daf7e0ea627c",
    "redirect_url": "https://your-web-site-url.com/order/page"
  }
}

Response options:

  • status — payment processing status. Supported statuses are listed in the sectionStatus codes;
    (string) (<= 32)

  • sub_status— payment processing substatus. Used only for some statuses. See section for detailsStatus codes;
    (string) (<= 32)

  • status_description— additional information on status. Used if the payment did not go through or an error occurred;
    (string) (<= 1024)

  • request_id — payment ID, which is generated in the HighHelp payment system;
    (string) (<= 32)

  • project_id — cash ID received from HighHelp during the integration process;
    (string) (<= 32)

  • payment_id — payment identifier, unique within the merchant’s cash register;
    (string) (<= 255)

  • integration— additional information for integration.

    • form_url — link to the payment page. The page displays payment details, payment instructions and service information;
      (string<https-url>) (<= 255)

    • redirect_url— link to redirect the user from the payment page after completing the payment;
      (string<https-url>) (<= 2048)

Fields marked, are mandatory.

Application information

POST https://api.hh-processing.com/api/v1/widget/payin/info

Parameters that must be sent in the body of the request to obtain P2P application status.

  • general — information about the application.

    • project_id — cash ID received from HighHelp during the integration process;
      (string) (<= 32)

    • payment_id — payment ID;
      (string) (<= 255)

Fields marked, are mandatory.

Example request:

curl https://api.hh-processing.com/api/v1/widget/payin/info \
  -X POST \
  -H 'x-access-timestamp: 1706182847' \
  -H 'x-access-merchant-id: 57aff4db-b45d-42bf-bc5f-b7a499a01782' \
  -H 'x-access-signature: SIGNATURE' \
  -H 'x-access-token: API_KEY' \
  -H 'content-type: application/json' \
  -d '{
    "general": {
      "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
      "payment_id": "UZS-HUMO-123456"
    }
  }'

Sample answer:

{
  "status": "processing",
  "sub_status": "awaiting_confirm",
  "status_description": null,
  "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "UZS-HUMO-123456",
  "payment_info": {
    "amount": 10000,
    "old_amount": 10000,
    "initial_amount": 3000,
    "currency": "UZS",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "method": "card-p2p",
    "widget_method": "payin-p2p-card",
    "payment_system": "humo",
    "type": "payin"
  },
  "integration": {
    "form_url": "https://ppage.hh-processing.com/widget/24a9249ae10e15232c123409b625daf7e0ea627c",
    "redirect_url": "https://your-web-site-url.com/order/page"
  }
}

Response options:

  • status — payment processing status. Supported statuses are listed in the sectionStatus codes;
    (string) (<= 32)

  • sub_status— payment processing substatus. Used only for some statuses;
    (string) (<= 32)

  • status_description— additional information on status. Used if the payment did not go through or an error occurred;
    (string) (<= 1024)

  • request_id — payment ID, which is generated in the HighHelp payment system;
    (string) (<= 32)

  • project_id — cash ID received from HighHelp during the integration process;
    (string) (<= 32)

  • payment_id — payment identifier, unique within the merchant’s cash register;
    (string) (<= 255)

  • payment_info — payment information.

    • amount — application amount. The amount is indicated in fractional units. For more details, see sectionCurrency codes;
      (integer) (1 <= X <= 10000000000000)

    • old_amount — the amount of the application before the appeal. The parameter may differ fromamount, if the user transferred an amount different from the original one. In this case, inamountthe actual amount is transferred, andold_amount— initial application amount;
      (integer) (1 <= X <= 10000000000000)

    • initial_amount — the amount specified when creating the application. The value does not change;
      (integer) (1 <= X <= 10000000000000)

    • currency — currency code in ISO 4217 alpha-3 format;
      (string) (regex: ^[A-Z]{3}$)

    • lifetime— request lifetime in seconds. The maximum lifetime is 10 minutes. If the parameter is not specified, the default value of 10 minutes is used;
      (integer) (300 <= X <= 600)

    • expiration_date— time until which the application is valid, in Unix Timestamp (UTC) format;
      (integer) (X <= 2^32)

    • method— payment method selected when creating the payment. For details, see sectionsPayment methods (H2H)Widget Methods (H2C);
      (string) (<= 32)

    • widget_method— payment widget method selected for payment. Supported methods are listed in sectionWidget Methods (H2C);
      (string) (<= 32)

    • payment_system— code of the payment system used when processing the payment.
      (string) (<= 32)

    • type— type of payment. Supported values ​​are listed in sectionPayment types;
      (string) (<= 32)

  • integration— additional information for integration.

    • form_url — link to the payment page. The page displays payment details, payment instructions and service information;
      (string<https-url>) (<= 255)

    • redirect_url— link to redirect the user from the payment page after completing the payment;
      (string<https-url>) (<= 2048)

Payment statuses

For a complete list of statuses and substatuses, see the sectionStatus codes.

Status Substatus Description Merchant actions

error

The request was rejected due to an error related to the payment parameters.

Contact support

processing

new

The payment has been created and is awaiting client action.

No action required

requisites

Entering details is required, a link to the form is available inintegration.form_url. For methodpayin-mobile-moneythis status is skipped because the details are not transmitted.

Direct the client to the payment form

awaiting_confirm

Client confirmation of payment is awaited. Payment is possible via redirection, QR or push notification (for example, forpayin-mobile-money).

Wait for the payment to complete

paid

Funds have been secured and final confirmation is awaited.

Wait for the payment to complete

dispute

no_payment

The client did not complete the payment within the payment lifetime (lifetime).

No action required

different_amount

An amount received that does not match the stated amount.

Contact support

confirm_timeout

The confirmation timeout has expired and the payment has not been completed.

Contact support

decline

Payment declined.

Inform the client about the refusal

success

Payment has been successfully confirmed.

No action required

Alerts

It is recommended to implement checking of incoming notifications for duplicates. The idempotency key can be generated using a template{project_id}:{payment_id}:{status}:{sub_status}. Repeated notifications with the same key should be ignored to ensure that the same request is not processed twice.

Each alert is digitally signed by HighHelp. The current public key for verifying the signature can be obtained in the admin panel. The key is unique for each cash register. The signature verification algorithm is the reverse of the signature generation algorithm when calling an API. Examples of signature verification are given in sectionsAlert Signing (RSA)Alert signature (HMAC).

There are three types of alerts:

  • Informative— notifications in non-final statuses, if they are provided for a specific product (for example,processing:*, dispute:*orerror). The URL is specified in the parametermerchant_callback_urlwhen creating an application.

  • Successful— notifications for applications completed in statussuccess. The URL is specified in the parametermerchant_success_callback_url.

  • Unsuccessful— notifications for applications completed in statusdecline. The URL is specified in the parametermerchant_decline_callback_url.

The composition of the fields and the list of informative statuses depend on the product and integration scenario. See more details.H2H AlertsWidget Alerts.

Informative Alerts

Example of an alert with statusprocessing:awaiting_confirm:

{ "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782", "general": { "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3", "payment_id": "UZS-HUMO-123456" }, "status": { "status": "processing", "sub_status": "awaiting_confirm", "status_description": null }, "payment_info": { "amount": 7000, "old_amount": 7000, "initial_amount": 3000, "currency": "UZS", "lifetime": 300, "expiration_date": 1721647251, "updated_date": 1721647251, "created_date": 1721647251, "method": "card-p2p", "widget_method": "payin-p2p-card", "payment_system": "humo", "type": "payin" }, "recipient_requisites": { "pan_hidden": "2202****6980", "card_holder_hidden": " **** ", "bank_name": "NBU", "bank_country": "UZ", "currency": "UZS" }, "integration": { "form_url": "https://ppage.hh-processing.com/widget/24a9249ae10e15232c123409b625daf7e0ea627c", "redirect_url": "https://your-web-site-url.com/order/page" } }

Masked details in the blockrecipient_requisitestransmitted only for statusesprocessing:awaiting_confirmprocessing:paid. For other substatusesprocessing:*blockrecipient_requisitesnot transmitted. In notifications with statusessuccess, decline, errordispute:*blockrecipient_requisitesalso not transmitted.

Successful Alerts

An alert is sent if the application has reached the successful final statesuccess.

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "UZS-HUMO-123456"
  },
  "status": {
    "status": "success",
    "sub_status": null,
    "status_description": null
  },
  "payment_info": {
    "amount": 7000,
    "old_amount": 5000,
    "initial_amount": 3000,
    "currency": "UZS",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-p2p",
    "widget_method": "payin-p2p-card",
    "payment_system": "humo",
    "type": "payin"
  }
}

Unsuccessful Alerts

An alert is sent if the request has entered an unsuccessful final statedecline.

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "UZS-HUMO-123456"
  },
  "status": {
    "status": "decline",
    "sub_status": null,
    "status_description": "Declined by anti-fraud"
  },
  "payment_info": {
    "amount": 7000,
    "old_amount": 7000,
    "initial_amount": 3000,
    "currency": "UZS",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": null,
    "widget_method": null,
    "payment_system": null,
    "type": "payin"
  }
}