Documentation Index
Fetch the complete documentation index at: https://docs.swiftpay.cx/llms.txt
Use this file to discover all available pages before exploring further.
Webhook Event Types
SwiftPay sends webhooks for various events in your account. Each event follows a standard envelope structure.
Webhook Structure
Every webhook request sent by SwiftPay has the following structure:
| Field | Type | Description |
|---|
id | string | Unique event identifier (e.g., evt_abc123) |
type | string | The type of event (e.g., checkout.succeeded) |
created | string | ISO 8601 timestamp of when the event occurred |
data | object | Event-specific payload (see below for types) |
Expected Response
Your server should return a 2xx HTTP status code (e.g., 200 OK, 201 Created, 204 No Content) to acknowledge receipt of the webhook.
- Timeouts: SwiftPay waits up to 30 seconds for a response.
- Retries: If your server returns any other status code (e.g.,
4xx, 5xx) or the request times out, SwiftPay will retry the delivery according to the retry schedule.
- Body: The response body is ignored, but we recommend returning a short string like
OK.
Each request includes security headers for verification:
| Header | Description |
|---|
X-Webhook-Signature | HMAC SHA-256 signature for verification. Format: t={timestamp},v1={signature} |
User-Agent | SwiftPay-Webhooks/1.0 |
Checkout Events
checkout.succeeded
Occurs when a checkout session is successfully completed and payment is received.
{
"id": "evt_checkout_abc123",
"type": "checkout.succeeded",
"created": "2024-01-15T10:30:00Z",
"data": {
"sessionId": "sess_abc123",
"amount": 2999,
"amountInDecimals": "29.99",
"currency": "USD",
"customerEmail": "customer@example.com",
"customerName": "John Doe",
"timestamp": "2024-01-15T10:30:00Z",
"shipping": {
"addressLine1": "123 Main St",
"city": "San Francisco",
"state": "CA",
"postalCode": "94102",
"country": "US"
}
}
}
Payload Fields
| Field | Type | Description |
|---|
sessionId | string | Unique checkout session identifier |
amount | integer | Total amount in cents |
amountInDecimals | string | Total amount formatted as decimal (e.g. “29.99”) |
currency | string | Three-letter ISO currency code |
customerEmail | string | Email address of the customer |
customerName | string | Full name of the customer |
timestamp | string | ISO 8601 timestamp of completion |
shipping | object | Shipping address details (if collected) |
checkout.failed
Occurs when a checkout session fails (e.g., payment declined).
{
"id": "evt_checkout_def456",
"type": "checkout.failed",
"created": "2024-01-15T10:35:00Z",
"data": {
"sessionId": "sess_def456",
"amount": 2999,
"amountInDecimals": "29.99",
"currency": "USD",
"customerEmail": "customer@example.com",
"errorMessage": "Insufficient funds",
"failedAt": "2024-01-15T10:35:00Z"
}
}
Payload Fields
| Field | Type | Description |
|---|
sessionId | string | Unique checkout session identifier |
amount | integer | Total amount in cents |
amountInDecimals | string | Total amount formatted as decimal (e.g. “29.99”) |
currency | string | Three-letter ISO currency code |
customerEmail | string | Email address of the customer |
errorMessage | string | Reason for the payment failure |
failedAt | string | ISO 8601 timestamp of failure |
Refund Events
refund.completed
Occurs when a refund is successfully processed.
{
"id": "evt_refund_def456",
"type": "refund.completed",
"created": "2024-01-15T11:05:00Z",
"data": {
"refundId": "ref_abc123",
"sessionId": "sess_abc123",
"amount": 2999,
"amountInDecimals": "29.99",
"currency": "USD",
"completedAt": "2024-01-15T11:05:00Z"
}
}
Payload Fields
| Field | Type | Description |
|---|
refundId | string | Unique refund identifier |
sessionId | string | Original checkout session identifier |
amount | integer | Refund amount in cents |
amountInDecimals | string | Refund amount formatted as decimal (e.g. “29.99”) |
currency | string | Three-letter ISO currency code |
completedAt | string | ISO 8601 timestamp of completion |
refund.failed
Occurs when a refund attempt fails.
{
"id": "evt_refund_ghi789",
"type": "refund.failed",
"created": "2024-01-15T11:10:00Z",
"data": {
"refundId": "ref_abc123",
"sessionId": "sess_abc123",
"amount": 2999,
"amountInDecimals": "29.99",
"currency": "USD",
"errorMessage": "Processor error",
"failedAt": "2024-01-15T11:10:00Z"
}
}
Payload Fields
| Field | Type | Description |
|---|
refundId | string | Unique refund identifier |
sessionId | string | Original checkout session identifier |
amount | integer | Refund amount in cents |
amountInDecimals | string | Refund amount formatted as decimal (e.g. “29.99”) |
currency | string | Three-letter ISO currency code |
errorMessage | string | Reason for the refund failure |
failedAt | string | ISO 8601 timestamp of failure |
Withdrawal Events
withdrawal.paid
Occurs when a withdrawal has been successfully paid out.
{
"id": "evt_withdrawal_def456",
"type": "withdrawal.paid",
"created": "2024-01-16T09:00:00Z",
"data": {
"withdrawalId": "wd_abc123",
"amount": 50000,
"amountInDecimals": "500.00",
"currency": "USD",
"destinationType": "bank_account",
"completedAt": "2024-01-16T09:00:00Z"
}
}
Payload Fields
| Field | Type | Description |
|---|
withdrawalId | string | Unique withdrawal identifier |
amount | integer | Withdrawal amount in cents |
amountInDecimals | string | Withdrawal amount formatted as decimal (e.g. “500.00”) |
currency | string | Three-letter ISO currency code |
destinationType | string | Type of destination (e.g. bank_account, crypto) |
completedAt | string | ISO 8601 timestamp of completion |
withdrawal.failed
Occurs when a withdrawal attempt fails.
{
"id": "evt_withdrawal_ghi789",
"type": "withdrawal.failed",
"created": "2024-01-16T09:05:00Z",
"data": {
"withdrawalId": "wd_abc123",
"amount": 50000,
"amountInDecimals": "500.00",
"currency": "USD",
"errorMessage": "Invalid bank details",
"failedAt": "2024-01-16T09:05:00Z"
}
}
Payload Fields
| Field | Type | Description |
|---|
withdrawalId | string | Unique withdrawal identifier |
amount | integer | Withdrawal amount in cents |
amountInDecimals | string | Withdrawal amount formatted as decimal (e.g. “500.00”) |
currency | string | Three-letter ISO currency code |
errorMessage | string | Reason for the withdrawal failure |
failedAt | string | ISO 8601 timestamp of failure |
