Payment Handler
Last updated
Last updated
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
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 (RUB, UAH, BYN, EUR, USD)
profit
number
Your income from this payment, rubles
phone
number
Payer's phone number (transmitted only for mobile payments)
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
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")
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.
