Webhooks

Introduction

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.

Authentication

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

Sandbox:

13.211.55.178
54.66.167.248
52.64.117.142

Production:

54.206.243.236
3.104.203.142
3.24.151.247

Payload

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-pay-1234"
}

The identifier field contains the 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.

Refund Notifications

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

The identifier field contains the 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 contact the Waave support team if this is of interest.

Agreement Notifications

Sample Payload

{
    "identifier": "d441ffaa-bb23-767b-b31c-f5c3f528ae3b",
    "businessCode": "bens_bakeshop",
    "entityType": "RECURRING_AGREEMENT",
    "status": "AUTHORISED",
    "customerReference": "3-agree-5678"
}

The identifier field contains the recurringAgreementId.

The following status values are posted by the webhook:

• AUTHORISED - the shopper has authorised the agreement.
• CANCELLED - The agreement has been cancelled by the merchant or the shopper.
• DECLINED - The agreement was declined by the Shopper.
• ERROR - There was an error while processing the agreement.

Payout Notifications

{
    "identifier": "54dcc608-7366-8872-6405-4fe2a26c9421",
    "businessCode": "bens_bakeshop",
    "entityType": "PAYOUT",
    "status": "COMPLETE",
    "customerReference": "4-payout-5678"
}

The identifier field contains the payoutId.

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

• COMPLETE - The funds were successfully paid out.
• FAILED - The funds could not be paid out.