QR Payments webhooks

​

Event types

​

Payload

{
  "webhook_event_id": "0198f31a-7c2b-7d91-9fa2-112233445566",
  "webhook_event_type": "payment_intent.captured",
  "api_version": "2026-05",
  "created_at": "2026-09-05T12:00:05.000Z",
  "data": {
    "intent": {
      "id": "0198f31a-7c2b-7d91-9fa2-112233445567",
      "partner_id": "example_partner",
      "partner_user_id": "usr_8f3ka92m",
      "amount_usd_cents": 14000,
      "corridor": "vn_vietqr",
      "status": "captured",
      "provider_quote_id": null,
      "provider_local_amount_minor_units": "3500000",
      "provider_local_currency": "VND",
      "created_at": "2026-09-05T12:00:00.000Z",
      "updated_at": "2026-09-05T12:00:05.000Z"
    }
  }
}

​

Verify the request

X-Zennopay-Key-Id: <outbound key id>
X-Zennopay-Timestamp: <RFC3339 timestamp>
X-Zennopay-Nonce: <64 hex characters>
X-Zennopay-Signature: <base64 HMAC-SHA256>
X-Zennopay-Webhook-Event-Id: <event id>
X-Zennopay-Webhook-Event-Type: payment_intent.captured

1. Select the outbound webhook secret for the key ID and environment. This is separate from your API signing secret.
2. Read the exact raw request body bytes. Check the timestamp against your allowed clock window and validate the nonce and signature formats.
3. Build the HMAC canonical string with POST, your endpoint’s pathname including its query string, timestamp, nonce, and SHA-256 body hash. Include the trailing newline.
4. Compare the received and computed signatures in constant time. Reject malformed signatures, including a different decoded length.
5. Check and record the nonce atomically to reject request replays. Verify the signature before storing the event or changing payment state.

​

Acknowledge and reconcile

• Return 2xx after durably storing the verified event. An already-stored event may be acknowledged again without repeating its accounting effects.
• Deduplicate by webhook_event_id. Delivery is at least once, and ordering is not guaranteed.
• Network and 5xx failures are retried with backoff up to the configured attempt limit. Exhausted deliveries are retained for operator replay.
• A 4xx response is treated as a permanent failure and is not automatically retried. Return 5xx when a temporary storage failure prevents acceptance.
• Retrieve GET /v1/payment_intents/{id} when events arrive out of order or local state is uncertain. See Reconciliation.