Order cancellation via API
Usually, payment cancellation is done in the eCom system. If a merchant needs to automate this process, then a special API call can be used.
Payment cancellation request must be sent to eCom by POST method to the address https://jpay.jysanbank.kz/ecom/api.
| Name | Obligation | Format | Description |
|---|---|---|---|
| ORDER | Yes | N(6 - 10) | Order number, must be the same as in the order operation |
| MERCHANT | Yes | C(6 - 15) | Merchant identifier |
| REV_AMOUNT | Yes | N(1 - 13) | Cancellation amount (in the order currency) must not exceed the order amount! Separator is dot |
| REV_DESC | Yes | C(1 – 400) | Description of the reason for canceling the order |
| LANGUAGE | No | С(2) | Client's preferred language, "ru" and "en" values are supported |
| P_SIGN | Yes | C(80 - 250) | Order sign |
The algorithm for generating a signature in the P_SIGN field is as follows: you need to collect the order fields values (without LANGUAGE!) In one line through the separator ";", then add this line to the value of the SHARED_SECRET secret key (this key is individual for each merchant), and calculate from the resulting string SHA512 hash value. In the REV_DESC line, remove all line breaks before processing. For example, in PHP it will look like this:
vSign=hash("sha512",C_SHARED_KEY.$_POST["ORDER"].";".$_POST["MERCHANT"].";".$_POST["REV_AMOUNT"].";".preg_replace("/\n|\r/g","",$_POST["REV_DESC"]).";"););
Note! In the product system, the hash should be calculated not in the browser on the client side, but in the procedure on the side of the merchant's web server!
The example on the test.html page is for testing purposes only.
The secret key SHARED_SECRET should never be available to anyone outside your server!
An example of calculation is on the example page https://ecom.jysanbank.kz:8462/ecom/static/e/test_rev.html.
The response will return the result of registering the order operation as XML:
<?xml version="1.0" encoding="utf-8"?>
<result>
<code>0</code>
<description>Order cancellation request '0000000034' for the
amount of '0.99' has been registered
</description>
</result>
| Code | Description (ru) | Description (en) |
|---|---|---|
| 0 | Зарегистрирована заявка на отмену заказа '%s' на сумму '%s' | Request of cancellation/refund of order '%s' is registered, amount '%s' |
| 41 | Сервис временно недоступен, попробуйте позже. %s. | Service temporary unavailable, try again later. %s. |
| 42 | Неправильная сумма: %s | Amount is invalid: %s |
| 43 | Сервис Db временно недоступен, попробуйте позже | Db service temporary unavailable, try again later |
| 44 | Неправильное значение в поле MERCHANT: '%s' | Merchant is invalid: '%s' |
| 45 | Заявка ORDER=%s не найдена | Order '%s' is not found |
| 46 | Неправильная подпись! | Signature is invalid! |
| 47 | Сумма возврта '%s' больше чем сумма заказа '%s' | Refund amount '%s' is greater than the order amount '%s' |
| 48 | Текущий татус заказа не позволяет делать возврат/отмену | Сurrent status of order does not allow to make it refund / cancel |
| 50 | Неправильное значение в поле '%s' : '%s' | Value of param '%s' is invalid: '%s' |
| 51 | Текущий статус терминала '%s' не позволяет производить операции | Current status of terminal '%s' does not allow operations |
| 52 | Операция отмены/возврата через API для терминала '%s' запрещена | API refunding operation for terminal '% s' is forbidden |
Cancellation of the order is done in the background. The result of the order cancellation operation, in the same way as when canceling through the eCom system, is sent to the BACKREF address specified in the BACKREF parameter of the main operation or in the merchant's default settings.