Event Types

Overview of supported event types

Supported Event Types

Event Type	Description	Trigger Condition
`order.created`	New order initiated	Customer starts checkout process
`order.success`	Payment successful	Payment confirmed and completed
`order.failed`	Payment failed	Payment declined, failed, or cancelled
`order.updated`	Order Refund	Contain the Bank gateway refund details.
`installment.tracker.approved`	The installment is approved	Contain the Installment tracker object with its status "A"
`installment.tracker.rejected`	The installment is rejected	Contain the Installment tracker object with its status "R"
`order.disputed`	Chargeback dispute update	Contains `disputed_status` to identify the chargeback status: `PENDING`, `RESOLVED`, or `LOST`.

`order.failed` Scenario

Amwal sends the order.failed webhook when a payment attempt cannot be completed. This can happen when the payment is declined, fails at the payment gateway, or is cancelled before completion.

Use this event to mark the order or payment attempt as failed in your system. If the payload includes failure_reason, store it with the order so your support team can review the failure reason later.

Example `order.failed` Payload

{
  "event_type": "order.failed",
  "data": {
    "id": "order_123456789",
    "ref_id": "merchant-order-1001",
    "status": "failed",
    "amount": "250.00000",
    "currency": "SAR",
    "payment_method": "Card",
    "payment_option": "Pay In Full",
    "failure_reason": "Payment was declined by the issuer bank"
  }
}

When you receive an order.failed event:

Mark the related order or payment attempt as failed.
Store failure_reason when it is included in the payload.
Do not fulfill the order unless a later successful payment event is received.
Return HTTP 200 after your system accepts the event.

Updated 9 days ago