Bank transfers in Azerbaijan

Name The code Description

Integration type

H2H

Payment via HighHelp API on the merchant side

Currency

AZN

Azerbaijani manat

Side

AZ

Azerbaijan

Deposits

Available payment methods:
- card-p2p
- phone-p2p

Payments

Available payment methods:
- card-p2p
- phone-p2p

Payment

General requirements for integrating P2P payments via API are described in the sectionGeneral requirements for P2P (H2H).

Creating an application

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

Request body parameters when creating a P2P request.

  • general — information about the application.

    • project_id — cashier identifier issued by HighHelp at the integration stage.
      (string) (<= 32)

    • payment_id — payment identifier, unique within the merchant’s checkout. Any UTF-8 encoded characters are acceptable.
      (string) (<= 255)

    • merchant_callback_url— dynamic URL for receiving informative notifications, for example about changes in the intermediate status of an application and details for payment of a P2P application. Final status notifications are sent to the URLs specified inmerchant_success_callback_urlAndmerchant_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 unsuccessful.
      (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.

    • method — payment method code. The list of codes is described in the sectionPayment methods and codes (H2H).
      (string) (<= 32)

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

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

    • currency — code of the currency in which the user pays, in the formatISO 4217 alpha-3. The list of codes is given in the sectionCurrency codes.
      (string) (regex: ^[A-Z]{3}$)

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

    • bank_symbol— code of the bank to which the user wants to make a transfer. If the parameter is not passed, the bank is selected randomly. The list of banks can be obtained via API/api/v1/bank/all(cm.Service endpoints). Examples of banks are given in the sectionBanks for P2P. Using this parameter reduces the conversion rate for issuing details, so it is recommended to set it only when necessary.
      (string) (<= 32)

    • description— payment description or comment. Displayed in the merchant's account.
      (string) (<= 255)

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

  • sender — card or phone details of the sender.

    • pan— sender’s card number.
      (string<pan>) (<= 32)

    • phone— sender’s phone number.
      (string) (<= 24)
      (regex: ^\+7\d{10}$|^\+994\d{7,12}$)

    • bank_symbol— code of the bank from whose card or account the user will pay. To get bank codes use the API/api/v1/bank/all(cm.Service endpoints). If the bank is not in the list, the parameter need not be passed.
      (string) (<= 32)

    • card_holder— sender’s name, as on the card.
      (string) (<= 255)
      (regex: ^[a-zA-Z - - ҐґЇїІіЄє0-9\s\-.']{1,255}$)

  • customer — information about the sending user.

    • id — a unique user identifier in the merchant’s system.
      (string) (<= 255)

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

    • first_name— name of the user making the payment.
      (string) (<= 255)

    • last_name— surname of the user making the payment.
      (string) (<= 255)

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

    • country — user country code in the formatISO 3166-1 alpha-2. A list of country codes is provided in the sectionCountry codes.
      (string) (regex: ^[A-Z]{2}$)

    • language— language code of the payment page interface in the formatISO 639-1. If no language is specified, the default language for the user's country is used. A list of language codes is provided in the sectionLanguage codes.
      (string) (regex: ^[a-z]{2}$)

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

    • browser— name and version of the user’s browser.
      (string) (<= 512)

    • device_type— user device type.
      (string) (<= 512)

    • user_agent— identification string of the client application.
      (string) (<= 1024)

Fields marked, are mandatory.

If the sender information (sender) are not transmitted, must be specified"sender": {}. When value"sender": nullthe request will be rejected.

Example request:

curl https://api.hh-processing.com/api/v1/payment/p2p/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": "AZN-PAYMENT-123456",
    "merchant_callback_url": "https://your-domain.com/internal",
    "merchant_success_callback_url": "https://your-domain.com/success",
    "merchant_decline_callback_url": "https://your-domain.com/decline",
    "redirect_url": "https://your-domain.com/order/page"
  },
  "payment": {
    "method": "card-p2p",
    "amount": 150000,
    "currency": "AZN",
    "lifetime": 300,
    "description": "Comment about the payment",
    "extra_param": "example"
  },
  "sender": {
    "pan": "4850788018041726",
    "card_holder": "Alex Johnson"
  },
  "customer": {
    "id": "cus_12345",
    "ip_address": "192.0.2.1",
    "first_name": "Alex",
    "last_name": "Johnson",
    "customer_type": "ftd",
    "country": "AZ",
    "language": "az",
    "email": "customer@example.com",
    "browser": "Google Chrome v15.12",
    "device_type": "iPhone 15 Pro"
  }
}'

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": "AZN-PAYMENT-123456",
  "integration": {
    "form_url": "https://ppage.hh-processing.com/24a9249ae10e15232c123409b625daf7e0ea627c",
    "redirect_url": "https://your-domain.com/order/page"
  }
}

