Transaction Webhooks

Webhooks provide real-time notifications to merchants about transaction and refund status changes. Merchants can configure a callback URL to receive these updates, which include event details and a signature for verification.

Configuring Webhook URLs

Merchants can configure Server-to-Server (S2S) callback URLs in the merchant dashboard.

Supported Event Types

• TRANSACTION_COMPLETED
• TRANSACTION_FAILED
• REFUND_SUCCESS
• REFUND_FAILED

Validation & Response Flow

• Receive a webhook payload containing a signature.
• Verify the signature using the HMAC method (described in Signature Verification for Payment Response).
• Acknowledge successful processing:

res.status(204).send();

• On error, respond with an appropriate status code and message:

res.status(400).send('Signature mismatched');

Webhook Response: Transaction Completed

{
  "eventType": "TRANSACTION_COMPLETED",
  "data": {
    "paymentId": "paycbaff3b9dc5443f0ba0997970ebeddfa",
    "orderId": "wb-bf35c7de-1e8f-425a-8833-bc23d609b256",
    "receiptId": "",
    "transactionType": "sales",
    "paymentStatus": "success",
    "paymentMethod": "card",
    "amount": "1.00",
    "currency": "OMR",
    "initiatedAt": "2025-05-29T07:21:19.845Z",
    "completedAt": "2025-05-29T07:21:19.846Z",
    "signature": "10ff8c4ddbeb8fcf24fcc110acb31599690a8057ecd3a7141b22354f9b73337f",
    "description": "Transaction completed",
    "paymentDetails": {
      "cardNetwork": "visa",
      "cardType": "credit",
      "cardUsageType": "domestic"
    }
  }
}

Webhook Response: Transaction Failed

{
  "eventType": "TRANSACTION_FAILED",
  "data": {
    "paymentId": "paycbaff3b9dc5443f0ba0997970ebeddfa",
    "orderId": "wb-bf35c7de-1e8f-425a-8833-bc23d609b256",
    "receiptId": "",
    "transactionType": "sales",
    "paymentStatus": "failure",
    "paymentMethod": "card",
    "amount": "1.00",
    "currency": "OMR",
    "initiatedAt": "2025-05-29T07:21:19.845Z",
    "completedAt": "2025-05-29T07:21:19.846Z",
    "description": "Transaction failed",
    "signature": "10ff8c4ddbeb8fcf24fcc110acb31599690a8057ecd3a7141b22354f9b73337f",
    "paymentDetails": {
      "cardNetwork": "visa",
      "cardType": "credit",
      "cardUsageType": "domestic"
    }
  }
}

Webhook Response: Refund Success

{
  "eventType": "REFUND_SUCCESS",
  "data": {
    "refundId": "refundcff3b9dc5443f0ba0997970ebeddfa",
    "paymentId": "paycbaff3b9dc5443f0ba0997970ebeddfa",
    "orderId": "wb-bf35c7de-1e8f-425a-8833-bc23d609b256",
    "receiptId": "",
    "paymentStatus": "success",
    "paymentMethod": "card",
    "amount": "1.00",
    "currency": "OMR",
    "initiatedAt": "2025-05-29T07:21:19.845Z",
    "completedAt": "2025-05-29T07:21:19.846Z",
    "description": "Refund completed",
    "signature": "10ff8c4ddbeb8fcf24fcc110acb31599690a8057ecd3a7141b22354f9b73337f"
  }
}

Webhook Response: Refund Failed

{
  "eventType": "REFUND_FAILED",
  "data": {
    "refundId": "refundcff3b9dc5443f0ba0997970ebeddfa",
    "paymentId": "paycbaff3b9dc5443f0ba0997970ebeddfa",
    "orderId": "wb-bf35c7de-1e8f-425a-8833-bc23d609b256",
    "receiptId": "",
    "paymentStatus": "failure",
    "paymentMethod": "card",
    "amount": "1.00",
    "currency": "OMR",
    "initiatedAt": "2025-05-29T07:21:19.845Z",
    "completedAt": "2025-05-29T07:21:19.846Z",
    "description": "Refund failed",
    "signature": "10ff8c4ddbeb8fcf24fcc110acb31599690a8057ecd3a7141b22354f9b73337f"
  }
}