Configuring Callback

Callback for Order Status Updates

To promptly inform merchants about changes in the status of processed orders, we send POST requests with order data to the merchant's endpoint.

In the merchant's user interface, there is a feature for each shop to set up a unique URL designated for receiving order status updates. You have the flexibility to specify a unique URL for each individual shop, or you can assign the same URL to all shops for order status updates.

Whenever there is an update to an order's status, a POST request is dispatched to the URL you have configured.

There are two ways to configure the callback for order status changes:

1. Set up a standard callback for the shop.
2. Specify the webhookUrl in the paymentSettings object in the request to the Create Order endpoint for each order during its creation.

note

If you specify the webhookUrl when creating an order, the callback will be sent to this address for that order and not to the standard callback address set up for the shop.

Additionally, we include a control signature in the headers, api-notification-sign (SHA512), to safeguard the security and authenticity of the data received. For this purpose, you must get your YOUR_SECRET_KEY in the Developers section of the merchant admin panel. See how to.

To generate the signature on your side, to compare it with the received signature, you must take the entire callback payload as it is received, without omitting any part of it, and generate the signature.

Below is an example of signature generation (this is just an example, not ready-to-use code). You need to use the data received in the callback:

Example of signature generation algorithm:

PHP

$phpInput = array(
    'id' => 77,
    'number' => '7_1706275173',
    'status' => 'completed',
    'cost' => array(
        'amount' => '10.000000000',
        'currency' => 'BRL'
    ),
    'timeLimit' => array(
        'date' => '2024-01-27 07:45:51.000000',
        'timezone_type' => 3,
        'timezone' => 'UTC'
    ),
    'orderCreatedAt' => array(
        'date' => '2024-01-26 13:19:33.222170',
        'timezone_type' => 3,
        'timezone' => 'UTC'
    ),
    'orderPaidAt' => array(
        'date' => '2024-01-26 13:19:33.526490',
        'timezone_type' => 3,
        'timezone' => 'UTC'
    ),
    'captureNeeded' => false,
    'payments' => array(
        array(
            'id' => 77,
            'type' => 'payment',
            'parentPaymentId' => null,
            'cost' => array(
                'amount' => '10.00',
                'currency' => 'BRL'
            ),
            'acquirerCode' => 'payku',
            'paymentMethod' => 'card',
            'paymentDetails' => array(
                'type' => 'card',
                'authCode' => '114255400',
                'rrn' => '301170696',
                'maskedCardNumber' => '411111**1111'
            )
        )
    ),
    'customer' => array(
        'id' => '4',
        'name' => 'Tester',
        'middleName' => 'Tester',
        'surname' => 'Tester',
        'phone' => '95968093',
        'email' => 'test02@test.сom'
    )
);

$message = json_encode($phpInput, JSON_UNESCAPED_SLASHES);
$sign = hash_hmac('sha512', $message, 'YOUR_SECRET_KEY'); // Replace 'YOUR_SECRET_KEY' with your actual secret key

Setting up the callback data

1. Log in to your merchant admin panel:
   • Production:
     Loading link...
   • Testing environment:
     Loading link...
2. Confirm that your account role is set to Developer or Admin, as this roles is necessary to access the Developers section.
3. In the sidebar menu, locate and select the Developers section.
4. Within this section, find and click on the Shops subsection.
5. Copy the Secret Key, which will be used to sign incoming requests from us (YOUR_SECRET_KEY).
6. In the Deposit notifications URL, specify the address that will receive our POST request when the status of an order changes, applicable for incoming payments (section: orders).
7. In the Withdrawal notifications URL, specify the address that will receive our POST request when the status of a payout changes, applicable outgoing payments (section: payouts).