Response options:

  • status — payment processing status. A list of status codes is given in the sectionStatus codes.
    (string) (<= 32)

  • sub_status— sub-status of payment processing. Only used for individual valuesstatus. See section for detailsTransaction types and statuses.
    (string) (<= 32)

  • status_description— additional description of status. Used for errors or unsuccessful payment.
    (string) (<= 1024)

  • request_id — payment identifier generated by the HighHelp payment system.
    (string) (<= 32)

  • project_id — cashier ID issued by HighHelp.
    (string) (<= 32)

  • payment_id — payment ID in the merchant’s system.
    (string) (<= 255)

  • integration— additional meta-information on the payment.

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

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

fieldsrecipient_requisitesAnddisplay_datain the API response remain empty until the request transitions to statusprocessing:awaiting_confirmorprocessing:paid.

Fields marked, are mandatory.

Data to display in payment instructions

Before issuing a payment instruction, you must obtain data to generate it. Two approaches are possible:

  • wait for notification with statusprocessing:awaiting_confirmto the URL specified in the parametermerchant_callback_url. The body of the notification will contain data for instructions;

  • poll the methodhttps://api.hh-processing.com/api/v1/payment/p2p/payin/infoat intervals of 15 seconds until the application status becomesprocessing:awaiting_confirm. After this, these instructions will be available in the response.

In the body of the notification or response, you need to get the fielddisplay_data. This is an array of objects with the following fields:

  • type— object type. For P2P payments the value is usedadd_info;

  • title— the name of the instruction attribute. Possible values:

    • recipient_card_holder— full name of the cardholder;

    • recipient_pan— card number to which the transfer needs to be made;

    • recipient_phone— phone number to which the transfer needs to be made;

    • lifetime— instruction (application) lifetime in seconds;

    • valid_until— the moment until which the instruction is valid, in Unix Timestamp (UTC) format;

    • amount— transfer amount in fractional units; For more details, see the sectionCurrency codes;

    • currency— currency code in the formatISO 4217 alpha-3;

    • bank_name— name of the recipient’s bank;

    • bank_country— country code of the recipient bank in the formatISO 3166-1 alpha-2; For a complete list of codes, seeCountry codes;

    • confirm_url— URL for sending a request when confirming the fact of payment by the user;

    • reject_url— URL for sending a request if the user refuses to pay;

  • data— the value of the instruction attribute.

An example fragment with a payment instruction:

"display_data": [
  {
    "type": "add_info",
    "title": "recipient_card_holder",
    "data": "Alex Johnson"
  },
  {
    "type": "add_info",
    "title": "recipient_pan",
    "data": "4850777018041155"
  },
  {
    "type": "add_info",
    "title": "recipient_phone",
    "data": "+994909994433"
  },
  {
    "type": "add_info",
    "title": "lifetime",
    "data": 300
  },
  {
    "type": "add_info",
    "title": "valid_until",
    "data": 1721647251
  },
  {
    "type": "add_info",
    "title": "amount",
    "data": 10000
  },
  {
    "type": "add_info",
    "title": "currency",
    "data": "AZN"
  },
  {
    "type": "add_info",
    "title": "bank_name",
    "data": "m10-az"
  },
  {
    "type": "add_info",
    "title": "bank_country",
    "data": "AZ"
  },
  {
    "type": "add_info",
    "title": "confirm_url",
    "data": "https://api.hh-processing.com/api/v1/payment/p2p/payin/confirm"
  },
  {
    "type": "add_info",
    "title": "reject_url",
    "data": "https://api.hh-processing.com/api/v1/payment/p2p/payin/cancel"
  }
]

Application information

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

Request body parameters for obtaining the status of a P2P application.

  • general — information about the application.

    • project_id — cashier ID issued by HighHelp.
      (string) (<= 32)

    • payment_id — payment ID in the merchant’s system.
      (string) (<= 255)

