payment-request.completed
The payment-request.completed event is sent when a checkout or payment request completes. Completion does not necessarily mean money moved.
It covers paid checkouts and completed zero-price checkouts, including free plans, fully discounted purchases and eligible trial receipts. Check amount and the payment request's status when reconciling access and payments.
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) | Confirmed gross checkout total, when available. Omitted when unavailable; never null. It may equal amount. Absence does not mean zero, and its presence alone does not establish VAT. |
currency | string | ISO 4217 currency code (e.g., 'USD', 'EUR') or cryptocurrency symbol (e.g., 'BTC', 'USDT'). |
settled_at | string | null (optional) | UTC ISO timestamp with milliseconds when known. May be null or omitted. |
is_test | boolean | true if the payment was produced in test mode. |
user_id | string (optional) | The member associated with the completed payment request, when available. |
plan_id | string (optional) | The plan associated with the completed payment request, when available. |
membership_id | string (optional) | The associated membership, when available. |
Full Example Envelope
The envelope contains id, event, created_at, schema_version and data. An optional meta field is an opaque JSON object; its properties can vary.
{
"id": "8c2b1a4f-9e3d-4a5b-bc12-3d4e5f6a7b8c",
"event": "payment-request.completed",
"created_at": "2026-05-25T10:00:00.000Z",
"schema_version": "v1",
"meta": {},
"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,
"user_id": "123456789012345678",
"plan_id": "22222222-2222-4222-8222-222222222222",
"membership_id": "33333333-3333-4333-8333-333333333333"
}
}Zero-price completion example
Free plans, fully discounted checkouts and eligible trial receipts can complete with an amount of "0". A confirmed gross total need not be present.
{
"id": "6c568cee-d8c6-42f0-aa55-fcc8fbb09a11",
"event": "payment-request.completed",
"created_at": "2026-10-23T10:00:00.000Z",
"schema_version": "v1",
"data": {
"payment_request_id": "7a356073-61e8-466d-8c17-f58c7042a975",
"project_id": "93425026-6bb8-4f81-a75d-63f538e1a123",
"amount": "0",
"currency": "USD",
"settled_at": null,
"is_test": true
}
}Next Steps
- Learn how to secure your receiver in Signature Verification.
- Implement idempotency and handling rules in Deduplication & Retries.