Payment Handler

A payment handler is the URL of your server where Unitpay sends server-side GET requests regarding the payment process. These requests allow you to:

• Verify an order before payment.

• Confirm that an order exists and can be paid for.

• Automatically issue products, provide services, or credit balances after successful payment completion.

• Receive notifications about payment errors.

Important: if the handler URL is not specified, callback requests are not sent, and the payment is considered successful automatically.

Requirements for the handler URL

The partner may specify any technically valid handler URL. The handler domain does not have to match the domain of the project website.

What is considered a valid URL

The handler URL will be saved if:

• the http or https protocol is used;

• a valid domain is specified.

Examples of valid URLs

• https://example.com/payment-handler

• https://api.example.com/unitpay/callback

• http://merchant-service.net/pay

• https://xn--e1afmkfd.xn--p1ai/handler

Examples of invalid URLs

• ftp://example.com/callback — unsupported protocol

• https://127.0.0.1/callback — IP address instead of a domain

• https://user:[e-mail]/callback — embedded authentication data

How it works

The typical flow is:

1. The customer starts the payment.

2. Unitpay may send check to verify the order before charging.

3. After a successful charge, Unitpay sends pay.

4. If an error occurs at any stage, error may be sent.

5. For preauthorized payments, preauth may be sent first.

Important: with preauth, the funds are only blocked. You should deliver the product, provide the service, or credit the balance only after a successful charge.

Important: error does not always mean the final status. In some cases, pay may arrive later after error.

What you need to implement on your side

Your handler must:

• accept GET requests from Unitpay;

• verify the sender's IP address;

• verify the signature;

• validate orderSum and orderCurrency against the order data;

• at the check stage, only verify the order;

• at the pay stage, deliver the product, provide the service, or credit the balance;

• correctly handle repeated requests;

• return JSON in the required format.

Important: unitpayId is the unique payment identifier in Unitpay. If a request with the same unitpayId is received again, do not process the payment a second time: do not deliver the product again, do not provide the service again, and do not credit the balance again.

Methods

CHECK

A request to verify the order before payment.

At this stage, you need to make sure that:

• the order exists;

• the amount and currency match;

• the order can be paid;

• the service can be provided after successful payment.

Important: at the check stage, you must not deliver the product, provide the service, or credit the balance.

By default, the CHECK request is disabled for a new project. To use it, enable this option in the project settings.

PAY

A notification of a successful charge.

This is the stage at which you must:

• deliver the product;

• provide the service;

• credit the balance;

• save the payment processing result.

If your server returns an error at this stage, the payment will receive the "Not completed" status. After the issue is fixed, the payment can be retried from the statistics interface.

Important: funds are credited to the partner's balance regardless of the handler response.

Important: pay processing must be idempotent. A repeated request must not result in duplicate product delivery or duplicate crediting.

PREAUTH

A notification for preauthorized payments. This means the funds were successfully blocked but have not yet been finally charged.

Important: do not deliver the product or provide the service when receiving preauth. This must only be done after a successful charge.

ERROR

A notification about an error at one of the payment stages.

If the error is caused by an empty or invalid response from the partner's server, the error request may not be sent.

Important: error is not always the final status. Sometimes pay may arrive after it.

Request format

Unitpay sends a GET request to your handler URL.

Example:

GET https://your_handler_url

method               = check
params[account]      = userId
params[date]         = 2025-10-01 12:32:00
params[paymentType]  = card
params[projectId]    = 123456
params[payerSum]     = 10.00
params[payerCurrency]= USD
params[signature]    = 9bdf52a4830779a1383ac24f1b3ed054
params[orderSum]     = 10.00
params[orderCurrency]= USD
params[unitpayId]    = 1234567890
params[test]         = 0

Параметры запроса

	Value	Description
method	line	check — request to check the subscriber's status pay — notification of debiting error — error notification
unitpayId	number	Internal payment number in UnitPay
projectId	number	Project ID in UnitPay
account	line	Subscriber ID in the partner's system
payerSum	number	Amount debited from the subscriber's account
payerCurrency	line	Currency of debiting from the subscriber's account according to ISO 4217 standard (USD, EUR, USD)
profit	number	Your income from this payment, rubles
phone	number	Payer's phone number (transmitted only for mobile payments)
paymentType	line	Payment system code
orderSum	number	Order amount. Make sure to check the received value against the original order amount
orderCurrency	line	Order currency according to ISO 4217 (USD, RUB, BYN, EUR, USD). Make sure to check the received value with the original order currency
operator	line	Operator alphabetic code
date	line	Payment date in the YYYY-mm-dd HH:ii:ss format (for example, 2012-10-01 12:32:00)
errorMessage	line	Error details (only for the error method)
test	number	Sign of test mode: if a request is made using the test request mechanism, the value will equal to 1. For real payments, the value is always 0
3ds	number	Sign of 3-DS for card transaction, the flag is present for PAY notifications
subscriptionId	number	Subscription ID, it returns after successful payment of the setup fee under the subscription. It is present for PAY notifications
signature	line	Digital signature. It is generated as sha256(method + "{up}" + params + "{up}" + secretKey), where sha256 is the encryption method; "{up}" is the parameter separator in the hash function; method is the request type (check, pay, error); params are the values of the parameter from the params arra, combined with the "{up}" separator. All parameters must be pre-sorted by key; the signature parameter do not participate in merging; secretKey is the project secret key (available in your personal account); Example of computing the signature for the request http://partnerUrl?method=check & params[b]=bob & params[c]=sam & params[a]=tod and secret key "a1b1c1d1" sha256("check{up}tod{up}bob{up}sam{up}a1b1c1d1")

Successful response

If the request is processed successfully, return:

Успешный ответ

Если запрос обработан успешно, верните:

{
    "result": {
        "message": "Request processed successfully"
    }
}

message	string	Text status of request execution

Error response

If the request cannot be processed, return:

{
    "error": {
        "message": "Error description"
    }
}

message	string	Information describing the payment processing error. When using the payment form, the text from the message parameter will be shown to the payer.

Common integration mistakes

Most often, problems occur because:

• signature is not verified;

• IP addresses are not verified;

• orderSum and orderCurrency are not validated;

• the product is delivered at the check stage instead of the pay stage;

• the server returns invalid JSON.