Fields marked, are mandatory.

Example request:

curl https://api.hh-processing.com/api/v1/payment/p2p/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": "AZN-PAYMENT-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": "AZN-PAYMENT-123456",
  "payment_info": {
    "amount": 10000,
    "old_amount": 10000,
    "initial_amount": 3000,
    "currency": "AZN",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "method": "card-p2p",
    "payment_system": null,
    "type": "payin"
  },
  "recipient_requisites": {
    "pan": "4850788018041726",
    "card_holder": "Alex Johnson",
    "bank_name": "m10-az",
    "bank_country": "AZ",
    "currency": "AZN"
  },
  "sender": {
    "pan_hidden": "48507****1726",
    "card_holder_hidden": "Alex****nson"
  },
  "integration": {
    "form_url": "https://ppage.hh-processing.com/24a9249ae10e15232c123409b625daf7e0ea627c",
    "redirect_url": "https://your-domain.com/order/page"
  }
}

Response options:

  • status — payment processing status; For status codes, see sectionStatus codes.
    (string) (<= 32)

  • sub_status— sub-status of payment processing; For a general description of statuses, see sectionTransaction types and statuses.
    (string) (<= 32)

  • status_description— additional description of status.
    (string) (<= 1024)

  • request_id — payment ID in the HighHelp system.
    (string) (<= 32)

  • project_id — HighHelp cash register identifier.
    (string) (<= 32)

  • payment_id — payment ID in the merchant’s system.
    (string) (<= 255)

  • payment_info — payment information.

    • amount — ; For more details, see the sectionCurrency codes.
      (integer) (1 <= X <= 10000000000000)

    • old_amount — the original amount of the application before the appeal. If the user transferred an amount different from the original one toamountthe actual amount is transferred, andold_amount— original. If there is a discrepancy in the amounts, you must create an appeal through HighHelp support.
      (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 the formatISO 4217 alpha-3; see sectionCurrency codes.
      (string) (regex: ^[A-Z]{3}$)

    • lifetime— request lifetime in seconds (no more than 10 minutes).
      (integer) (300 <= X <= 600)

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

    • method — payment method selected when creating the application; For method codes, see sectionPayment methods and codes (H2H).
      (string) (<= 32)

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

    • type— type of operation, for examplepayin; For a general list of types, see sectionPayment types.
      (string) (<= 32)

  • recipient_requisites— details to which the transfer is expected.

    • pan — card or phone number of the payment recipient.
      (string<pan>) (<= 4096)

    • card_holder — cardholder’s name (as on the card). In rare cases may contain technical meaning"--".
      (string) (<= 255)

    • bank_name— name of the recipient’s bank.
      (string) (<= 255)

    • currency— transaction currency code in the formatISO 4217 alpha-3; see sectionCurrency codes.
      (string) (regex: ^[A-Z]{3}$)

  • sender — details of the sender (merchant user).

    • pan_hidden— disguised card or phone number of the sender.
      (string) (<= 32)

    • card_holder_hidden— masked name of the sender’s cardholder.
      (string) (<= 255)

  • integration— additional meta-information on the payment.

    • form_url — link to the payment page with details and instructions.
      (string<https-url>) (<= 255)

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

fieldsrecipient_requisitesAnddisplay_dataremain empty until the application transitions to statusprocessing:awaiting_confirmorprocessing:paid.

Cancellation of application

POST https://api.hh-processing.com/api/v1/payment/p2p/payin/cancel

Request body parameters when canceling a P2P request.

  • general — information about the application.

    • project_id — HighHelp cash register identifier.
      (string) (<= 32)

    • payment_id — payment ID that needs to be cancelled.
      (string) (<= 255)

Fields marked, are mandatory.

Example request:

curl https://api.hh-processing.com/api/v1/payment/p2p/payin/cancel \
  -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": "AZN-PAYMENT-123456"
  }
}'

Sample answer:

{
  "status": "decline",
  "sub_status": null,
  "status_description": "Canceled by client",
  "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "AZN-PAYMENT-123456"
}

Response options:

  • status — payment processing status; see sectionStatus codes.
    (string) (<= 32)

  • sub_status— sub-status of payment processing.
    (string) (<= 32)

  • status_description— description of the reason for the unsuccessful completion of the operation.
    (string) (<= 1024)

  • request_id — operation identifier in the HighHelp system.
    (string) (<= 32)

  • project_id — HighHelp cash register identifier.
    (string) (<= 32)

  • payment_id — payment ID in the merchant’s system.
    (string) (<= 255)

