Events Reference

Morph Payments notifies your application of payin order lifecycle changes by sending an HTTP POST request to the webhook URL you configured. Each request delivers a single order status event as a JSON body.

Payout and refund write APIs do not emit these events. Poll List Payouts / Get Payout or List Refunds for terminal success / failed.

Every request is signed. Before trusting a payload, verify the signature as described in Signature Verification — without verification, an attacker could forge webhook requests to your endpoint. As an additional safeguard, also restrict your endpoint to Morph Payments' egress IP addresses, listed in Signature Verification.

Delivery

Property	Value
Method	`POST`
Content-Type	`application/json`
Target	The webhook URL registered for your merchant account
Success	Your endpoint returns any `2xx` status code
Failure	Any non-`2xx` response, timeout, or connection error

Respond with a 2xx status code as soon as you have accepted the event. Perform any slow processing asynchronously — a slow response is treated as a failed delivery and will be retried.

Event types

The event type is carried in the status field of the payload.

`status`	Meaning
`success`	The order was paid successfully. `paid_at` is set.
`failed`	The order failed.
`expired`	The order expired before it was paid.

Payload

The webhook body is a JSON object with the following fields.

Field	Type	Description
`event_id`	string	Unique identifier for this event. Use it for idempotency (see below).
`platform_order_id`	string	Morph Payments order identifier.
`merchant_id`	string	Your merchant identifier.
`payee_order_id`	string	Your own order reference supplied when the order was created.
`status`	string	Order status: `success`, `failed`, or `expired`.
`amount`	string	Order amount as a decimal string. Never parse as a float.
`pay_token`	string	Token used for payment.
`pay_network`	string	Network the payment was made on.
`tx_hash`	string	On-chain transaction hash.
`source_type`	string	Origin of the order.
`source_id`	string	Identifier within the source.
`receiving_network`	string	Network funds were received on.
`receiving_address`	string	Address funds were received at.
`receiving_token_address`	string	Token contract address for the received funds.
`payer_address`	string	Address that paid the order.
`paid_at`	integer	Payment time in Unix milliseconds. `0` when `status` is not `success`.
`reference_id`	string	Your own business reference, if you supplied one when creating the invoice. Empty string when not provided.
`event_time`	integer	Time the event occurred, in Unix milliseconds.
`created_at`	integer	Order creation time, in Unix milliseconds.
`updated_at`	integer	Last update time, in Unix milliseconds.

note

Amounts are decimal strings and timestamps are integer Unix milliseconds. Always handle amount as a string to avoid precision loss.

Example

{
  "event_id": "evt_...",
  "platform_order_id": "ord_...",
  "merchant_id": "mch_...",
  "payee_order_id": "your-order-...",
  "status": "success",
  "amount": "12.500000",
  "pay_token": "USDC",
  "pay_network": "morph",
  "tx_hash": "0x...",
  "source_type": "checkout",
  "source_id": "chk_...",
  "receiving_network": "morph",
  "receiving_address": "0xReceiver...",
  "receiving_token_address": "0xToken...",
  "payer_address": "0xPayer...",
  "paid_at": 1752566400000,
  "reference_id": "your-ref-...",
  "event_time": 1752566400500,
  "created_at": 1752566100000,
  "updated_at": 1752566400500
}

Idempotency

The same event may be delivered more than once — for example when your endpoint was slow to respond and a retry was triggered before your 2xx was received.

Treat event_id as the idempotency key. Record the event_id values you have already processed and ignore duplicates.

Retries

If a delivery does not receive a 2xx response, Morph Payments retries the event using an exponential backoff schedule. There are up to 5 retry attempts:

Retry	Wait after previous attempt
1	1 minute
2	5 minutes
3	15 minutes
4	60 minutes
5	240 minutes

After all retries are exhausted without a 2xx response, the event is marked as undeliverable and no further attempts are made.