The merchant can subscribe to Payment and Refund notification webhooks by populating notificationUrl when calling the Create Payment API and the Create Refund API respectively.


For security reasons, the merchant must make server-side calls, such as Get Payment Status API, upon receiving a webhook call to verify the status before finalising the order.


The merchant must whitelist Waave's IP addresses below to allow webhook calls.




Webhook payloads use the same schema for both Payment Session and Refund notifications, and the entityType field indicates which object it is for:

  • PAYMENT_SESSION - the notification is for a payment session status change.
  • REFUND - the notification is for a refund status change.

Payment Notifications

Sample Payload

    "identifier": "c71892ae-1237-495b-b94c-6f1e290f84a3",
    "businessCode": "bens_bakeshop",
    "entityType": "PAYMENT_SESSION",
    "status": "INSTRUCTION_SENT",
    "customerReference": "1-36-pay-12345"

The identifier field contains the original paymentSessionId.

The following status values are posted by the webhook:

  • INSTRUCTION_SENT - the shopper has authorised the payment.
  • CANCELLED - The payment has been cancelled by the merchant or the shopper.
  • DECLINED - The payment was declined by Waave.
  • ERROR - There was an error while processing the payment session.

Refund Notifications

    "identifier": "371ef9d1-d620-4a06-a775-261eae16c2b1",
    "businessCode": "bens_bakeshop",
    "entityType": "REFUND",
    "status": "ACCEPTED",
    "customerReference": "refund-12345"

The identifier field contains the original refundId.

For refunds, the following status values are posted by the webhook:

  • ACCEPTED - The refund request was accepted by Waave.
  • FAILED - The funds could not be transferred.

Optionally, if the merchant is interested in being notified when the fund is successfully returned to the customer, they can subscribe to COMPLETE status updates. Please discuss with Waave team if this is of interest.