Payment confirmation

POST https://api.hh-processing.com/api/v1/payment/p2p/payin/confirm

Request body parameters to confirm that the user transferred funds to the issued details.

  • general — information about the application.

    • project_id — HighHelp cash register identifier.
      (string) (<= 32)

    • payment_id — payment identifier for which confirmation is performed.
      (string) (<= 255)

Fields marked, are mandatory.

Example request:

curl https://api.hh-processing.com/api/v1/payment/p2p/payin/confirm \
  -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": "AZN-PAYMENT-123456"
  }
}'

Sample answer:

{
  "status": "processing",
  "sub_status": "paid",
  "status_description": null,
  "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "AZN-PAYMENT-123456"
}

Response options:

  • status — payment processing status; see sectionStatus codes.
    (string) (<= 32)

  • sub_status— sub-status of payment processing.
    (string) (<= 32)

  • status_description— additional information on status.
    (string) (<= 1024)

  • request_id — operation identifier in the HighHelp system.
    (string) (<= 32)

  • project_id — HighHelp cash register identifier.
    (string) (<= 32)

  • payment_id — payment ID in the merchant’s system.
    (string) (<= 255)

Payment statuses

Types of operations and statuses are described in sectionTransaction types and statuses.
Status codes and possible valuesstatusAndsub_statusare given in sectionStatus codes.

Status Substatus Description Payment status

error

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

Intermediate state

processing

new

The correctness of the request is checked before processing begins.

Intermediate state

requisites

Selection of details to which the client needs to transfer the amount from the request.

Intermediate state

awaiting_confirm

Confirmation of payment from the client is expected, since the details have already been provided.

Intermediate state

paid

The client confirmed that he sent the amount to the given details.

Intermediate state

dispute

no_payment

The client did not complete the payment for the application during its lifetime (lifetime).

Intermediate state

different_amount

The client sent an amount different from that specified in the application.

Intermediate state

confirm_timeout

The application expired, but the client later confirmed the payment and provided a receipt.

Intermediate state

decline

Payment declined

Final state

success

Payment completed

Final state

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)AndAlert 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 AlertsAndWidget 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": "AZN-PAYMENT-123456"
  },
  "status": {
    "status": "processing",
    "sub_status": "awaiting_confirm",
    "status_description": null
  },
  "payment_info": {
    "amount": 7000,
    "old_amount": 7000,
    "initial_amount": 3000,
    "currency": "AZN",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-p2p",
    "payment_system": null,
    "type": "payin"
  },
  "recipient_requisites": {
    "pan": "4850788018041726",
    "card_holder": "Alex Johnson",
    "bank_name": "m10-az",
    "bank_country": "AZ",
    "currency": "AZN"
  },
  "integration": {
    "form_url": "https://ppage.hh-processing.com/24a9249ae10e15232c123409b625daf7e0ea627c",
    "redirect_url": "https://your-domain.com/order/page"
  },
  "additional_info": {
    "display_data": [
      {
        "type": "add_info",
        "title": "recipient_card_holder",
        "data": "Alex Johnson"
      },
      {
        "type": "add_info",
        "title": "recipient_pan",
        "data": "4850788018041726"
      },
      {
        "type": "add_info",
        "title": "lifetime",
        "data": 300
      },
      {
        "type": "add_info",
        "title": "valid_until",
        "data": 1721647251
      },
      {
        "type": "add_info",
        "title": "amount",
        "data": 10000
      },
      {
        "type": "add_info",
        "title": "currency",
        "data": "AZN"
      },
      {
        "type": "add_info",
        "title": "bank_name",
        "data": "m10-az"
      },
      {
        "type": "add_info",
        "title": "bank_country",
        "data": "AZ"
      },
      {
        "type": "add_info",
        "title": "confirm_url",
        "data": "https://api.hh-processing.com/api/v1/payment/p2p/payin/confirm"
      },
      {
        "type": "add_info",
        "title": "reject_url",
        "data": "https://api.hh-processing.com/api/v1/payment/p2p/payin/cancel"
      }
    ]
  }
}

