Order Tracking

Overview

Payment links support two URL parameters that enable order tracking and post-payment redirects:

• order_id — Your external order or invoice ID. Links a customer’s payment to your system.
• callback_url — URL to redirect the customer after successful payment.

Both parameters are passed as query strings when sending customers to your payment link.

Payment URL Format

https://app.unuspay.com/pay/{slug}?order_id={your_id}&callback_url={encoded_url}

Example:

https://app.unuspay.com/pay/my-shop?order_id=INV-2025-001&callback_url=https%3A%2F%2Fshop.com%2Fconfirm%3Fsession%3Dabc

Always URL-encode the callback_url value before appending it to the payment URL.

Parameters

order_id

Your external order or invoice ID. Maps to external_order_id on the created order. If an order with this ID was already completed, the payment page returns 409.

callback_url

URL to redirect the customer after successful payment. Stored in order metadata and included in webhook events. Both HTTP and HTTPS are accepted.

Webhook Events

When order_id and callback_url are used, webhook payloads include external_order_id at the top level and inside metadata.

order.created

{
  "id": "evt_abc123def456",
  "type": "order.created",
  "created_at": "2026-03-18T10:00:00.000Z",
  "data": {
    "object": {
      "order_id": "ord_xxx",
      "order_number": 42,
      "status": "pending",
      "chain_id": 8453,
      "payer_address": "0x1234...abcd",
      "external_order_id": "INV-2025-001",
      "metadata": {
        "order_id": "INV-2025-001",
        "callback_url": "https://shop.com/confirm?session=abc",
        "customer_note": "notes for the customer"
      },
      "created_at": "2026-03-18T10:00:00.000Z"
    }
  }
}

order.completed

{
  "id": "evt_abc123def456",
  "type": "order.completed",
  "created_at": "2026-03-18T10:05:00.000Z",
  "data": {
    "object": {
      "order_id": "ord_xxx",
      "order_number": 42,
      "status": "completed",
      "chain_id": 8453,
      "payer_address": "0x1234...abcd",
      "external_order_id": "INV-2025-001",
      "metadata": {
        "order_id": "INV-2025-001",
        "callback_url": "https://shop.com/confirm?session=abc",
        "customer_note": "notes for the customer"
      },
      "completed_at": "2026-03-18T10:05:00.000Z"
    }
  }
}

order.failed

Same structure as order.completed, with status: "failed" or status: "expired" and a failed_at timestamp.

Pre-Payment Status Check

Before sending a customer to the payment page, check if the order is already paid using the /check endpoint:

GET /api/v1/orders/check?link_id={link_id}&external_order_id={order_id}

Response:

{ "status": "none" }
{ "status": "pending", "order_id": "ord_xxx" }
{ "status": "completed", "order_id": "ord_xxx", "message": "This order has been paid." }

The payment page performs this check automatically on load and displays an “Already Paid” screen if the order is completed.