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>


Possible order cancellation registration result codes:
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.