Details (recipient_requisites) and payment instruction (additional_info) are included in the notification when payment details are available for the application (usually starting fromprocessing:awaiting_confirmand further in subsequent non-final statuses).
In other cases, these fields may have the valuenull, For example"recipient_requisites": null, "additional_info": null.

Successful Alerts

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

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

Unsuccessful Alerts

An alert is sent if the application is unsuccessful (for example, final statusdecline).

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

Pay

Creating a payment request

POST https://api.hh-processing.com/api/v1/payment/p2p/payout

Request body parameters when creating a P2P payment to a card or phone.

  • general — information about the application.

    • project_id — cashier ID issued by HighHelp.
      (string) (<= 32)

    • payment_id — payment identifier, unique within the merchant’s cash register. Any UTF-8 characters are acceptable.
      (string) (<= 255)

    • merchant_callback_url— dynamic URL for informative notifications about the intermediate status of an application. Final status alerts are sent to the URL frommerchant_success_callback_urlAndmerchant_decline_callback_url.
      (string<https-url>) (<= 2048)

    • merchant_success_callback_url— dynamic URL for notifications about successfully completed payments.
      (string<https-url>) (<= 2048)

    • merchant_decline_callback_url— dynamic URL for notifications about unsuccessful payments.
      (string<https-url>) (<= 2048)

  • receiver — details of the payment recipient.

    • pan — recipient’s card number; required parameter ifpayment.method = "card-p2p".
      (string<pan>) (<= 32)

    • phone — recipient’s phone number; required parameter ifpayment.method = "phone-p2p".
      (string) (<= 24)
      (regex: ^\+7\d{10}$|^\+994\d{7,12}$)

    • bank_code — recipient’s bank code. Example for Sberbank:100000000111. The list of bank codes is available via API/api/v1/bank/all.
      (string) (= 12)
      (regex: ^\d{12}$)

    • card_holder— the name of the recipient’s cardholder, as on the card.
      (string) (<= 255)
      (regex: ^[a-zA-Z - - ҐґЇїІіЄє0-9\s\-.']{1,255}$)

  • payment — information about payment.

    • method — payment method code. The codes are described in the sectionPayment methods and codes (H2H).
      (string) (<= 32)

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

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

    • currency — payout currency in the formatISO 4217 alpha-3.
      (string) (regex: ^[A-Z]{3}$)

    • description— payment description or comment. Displayed in the merchant's account.
      (string) (<= 255)

    • extra_param— an additional parameter for routing the application, agreed with HighHelp specialists.
      (string) (regex: ^[A-Za-z0-9_-]{1,16}$)

  • customer — information about the sending user (merchant’s client).

    • id — a unique user identifier in the merchant’s system.
      (string) (<= 255)

    • ip_address — User IP address.
      (string<ip-address>) (<= 255)

    • first_name — name of the user receiving the payment.
      (string) (<= 255)

    • last_name — surname of the user receiving the payment.
      (string) (<= 255)

    • country — user country code in the formatISO 3166-1 alpha-2; see sectionCountry codes.
      (string) (regex: ^[A-Z]{2}$)

    • email— user email address.
      (string<email>) (<= 255)

    • browser— name and version of the browser.
      (string) (<= 512)

    • device_type— device type.
      (string) (<= 512)

    • user_agent— identification string of the client application.
      (string) (<= 1024)

Fields marked, are mandatory.

Example request:

curl https://api.hh-processing.com/api/v1/payment/p2p/payout \
  -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": "AZN-PAYOUT-123456",
    "merchant_callback_url": "https://your-domain.com/internal",
    "merchant_success_callback_url": "https://your-domain.com/success",
    "merchant_decline_callback_url": "https://your-domain.com/decline"
  },
  "receiver": {
    "pan": "4850788018041726",
    "card_holder": "Alex Johnson"
  },
  "payment": {
    "method": "card-p2p",
    "amount": 100,
    "currency": "AZN",
    "description": "Comment about the payout",
    "extra_param": "example"
  },
  "customer": {
    "id": "cus_12345",
    "ip_address": "192.0.2.1",
    "first_name": "Alex",
    "last_name": "Johnson",
    "country": "RU",
    "email": "customer@example.com",
    "browser": "Google Chrome v15.12",
    "device_type": "iPhone 15 Pro"
  }
}'

Sample answer:

{
  "status": "processing",
  "sub_status": "new",
  "status_description": null,
  "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "AZN-PAYOUT-123456"
}

