Refunds

1 - Get Access Token

Implement logic to pass your client id and secret to the Waave token API to obtain an access token. The access token returned by this logic will be required to make subsequent calls to Waave APIs.

🚧

The merchant client id and secret must not be exposed to the browser. In addition, access tokens that are issued with refunds scopes must not be exposed to the browser.

Token API end point URIs:

• Production: https://api.au.app.waave.com/token
• Sandbox: https://api.au.app.waavetest.com/token

Sample Request

{
    "client_id":MERCHANT_CLIENT_ID,
    "client_secret":MERCHANT_CLIENT_SECRET,
    "scope":"refunds:create refunds.status:read"
}

Sample Response

{
    "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxYjg3MGNkNy1lODdjLTRkZTYtYTExNS05Y2I1NzBkZDk5NTIiLCJhdXRoIjoiUk9MRV9XU19VU0VSIiwic2NvcGUiOiJwYXltZW50LXNlc3Npb25zOmNyZWF0ZSBwYXltZW50LXNlc3Npb25zLnN0YXR1czpyZWFkIiwiZXhwIjoxNjU0ODI1OTgwfQ.nOZNzpHicZkFtmsK4LJNRD44QuGlja8UBoyv_1JiUlTdGYTadq0Qe_yK8LV9e_RMgKeusb6xTk0ZbMzj6bgbZn7h9ZC6g942gjhFyIIQwY0tpLaFcU5cC5wfdcIIwdKDHcQNnXz1J6mNHnJlmgbmRijYdR21q-CxFZJ3j3TScYUDAyoz9_8usI8UeLjWrzveU1DZvGd1jKJFmnqDJntuBtDjW107rADZaaGrAmidC-QXrLJx90z7YxVu8N5B0lQTd67mQILWpONAVLLeFTCDEtQEMXLb1O_ENlYw6ZdyF8RzukfW0Nz91OMml86VlrRKG1IaiSKg1WhyI9YvhiTiuQ",
    "expires": 86400
}

2 - Initiate a Refund

Using the access token obtained, call Refunds API to initiate a refund.

Sample Request

{
    "originalPaymentSessionId": "c71892ae-1237-495b-b94c-6f1e290f84a3",  
    "amount": 150,
    "currency": "AUD",
    "customerReference": "refund-order-12345",
    "description": "refund description",
    "notificationUrl" : "https://your_notification_url",
    "businessCode" : "your_business_code"
}

The notificationUrl is an optional field. If populated, Waave will trigger a webhook call to the specified URL when the refund status is updated. See the Webhook section below.

This API supports idempotency. See this section for more detail.

Sample Response

{
    "refundId": "f793ac94-61e4-497d-935e-0c40453f9bd2",
    "originalPaymentSessionId": "c71892ae-1237-495b-b94c-6f1e290f84a3",
    "amount": 150,
    "currency": "AUD",
    "customerReference": "refund-order-12345",
    "description": "refund description",
    "notificationUrl" : "https://your_notification_url",
    "businessCode" : "your_business_code",
    "status": "ACCEPTED"
}

Waave performs pre-validation on the request, such as checking if the total refunded amount exceeds the original tender amount.

A successful response (200) indicates the pre-validation passed, and the refund request has been accepted by Waave.

A negative response (4xx) indicates the pre-validation failed, and the refund request was not accepted by Waave. The response message will contain a description as to why the validation failed.

3 - Funds Transfer

After a successful refund acceptance, the funds are typically transfered back to the shopper within 1 to 4 business days.

In the unlikely event that the funds transfer fails due to issues with the financial institutions involved, Waave notifies the merchant using webhooks (if notificationUrl was populated when initiating the refund). For example, the shopper may have closed the bank account used for the purchase. See Webhooks for more details.

Alternatively, the merchant can query the status of the refund by calling the Refunds Status API with the refundId.

Based on the status being returned, you must take different actions:

• ACCEPTED - The refund request was accepted by Waave.
• FAILED - The refund could not be processed and Waave will no longer attempt to process this refund.
• COMPLETE - The fund has been returned to the shopper.

There are other interim statuses that the API can return such as 'PENDING' and 'RETRYING'. These statuses indicate that the refund is still being processed and there are no actions required by the merchant.

Sample Response:

{
    "status": "COMPLETE",
    "reason": null
}