Payment Handler

As the payment is made, we notify the store's platform of the payment status by consistently sending GET requests to the handler's URL.

The domain in the payment handler must completely match the one you add to our system as a project

CHECK: checking the possibility of providing the service to the subscriber, the request is sent before the payment is made. You must confirm that the system is ready (check whether the payment amount is correct, whether the account exists in the database, etc.)

PAY: notification of successful debiting, you must provide the service to the subscriber. If any error occurs at this stage (e.g., the database is inaccessible), the payment gets the "not completed" status. After the problem is resolved, you can repeat the payment in the statistics interface. Money is credited to the partner's balance regardless of the handler's response

PREAUTH: notification in case of payments with pre-authorization when funds are successfully blocked. Important Note! You should not provide the service or give the goods to the payer upon receipt of such notification. The funds should be debited and services should be provided when confirmPayment is completed

ERROR: payment error at any stage. If an error is caused by an empty/error response from the partner server, the request will not be sent. Please note that this status is not final and there may be situations when the ERROR request may be followed by a PAY request

http://your_payment_handler_address?

     method=check 
     params[account]=userId 
     params[date]=2024-10-01 12:32:00
     params[paymentType]=card
     params[projectId]=123456
     params[phone]=9XXXXXXXXX 
     params[payerSum]=10.00 
     params[payerCurrency]=USD 
     params[signature]=9bdf52a4830779a1383ac24f1b3ed054 
     params[orderSum]=10.00 
     params[orderCurrency]=USD 
     params[unitpayId]=123456789
     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
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 sign and signature parameters 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")
payerSum	number	Amount debited from the subscriber's account
payerCurrency	line	Currency of debiting from the subscriber's account according to ISO 4217 standard (RUB, UAH, BYN, EUR, USD)
profit	number	Your income from this payment, rubles
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 (RUB, UAH, BYN, EUR, USD). Make sure to check the received value with the original order currency
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

Always check the IP addresses from which requests are sent to your handler

IMPORTANT NOTE: the partner's system cannot have two different payments with the same unitpayId. If you receive a repeated CHECK or PAY request, you must return the result of the previous request without depositing/crediting anything

Successful response

Запрос успешно обработан

Request processed successfully

	Value	Description
message	line	Text status of query progress.

Error response

Описание ошибки

Error description

	Value	Description
message	line	Information with a description of the payment generation error.

In case of errors, the text from the "message" parameter will be shown to the client when using the payment form

IMPORTANT NOTE: If any error occurs at the PAY stage (e.g., the database can not be accessed), the payment gets the "not completed" status. After the problem is resolved, repeat the payment in the statistics.