Skip to main content

Documentation Index

Fetch the complete documentation index at: https://coinvoyage-3c99945b.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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 identifierPayload typeDescription
ORDER_CREATEDpayorder_createdA new PayOrder was created.
ORDER_AWAITING_PAYMENTpayorder_startedThe PayOrder is ready and awaiting payment from the user.
ORDER_CONFIRMINGpayorder_confirmingPayment has been received and is being confirmed on-chain.
ORDER_EXECUTINGpayorder_executingCoinVoyage is executing the destination transfer or contract call.
ORDER_COMPLETEDpayorder_completedThe PayOrder completed successfully.
ORDER_ERRORpayorder_errorAn error occurred during PayOrder processing.
ORDER_REFUNDEDpayorder_refundedFunds were refunded to the user.
ORDER_EXPIREDpayorder_expiredThe 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": { }
}
FieldDescription
idUnique identifier for this event delivery.
typeLowercase payorder_* string identifying the event.
statusThe current PayOrder status as an uppercase string.
payorder_idThe ID of the PayOrder this event relates to.
metadataOptional key-value metadata attached to the PayOrder at creation.
payment_dataPayment 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"
}
FieldDescription
srcSource-side amounts broken down into total, base, fees, and gas.
dstDestination currency and the amount to be received.
deposit_addressThe address the user should send payment to.
receiving_addressThe address that will receive the settled funds.
refund_addressThe address funds are returned to if a refund occurs.
source_tx_hashTransaction hash of the incoming payment on the source chain.
destination_tx_hashTransaction hash of the outgoing transfer on the destination chain.
refund_tx_hashTransaction hash of the refund transaction, if applicable.
executionArray of execution steps, each with a provider and status.
expires_atISO 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.
{
  "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.
{
  "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.
{
  "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.
{
  "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.
{
  "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.
{
  "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.
{
  "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.
{
  "type": "payorder_expired",
  "status": "EXPIRED",
  "payorder_id": "po_abcdef123456"
}