CoinVoyage webhook event types and payload reference

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.

{
  "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.

{
  "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

payorder_created

Triggered when a new PayOrder is created. The payment_data field is not yet available at this stage.

{
  "type": "payorder_created",
  "status": "PENDING",
  "payorder_id": "po_abcdef123456",
  "metadata": { }
}

payorder_started

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.

{
  "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"
  }
}

payorder_confirming

Triggered when payment has been detected on-chain and is awaiting the required number of confirmations.

{
  "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"
  }
}

payorder_executing

Triggered when CoinVoyage starts executing the destination transfer or contract call after the source payment is confirmed.

{
  "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"
  }
}

payorder_completed

Triggered when the PayOrder has completed successfully and settlement has been delivered to the receiving address.

{
  "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"
  }
}

payorder_error

Triggered when an error occurs during PayOrder processing. The message field contains a description of the error. payment_data is not included.

{
  "type": "payorder_error",
  "status": "FAILED",
  "payorder_id": "po_abcdef123456",
  "metadata": { },
  "message": "Error description"
}

payorder_refunded

Triggered when funds have been refunded to the user. The refund_tx_hash and refund_address fields identify the refund transaction and destination.

{
  "type": "payorder_refunded",
  "status": "REFUNDED",
  "payorder_id": "po_abcdef123456",
  "metadata": { },
  "refund_tx_hash": "0xghi789...",
  "refund_address": "0x1234567890abcdef..."
}

payorder_expired

Triggered when the PayOrder expires before payment was received. No metadata or payment_data is included in the minimal expiry payload.

{
  "type": "payorder_expired",
  "status": "EXPIRED",
  "payorder_id": "po_abcdef123456"
}

​Event types

​Base event payload structure

​PaymentData structure

​Payload examples

Event types

Base event payload structure

PaymentData structure

Payload examples