payment-request.completed
The payment-request.completed event is fired automatically when a checkout or payment request is successfully settled.
- Fires When: A customer successfully pays a checkout or payment request (e.g., purchasing a plan, topping up a balance, or other payment flows).
Payload Field Reference
The event data contains the following fields inside the nested data object:
| Field | Type | Description |
|---|---|---|
payment_request_id | string | The unique ID of the payment request that completed. |
project_id | string | The project ID that contains this payment. Duplicates the X-Project-ID header. |
amount | string | The NET payment amount in standard currency units (e.g., '19.99' for $19.99, or '0.005' for 0.005 BTC). Always a string—never a JSON number—to preserve monetary precision. |
gross_amount | string (conditional) | The provider charge total (NET + VAT). Present when a stored provider charge total exists (provider-charged central rows); it may equal amount when VAT is 0, and is omitted (never null) for internal-balance, local-project, and legacy rows. Coalesce gross_amount ?? amount for "what was charged"; do not infer VAT from its presence. |
currency | string | ISO 4217 currency code (e.g., 'USD', 'EUR') or cryptocurrency symbol (e.g., 'BTC', 'USDT'). |
settled_at | string | null | ISO 8601 UTC timestamp of settlement, when known. |
is_test | boolean | true if the payment was produced in test mode. |
Full Example Envelope
{
"id": "8c2b1a4f-9e3d-4a5b-bc12-3d4e5f6a7b8c",
"event": "payment-request.completed",
"created_at": "2026-05-25T10:00:00.000Z",
"schema_version": "v1",
"data": {
"payment_request_id": "7a356073-61e8-466d-8c17-f58c7042a975",
"project_id": "93425026-6bb8-4f81-a75d-63f538e1a123",
"amount": "19.99",
"gross_amount": "23.99",
"currency": "USD",
"settled_at": "2026-05-25T09:59:58.412Z",
"is_test": false
}
}Next Steps
- Learn how to secure your receiver in Signature Verification.
- Implement idempotency and handling rules in Deduplication & Retries.