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) |
paymentType | line | |
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 |
operator | line | |
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.