Documentation

Order Failed

Process order.failed webhooks and record failed payment details.

Handle order.failed Events

Handle failed payment notifications by updating the related order and recording the reason provided by Amwal.

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.

Process the event

  1. Match the event to the related order or payment attempt.
  2. Mark the order or payment attempt as failed.
  3. Store failure_reason when it is included in the payload so your support team can review it later.
  4. Do not fulfill the order unless you receive a later successful payment event.
  5. Return HTTP 200 after your system accepts the event.

Example payload

The following example uses dummy data. Do not include real customer details, merchant credentials, or signed URLs in documentation.

{
  "id": "11111111-2222-4333-8444-555555555555",
  "fees": "0.00000",
  "type": "PRODUCTION",
  "taxes": "125.00000",
  "amount": "1000.00000",
  "issuer": null,
  "number": "412013xxxxxx1234",
  "ref_id": "merchant-order-1001",
  "status": "fail",
  "gateway": 11,
  "discount": "50.00000",
  "shipping": "0.00000",
  "trx_lang": "en",
  "amwal_fee": "25.00",
  "bank_name": "EXAMPLE_BANK",
  "card_type": "",
  "created_at": "2026-01-15T10:30:00.000000+03:00",
  "store_logo": "https://example.com/store-logo.png",
  "branch_name": "Main Branch",
  "card_holder": "",
  "merchant_id": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
  "murabha_fee": "0.00",
  "app_notified": false,
  "client_email": "[email protected]",
  "gateway_type": 4,
  "merchant_key": "prod-amwal-example-key",
  "paymentBrand": "VISA",
  "store_domain": "https://store.example.com",
  "total_amount": "1050.00",
  "amwal_tax_vat": "3.75",
  "approval_type": null,
  "hypersplit_id": null,
  "is_refundable": false,
  "order_details": null,
  "failure_reason": "INSUFFICIENT_FUNDS: Not sufficient funds",
  "funding_method": null,
  "payment_amount": "1050.00",
  "payment_method": "Apple Pay",
  "payment_option": "Installment",
  "refund_tracker": null,
  "address_details": {
    "city": "Riyadh",
    "email": "[email protected]",
    "state": "Riyadh Region",
    "country": "SA",
    "street1": "123 Example Street",
    "postcode": "12345",
    "last_name": "Customer",
    "first_name": "Example"
  },
  "convenience_fee": "0.00",
  "disputed_status": null,
  "installment_fee": "37.50",
  "merchant_domain": "https://store.example.com",
  "merchant_payout": "987.50",
  "murabha_fee_vat": "0.00",
  "payment_link_id": "",
  "refunded_amount": "0.00",
  "address_required": false,
  "brand_percentage": "2.20",
  "brand_static_fee": "0.00",
  "card_bank_issuer": "",
  "client_last_name": "Customer",
  "shipping_details": {
    "id": "free_shipping:1",
    "tax": 0,
    "label": "Free shipping",
    "price": 0
  },
  "supports_stc_pay": false,
  "client_first_name": "Example",
  "client_registered": false,
  "payment_link_lang": "en",
  "card_last_4_digits": "1234",
  "card_payment_brand": "VISA",
  "installment_status": "Pending",
  "client_phone_number": "+966500000000",
  "installment_fee_vat": "5.63",
  "installment_tracker": {
    "id": "123456",
    "status": "P",
    "message": null
  },
  "has_new_registration": false,
  "hyperpay_checkout_id": null,
  "installment_duration": "12",
  "is_approved_by_client": null,
  "merchant_country_code": "SA",
  "merchant_business_name": "Example Store",
  "billing_address_required": false,
  "payment_link_description": "",
  "payment_link_callback_url": "https://store.example.com/payment/callback",
  "payment_link_show_shipping": false,
  "payment_link_passkey_enabled": true,
  "merchant_english_business_name": "Example Store",
  "payment_link_only_show_pay_in_full": true,
  "payment_link_only_show_bank_installments": true
}
📘

Map payload identifiers to your records

The payload id maps to the Amwal transaction_id. Use order_details.order_id to match the event to the order ID in your system.


Updated 1 day ago

Did this page help you?