> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coinvoyage.io/llms.txt
> Use this file to discover all available pages before exploring further.
# CoinVoyage webhook event types and payload reference
> Every PayOrder webhook event with its subscription identifier, payload type value, and full JSON example delivered to your endpoint.
CoinVoyage emits a webhook event at each stage of the PayOrder lifecycle. For every event you subscribe to, CoinVoyage delivers a `POST` request to your endpoint containing a JSON payload that describes what changed. This page covers every event type, the payload structures you can expect, and a full example for each.
There is a naming difference between the identifiers you use when subscribing to events and the `type` field in the delivered payload. Subscription identifiers use uppercase `ORDER_*` format. The `type` field in the JSON payload uses lowercase `payorder_*` format. For example, subscribing to `ORDER_COMPLETED` results in payloads where `"type": "payorder_completed"`.
## Event types
| Subscription identifier | Payload `type` | Description |
| ------------------------ | --------------------- | ------------------------------------------------------------------ |
| `ORDER_CREATED` | `payorder_created` | A new PayOrder was created. |
| `ORDER_AWAITING_PAYMENT` | `payorder_started` | The PayOrder is ready and awaiting payment from the user. |
| `ORDER_CONFIRMING` | `payorder_confirming` | Payment has been received and is being confirmed on-chain. |
| `ORDER_EXECUTING` | `payorder_executing` | CoinVoyage is executing the destination transfer or contract call. |
| `ORDER_COMPLETED` | `payorder_completed` | The PayOrder completed successfully. |
| `ORDER_ERROR` | `payorder_error` | An error occurred during PayOrder processing. |
| `ORDER_REFUNDED` | `payorder_refunded` | Funds were refunded to the user. |
| `ORDER_EXPIRED` | `payorder_expired` | The PayOrder expired before payment was received. |
## Base event payload structure
Every webhook delivery shares a common base structure. Additional top-level fields are present depending on the specific event type.
```json theme={null}
{
"id": "event_123456",
"type": "payorder_completed",
"status": "COMPLETED",
"payorder_id": "po_abcdef123456",
"metadata": { },
"payment_data": { }
}
```
| Field | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | Unique identifier for this event delivery. |
| `type` | Lowercase `payorder_*` string identifying the event. |
| `status` | The current PayOrder status as an uppercase string. |
| `payorder_id` | The ID of the PayOrder this event relates to. |
| `metadata` | Optional key-value metadata attached to the PayOrder at creation. |
| `payment_data` | Payment details object. Present on `payorder_started`, `payorder_confirming`, `payorder_executing`, and `payorder_completed` events. |
## PaymentData structure
The `payment_data` object is included in `payorder_started`, `payorder_confirming`, `payorder_executing`, and `payorder_completed` events. It contains source and destination amounts, addresses, transaction hashes, and execution details.
```json theme={null}
{
"src": {
"total": { },
"base": { },
"fees": { },
"gas": { }
},
"dst": {
"currency": { },
"currency_amount": { }
},
"deposit_address": "0x...",
"receiving_address": "0x...",
"refund_address": "0x...",
"source_tx_hash": "0x...",
"destination_tx_hash": "0x...",
"refund_tx_hash": "0x...",
"execution": [
{
"provider": "...",
"status": "...",
}
],
"expires_at": "2025-01-15T11:00:00Z"
}
```
| Field | Description |
| --------------------- | ------------------------------------------------------------------- |
| `src` | Source-side amounts broken down into total, base, fees, and gas. |
| `dst` | Destination currency and the amount to be received. |
| `deposit_address` | The address the user should send payment to. |
| `receiving_address` | The address that will receive the settled funds. |
| `refund_address` | The address funds are returned to if a refund occurs. |
| `source_tx_hash` | Transaction hash of the incoming payment on the source chain. |
| `destination_tx_hash` | Transaction hash of the outgoing transfer on the destination chain. |
| `refund_tx_hash` | Transaction hash of the refund transaction, if applicable. |
| `execution` | Array of execution steps, each with a provider and status. |
| `expires_at` | ISO 8601 timestamp after which the PayOrder expires. |
## Payload examples
Triggered when a new PayOrder is created. The `payment_data` field is not yet available at this stage.
```json theme={null}
{
"type": "payorder_created",
"status": "PENDING",
"payorder_id": "po_abcdef123456",
"metadata": { }
}
```
Triggered when the PayOrder is ready and waiting for the user to send payment. The `payment_data` field is now populated, including the `deposit_address` and `expires_at`.
```json theme={null}
{
"type": "payorder_started",
"status": "AWAITING_PAYMENT",
"payorder_id": "po_abcdef123456",
"metadata": { },
"payment_data": {
"src": {
"total": { },
"base": { },
"fees": { },
"gas": { }
},
"dst": {
"currency": { },
"currency_amount": { }
},
"deposit_address": "0x...",
"receiving_address": "0x...",
"refund_address": "0x...",
"source_tx_hash": null,
"destination_tx_hash": null,
"refund_tx_hash": null,
"execution": [],
"expires_at": "2025-01-15T11:00:00Z"
}
}
```
Triggered when payment has been detected on-chain and is awaiting the required number of confirmations.
```json theme={null}
{
"type": "payorder_confirming",
"status": "AWAITING_CONFIRMATION",
"payorder_id": "po_abcdef123456",
"metadata": { },
"payment_data": {
"src": {
"total": { },
"base": { },
"fees": { },
"gas": { }
},
"dst": {
"currency": { },
"currency_amount": { }
},
"deposit_address": "0x...",
"receiving_address": "0x...",
"refund_address": "0x...",
"source_tx_hash": "0xabc123...",
"destination_tx_hash": null,
"refund_tx_hash": null,
"execution": [],
"expires_at": "2025-01-15T11:00:00Z"
}
}
```
Triggered when CoinVoyage starts executing the destination transfer or contract call after the source payment is confirmed.
```json theme={null}
{
"type": "payorder_executing",
"status": "EXECUTING_ORDER",
"payorder_id": "po_abcdef123456",
"metadata": { },
"payment_data": {
"src": {
"total": { },
"base": { },
"fees": { },
"gas": { }
},
"dst": {
"currency": { },
"currency_amount": { }
},
"deposit_address": "0x...",
"receiving_address": "0x...",
"refund_address": "0x...",
"source_tx_hash": "0xabc123...",
"destination_tx_hash": null,
"refund_tx_hash": null,
"execution": [
{ "provider": "...", "status": "pending" }
],
"expires_at": "2025-01-15T11:00:00Z"
}
}
```
Triggered when the PayOrder has completed successfully and settlement has been delivered to the receiving address.
```json theme={null}
{
"type": "payorder_completed",
"status": "COMPLETED",
"payorder_id": "po_abcdef123456",
"metadata": { },
"payment_data": {
"src": {
"total": { },
"base": { },
"fees": { },
"gas": { }
},
"dst": {
"currency": { },
"currency_amount": { }
},
"deposit_address": "0x...",
"receiving_address": "0x...",
"refund_address": "0x...",
"source_tx_hash": "0xabc123...",
"destination_tx_hash": "0xdef456...",
"refund_tx_hash": null,
"execution": [
{ "provider": "...", "status": "completed" }
],
"expires_at": "2025-01-15T11:00:00Z"
}
}
```
Triggered when an error occurs during PayOrder processing. The `message` field contains a description of the error. `payment_data` is not included.
```json theme={null}
{
"type": "payorder_error",
"status": "FAILED",
"payorder_id": "po_abcdef123456",
"metadata": { },
"message": "Error description"
}
```
Triggered when funds have been refunded to the user. The `refund_tx_hash` and `refund_address` fields identify the refund transaction and destination.
```json theme={null}
{
"type": "payorder_refunded",
"status": "REFUNDED",
"payorder_id": "po_abcdef123456",
"metadata": { },
"refund_tx_hash": "0xghi789...",
"refund_address": "0x1234567890abcdef..."
}
```
Triggered when the PayOrder expires before payment was received. No `metadata` or `payment_data` is included in the minimal expiry payload.
```json theme={null}
{
"type": "payorder_expired",
"status": "EXPIRED",
"payorder_id": "po_abcdef123456"
}
```