Webhook Payloads

When an event occurs, AstraPay sends a POST request to your webhook URL with the following structure.

---

Payload format

{
  "event": "payment.completed",
  "timestamp": "2026-03-31T12:05:00.000Z",
  "data": {
    "payment_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "short_id": "pXk9mQ",
    "amount": 25.00,
    "token": "USDC",
    "network": "BASE",
    "status": "completed",
    "transaction_hash": "0xabc123...",
    "test_mode": false
  }
}

---

Request headers

Header	Description
Content-Type	application/json
X-AstraPay-Signature	HMAC signature for verification
X-AstraPay-Event	Event type (e.g. payment.completed)

---

Payload by event type

payment.completed

{
  "event": "payment.completed",
  "timestamp": "2026-03-31T12:05:00.000Z",
  "data": {
    "payment_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "short_id": "pXk9mQ",
    "amount": 25.00,
    "token": "USDC",
    "network": "BASE",
    "status": "completed",
    "transaction_hash": "0xabc123...",
    "test_mode": false
  }
}

payment.expired

{
  "event": "payment.expired",
  "timestamp": "2026-04-01T12:00:00.000Z",
  "data": {
    "payment_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "short_id": "pXk9mQ",
    "amount": 25.00,
    "token": "USDC",
    "network": "BASE",
    "status": "expired",
    "transaction_hash": null,
    "test_mode": false
  }
}

payment.canceled

{
  "event": "payment.canceled",
  "timestamp": "2026-03-31T12:02:00.000Z",
  "data": {
    "payment_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "short_id": "pXk9mQ",
    "amount": 25.00,
    "token": "USDC",
    "network": "BASE",
    "status": "canceled",
    "transaction_hash": null,
    "test_mode": false
  }
}

payment.partially_paid

{
  "event": "payment.partially_paid",
  "timestamp": "2026-03-31T12:03:00.000Z",
  "data": {
    "payment_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "short_id": "pXk9mQ",
    "amount": 25.00,
    "token": "USDC",
    "network": "BASE",
    "status": "partially_paid",
    "transaction_hash": "0xabc123...",
    "test_mode": false
  }
}

Always use metadata in the original payment creation to attach your internal order_id or user_id. These are returned in the full payment object when you fetch it via the API after receiving a webhook — giving you the context to fulfill the order.