Bank transfers in Kyrgyzstan

Name The code Description

Integration type

H2C

Payment via HighHelp payment widget

Currency

KGS

Kyrgyz som

Side

KG

Kyrgyz Republic

Deposits

Available payment methods:
- payin-p2p-card
- payin-p2p-phone
- payin-qr-link-p2p

Payments

Payments not available

Payment

Creating an application

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

Request body parameters when creating a P2P request.

  • general — information about the application.

    • project_id — cash ID issued by 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 with intermediate information: changes in application status, payment details, etc. Notifications regarding the final status of the application 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 when the operation is successful.
      (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— a link to redirect the user from the payment page after completing the payment.
      (string<https-url>) (<= 2048)

  • payment — payment information.

    • amount — the amount paid by the user. The amount is indicated in fractional units. See more details.Currency codes.
      (integer) (1 <= X <= 10000000000000)

    • currency — payment currency code in ISO 4217 alpha-3 format. See more details.Currency codes.
      (string) (regex: ^[A-Z]{3}$)

    • lifetime— request lifetime in seconds. The maximum lifetime is 10 minutes. If no value is 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 personal account.
      (string) (<= 255)

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

    • widget_method— code of the payment method that will be pre-selected on the payment page. For a list of methods, seeWidget Methods (H2C).
      (string) (<= 32)

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

    • bank_symbol— the bank from which the client will pay for the application. For a list of banks, see the sectionsBanks for pre-selectionBanks for P2P. If the bank does not need to be preselected, the field is not required.
      (string) (<= 32)

  • customer — information about the sender.

    • id — a unique identifier of the user (sender) in the merchant 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. For a list of supported countries, seeCountry 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. For a list of supported languages, seeLanguage codes.
      (string) (regex: ^[a-z]{2}$)

    • customer_type— user type:ftdfor primary traffic,trustfor 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": "PAYMENT-KGS-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": "KGS",
    "lifetime": 300,
    "description": "Comment about the payment",
    "extra_param": "example",
    "widget_method": "payin-p2p-card"
  },
  "sender": {
    "bank_symbol": "demir-bank-kgs"
  },
  "customer": {
    "id": "cus_12345",
    "ip_address": "192.0.2.1",
    "country": "KG",
    "language": "ky",
    "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": "PAYMENT-KGS-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. For a list of statuses, see sectionStatus codes.
    (string) (<= 32)

  • sub_status— payment processing substatus. Used only for some statuses. For a complete list of combinations of statuses and substatuses, seeStatus codes.
    (string) (<= 32)

  • status_description— additional information about the status. Used when there is a payment error.
    (string) (<= 1024)

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

  • project_id — cash ID issued by HighHelp during the integration process.
    (string) (<= 32)

  • payment_id — payment identifier, unique within the merchant’s checkout.
    (string) (<= 255)

  • integration— additional meta-information about the payment.

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

    • redirect_url— a 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

Request body parameters for obtaining P2P request status.

  • general — information about the application.

    • project_id — cash ID issued by 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": "PAYMENT-KGS-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": "PAYMENT-KGS-123456",
  "payment_info": {
    "amount": 10000,
    "old_amount": 10000,
    "initial_amount": 3000,
    "currency": "KGS",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "method": "card-p2p",
    "widget_method": "payin-p2p-card",
    "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. For a list of statuses, see sectionStatus codes.
    (string) (<= 32)

  • sub_status— payment processing substatus. Used only for some statuses. For a complete list of combinations of statuses and substatuses, seeStatus codes.
    (string) (<= 32)

  • status_description— additional information about the status. Used when there is a payment error.
    (string) (<= 1024)

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

  • project_id — cash ID issued by HighHelp during the integration process.
    (string) (<= 32)

  • payment_id — payment identifier, unique within the merchant’s checkout.
    (string) (<= 255)

  • payment_info — payment information.

    • amount — application amount. The amount is indicated in fractional units. See more details.Currency codes.
      (integer) (1 <= X <= 10000000000000)

    • old_amount — the amount of the application before the appeal. The value may differ fromamount, if the application was created for one amount, and the user transferred another. In this case, in the fieldamountthe actual amount received from the user is transmitted, and in the fieldold_amount— the amount for which the application was created. If the amount has not changed, the field values ​​are the same.
      (integer) (1 <= X <= 10000000000000)

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

    • currency — payment currency code in ISO 4217 alpha-3 format. See more details.Currency codes.
      (string) (regex: ^[A-Z]{3}$)

    • lifetime— request lifetime in seconds.
      (integer) (300 <= X <= 600)

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

    • method— , . See more details.Payment methods.
      (string) (<= 32)

    • widget_method— payment method code of the payment page. See more details.Widget Methods (H2C).
      (string) (<= 32)

    • type— type of payment. See more details.Payment types.
      (string) (<= 32)

  • integration— additional meta-information about the payment.

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

    • redirect_url— a 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": "PAYMENT-KGS-123456" }, "status": { "status": "processing", "sub_status": "awaiting_confirm", "status_description": null }, "payment_info": { "amount": 7000, "old_amount": 7000, "initial_amount": 3000, "currency": "KGS", "lifetime": 300, "expiration_date": 1721647251, "updated_date": 1721647251, "created_date": 1721647251, "method": "card-p2p", "widget_method": "payin-p2p-card", "type": "payin" }, "recipient_requisites": { "pan_hidden": "2202****6980", "card_holder_hidden": " **** ", "bank_name": "demir-bank-kgs", "bank_country": "KG", "currency": "KGS" }, "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

The notification is sent if the application has completed in the statussuccess.

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

Unsuccessful Alerts

The notification is sent if the application has completed in the statusdecline.

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