Check Order Status

There are two ways to get the order status: automatic webhook notifications (recommended) and manual API polling.

Webhook Notifications (Recommended)

This is the recommended method for integration. Webhooks automatically notify your server when the order status changes — no need to poll the API manually.

When the order status changes, we will send a POST request to your webhook URL with the order data.

Setting Up Webhooks

Provide your webhook URL to your manager
Make sure your server can accept POST requests at this URL
Process incoming notifications and respond with HTTP 200

Webhook Request Example

Your server will receive a POST request with the following body:

{
  "id": "a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6",
  "status": "COMPLETED",
  "purpose": "Payment for order #1234",
  "amount": "1000.5",
  "commission": "1.5",
  "received": "999.0",
  "currency": "RUB",
  "paymentType": "SBP",
  "shopId": "a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6",
  "terminalId": "a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6",
  "merchantId": "a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6",
  "externalId": "order_1234",
  "externalUserId": "user_987",
  "paymentLink": "https://example.com/payment?id=...",
  "successUrl": "https://example.com/success",
  "payedAt": "2023-03-21T12:34:56Z",
  "updatedAt": "2023-03-21T12:34:56Z",
  "createdAt": "2023-03-21T12:34:56Z"
}

Signature Verification (X-Signature)

For additional security, each webhook request includes the X-Signature header — this is the HMAC SHA512 hash in HEX format of the request body. The signature is generated using your API key as the secret key.

Example of Signature Verification

import crypto from "crypto";

const apiKey = "your_API_key";

app.post("/webhook/payments", (req, res) => {
  const signature = req.headers["x-signature"];
  const body = JSON.stringify(req.body);

  // Verify the signature
  const hmac = crypto.createHmac("sha512", apiKey);
  hmac.update(body);
  const calculatedSignature = hmac.digest("hex");

  if (calculatedSignature !== signature) {
    console.error("❌ Invalid webhook signature!");
    return res.status(403).send("Invalid signature");
  }

  console.log("✅ Signature is valid");

  // Process the webhook
  const data = req.body;
  if (data.status === "COMPLETED") {
    console.log(`✅ Order ${data.externalId} has been paid!`);
  }

  res.status(200).send("OK");
});

Webhook Recommendations

Always respond with HTTP 200 to confirm receipt
Verify the order data matches your records using externalId
Process webhooks idempotently — you may receive the same notification multiple times
If your server doesn't respond with 200, we will retry the webhook

Manual Status Check

To get the current order status, send a GET request with authorization to:

/v1/orders/:id

where :id is the order UUID in our system.

Before you start

How to authorize your requests

Request Example

curl -X GET "https://api.riopay.online/v1/orders/a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6" \
-H "X-Api-Token: YOUR_API_TOKEN"

Successful Response Example

{
  "id": "a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6",
  "status": "PENDING",
  "purpose": "Payment for order #1234",
  "amount": "1000.5",
  "commission": "1.5",
  "received": "999.0",
  "currency": "RUB",
  "paymentType": "SBP",
  "shopId": "a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6",
  "terminalId": "a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6",
  "merchantId": "a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6",
  "externalId": "sesemasese3252362632",
  "externalUserId": "user15236236",
  "paymentLink": "https://example.com/index.php?route=extension/trip/payments/create?id=a1b2c3d4-e5f6-7g8h-i9j0-k1l2m3n4o5p6&amount=1000&hash=2792ob1jhvyif81bhcvfy8iwbhck",
  "successUrl": "https://example.com",
  "payedAt": "2023-03-21T12:34:56Z",
  "updatedAt": "2023-03-21T12:34:56Z",
  "createdAt": "2023-03-21T12:34:56Z"
}

Possible Status Values

Status	Description
CREATED	Order created
PENDING	Awaiting payment
COMPLETED	Payment successful
FAILED	Payment error
CANCELED	Order canceled by system
EXPIRED	Order expired

Some fields in the response may be null depending on the order processing stage. Always refer to the current Swagger documentation.