Response options:

  • status — payment processing status; see sectionStatus codes.
    (string) (<= 32)

  • sub_status— sub-status of payment processing.
    (string) (<= 32)

  • status_description— additional information on status.
    (string) (<= 1024)

  • request_id — operation identifier in the HighHelp system.
    (string) (<= 32)

  • project_id — HighHelp cash register identifier.
    (string) (<= 32)

  • payment_id — payment identifier in the merchant’s system.
    (string) (<= 255)

Fields marked, are mandatory.

Information about the payment request

POST https://api.hh-processing.com/api/v1/payment/p2p/payout/info

Request body parameters for obtaining P2P payment status.

  • general — information about the application.

    • project_id — HighHelp cash register identifier.
      (string) (<= 32)

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

Fields marked, are mandatory.

Example request:

curl https://api.hh-processing.com/api/v1/payment/p2p/payout/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": "AZN-PAYOUT-123456"
  }
}'

Sample answer:

{
  "status": "processing",
  "sub_status": "payout_process",
  "status_description": null,
  "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "payment_id": "AZN-PAYOUT-123456",
  "payment_info": {
    "amount": 10000,
    "old_amount": 10000,
    "initial_amount": 3000,
    "currency": "AZN",
    "method": "card-p2p",
    "type": "payout"
  }
}

Response options:

  • status — payment processing status; codes see sectionStatus codes.
    (string) (<= 32)

  • sub_status— sub-status of payment processing.
    (string) (<= 32)

  • status_description— additional description of status.
    (string) (<= 1024)

  • request_id — operation identifier in the HighHelp system.
    (string) (<= 32)

  • project_id — HighHelp cash register identifier.
    (string) (<= 32)

  • payment_id — payment identifier in the merchant’s system.
    (string) (<= 255)

  • payment_info — information about payment.

    • amount — ; For more details, see the sectionCurrency codes.
      (integer) (1 <= X <= 10000000000000)

    • old_amount — the amount of the application before the appeal. If there is a discrepancy with the actual amount, an appeal is required through HighHelp support.
      (integer) (1 <= X <= 10000000000000)

    • initial_amount — the amount specified when creating the application.
      (integer) (1 <= X <= 10000000000000)

    • currency — payment currency code in the formatISO 4217 alpha-3; see sectionCurrency codes.
      (string) (regex: ^[A-Z]{3}$)

    • method — payment method code; codes see sectionPayment methods and codes (H2H).
      (string) (<= 32)

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

    • type— type of operation, for examplepayout; a list of types is given inPayment types.
      (string) (<= 32)

Payment statuses

Types of operations and statuses are described in sectionTransaction types and statuses.
Status codes and possible valuesstatusAndsub_statusare given in sectionStatus codes.

Status Sub-status Description Payment status

error

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

Intermediate state

processing

new

Checking the request before processing.

Intermediate state

requisites

Selection of a trader who will execute the payment.

Intermediate state

payout_process

Making a payment using the specified details.

Intermediate state

dispute

incorrect_requisites

The trader reported incorrect payment details.

Intermediate state

payout_failed

The trader was unable to complete the payment using the correct details.

Intermediate state

payout_timeout

The order's lifetime has expired and the trader did not have time to execute the payment.

Intermediate state

decline

Payment declined.

Final state

success

Payment completed successfully.

Final state

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)AndAlert 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 AlertsAndWidget Alerts.

Informative Alerts

Example of an alert with statusprocessing:payout_process:

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "AZN-PAYOUT-123456"
  },
  "status": {
    "status": "processing",
    "sub_status": "payout_process",
    "status_description": null
  },
  "payment_info": {
    "amount": 7000,
    "old_amount": 7000,
    "initial_amount": 3000,
    "currency": "AZN",
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-p2p",
    "type": "payout"
  },
  "additional_info": {}
}

Successful Alerts

An alert is sent upon successful payment (statussuccess).

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

Unsuccessful Alerts

An alert is sent if the payout is unsuccessful (statusdecline).

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "AZN-PAYOUT-123456"
  },
  "status": {
    "status": "decline",
    "sub_status": null,
    "status_description": "Declined by anti-fraud"
  },
  "payment_info": {
    "amount": 7000,
    "old_amount": 7000,
    "initial_amount": 3000,
    "currency": "AZN",
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-p2p",
    "type": "payout"
  }
}