Payments

This guide describes how the online payment flow works in detail.

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. Only short-lived access tokens must be sent to the browser.
In addition, never use refunds scope when requesting an access token for the browser.

Token API end point URIs:

Production: https://prod01.app.waave.com/authn/api/token
Sandbox: https://test01.app.waavetest.com/authn/api/token

Sample Request

{
    "client_id":MERCHANT_CLIENT_ID,
    "client_secret":MERCHANT_CLIENT_SECRET,
    "scope":"payment-sessions:create payment-sessions.status:read"
}

Sample Response

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

2 - Create a Payment Session

Using the access token obtained, call Begin Payment Session API to start a payment session.

Sample Request

{
    "customerReference": "orderRef-20220610123125",  
    "acceptanceTypes": ["APP","WEB"],
    "totalAmount": total_amount,
    "currency": "AUD",
    "effectiveFromAt": null,
    "effectiveToAt": "2022-07-11T04:40:42.500126870Z",
    "returnUrl": return_url,
    "notificationUrl": notification_url, 
    "businessCode": your_business_code,
    "billingAddress": {
        "line1": "Halloween Street",
        "line2": "House No.23",
        "city": "Melbourne",
        "state": "Victoria",
        "postcode": "3006",
        "country": "Australia"
    },
    "shippingAddress": {
        "line1": "Halloween Street",
        "line2": "House No.23",
        "city": "Melbourne",
        "state": "Victoria",
        "postcode": "3006",
        "country": "Australia"
    },
    "orderItems": [
        {
            "name": "bournvita health drink",
            "quantity": 1,
            "amount": 900,
            "currency": "AUD"
        }
    ],
    "shopperData": {
        "firstName": "Jane",
        "lastName": "Doe",
        "email": "[email protected]",
        "phoneNumber": "041234567"
    }
}

Field		Description / Notes
customerReference	Optional	Merchant specified customer reference for the order / payment.
acceptanceTypes	Mandatory	For online payments, always pass 'APP' and 'WEB'.
totalAmount	Mandatory	Total payment amount.
currency	Optional	If not specified, defaults to AUD.
effectiveFromAt	Optional	If specified, Waave will reject payment authorisation attempts by the shopper prior to the time specified.
effectiveToAt	Optional (Recommended)	If specified, Waave will reject payment authorisation attempts by the shopper after the time specified. It is strongly recommended to set this field to a time before cart expiry on the merchant's checkout. This prevents payment authorisation after the cart expires (which would necessitate a refund).
returnUrl	Required	Merchant's call back URL to which Waave should send the shopper after the shopper has authorised or cancelled payment, or there has been an error.
notificationUrl	Optional	Webhook URL to which Waave will post the status updates for this payment. Leave blank if web hooks are not required.
businessCode	Mandatory	Provided by the Waave team during onboarding.
billingAddress	Optional (Recommended)	Customer billing address.
shippingAddress	Optional	Customer shipping address.
orderItems	Mandatory	Array of line items in the cart.
shopperData	Optional	Shopper information such as their phone number, email address and name. All fields under shopperData are optional. If populated, Waave will use this information to pre-populate the sign up forms to remove the need for the customer to re-enter it.

Sample Response

{
    "paymentSessionId": "8d04eee8-de1a-4203-b4ff-31e21c1398e4",
    "customerReference": "orderRef-20220610123125",
    "bindingAgreementId": null,
    "acceptanceTypes": [
        "APP",
        "WEB"
    ],
    "totalAmount": 900,
    "templateId": null,
    "currency": "AUD",
    "effectiveFromAt": null,
    "effectiveToAt": "2022-07-11T04:40:42.500126870Z",
    "returnUrl": return_url,
    "notificationUrl": notification_url,
    "createdAt": "2022-06-10T02:31:25.017899854Z",
    "expiresAt": "2022-06-15T02:31:25.017901972Z",
    "status": "AWAITING_AUTHORISATION",
    "payUrl": "https://link.app.waave.com/pay/w/8d04eee8-de1a-4203-b4ff-31e21c1398e4?r=true",
    "businessCode": "bens_bakeshop",
    "bindingBuyerWalletId": null,
    "codeUrl": "https://link.app.waave.com/pay/w/8d04eee8-de1a-4203-b4ff-31e21c1398e4", 
    "billingAddress": {
        "id": 18014,
        "line1": "Halloween Street",
        "line2": "House No.23",
        "city": "Melbourne",
        "state": "Victoria",
        "postcode": "3006",
        "country": "Australia"
    },
    "shippingAddress": {
        "id": 18064,
        "line1": "Halloween Street",
        "line2": "House No.23",
        "city": "Melbourne",
        "state": "Victoria",
        "postcode": "3006",
        "country": "Australia"
    },
    "orderItems": [
        {
            "id": 18205,
            "name": "bournvita health drink",
            "sku": null,
            "quantity": 1,
            "amount": 900,
            "currency": "AUD"
        }
    ],
    "businessName": "Ben's Bakeshop",
    "businessLogoUrl": "https://cdn.app.waavetest.com/img/business-logos/bens_bakeshop.png",
    "resultCode": null,
    "resultUrl": null,
    "shopperData": {
        "id": 168752,
        "firstName": "Jane",
        "middleName": null,
        "lastName": "Doe",
        "email": "[email protected]",
        "phoneNumber": "041234567"
    }
}

The response contains a unique payUrl which is required in the next step.

3 - Send the shopper to Waave Web UI / App

Once the payment session has been created, you need to redirect the shopper to the Pay URL.

The shopper will interact with the Waave Web UI (or the Waave mobile app if it is installed on the shopper's device) to complete sign up and payment authorisation.

Once the payment is authorised or cancelled, the Waave Web UI / Mobile app will redirect the shopper to the returnUrl specified during the payment session creation, along with additional parameters.

resultCode - indicates the outcome of the payment. It can be APPROVED, DECLINED, ERROR or CANCELLED.
paymentSessionId - the payment session ID.
businessCode - the merchant's business code.

4 - Verify Payment Session Status

Once the shopper has landed on the merchant's returnUrl, the merchant must verify the payment status by calling the Get Payment Session Status API with the paymentSessionId.

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

INSTRUCTION_SENT - the shopper has authorised the payment in the Waave app and the payment has been submitted. This is the only status that indicates successful payment authorisation.
EXPIRED - The payment session has expired.
DECLINED - Waave have declined the payment.
CANCELLED - The payment session has been cancelled by the merchant or the shopper.
ERROR - There was an error while processing the payment session.

There are other statuses that this API can return (e.g. AWAITING_AUTHORISATION). However, these are interim statuses that should not be returned after Waave redirects the shopper to returnUrl. If it does, please contact the Waave team as it might indicate incorrect integration.

Sample Response

{
    "status": "INSTRUCTION_SENT", 
    "resultCode": null,
    "resultUrl": null
}

It is strongly recommended that your server-side logic calls the Get Payment Session Status API before fulfilling the order. Solely relying on status verification done in JavaScript running in the browser would make your application susceptible to malicious manipulation of data. Additionally, calling the API from the server-side will safely confirm the final state of the payment session regardless of whether the shopper closes the browser.

The merchant can also subscribe to payment notification webhooks. Refer to Webhooks - Payment Session Notifications for more details.

5 - Cancel a Payment Session

The merchant can explicitly cancel a payment session by calling the Cancel Payment Session API. If the shopper attempts to authorise a cancelled payment, they recieve an error.

This is recommended when the payment session should be voided (and potentially a new one created separately). Examples include:

Shopping cart expiry has been detected
Shopper has updated the cart content / total amount
Shopper has cancelled the checkout process
Shopper has clicked the browser back button or refresh button

Once a payment session is authorised it cannot be cancelled. You will need to initiate a refund instead. See Refunds for more details.

First, implement logic to pass your client id and secret to the Waave token API to obtain an access token with the scope 'payment-sessions:cancel'.

Sample Request

{
    "client_id":MERCHANT_CLIENT_ID,
    "client_secret":MERCHANT_CLIENT_SECRET,
    "scope":"payment-sessions:cancel"
}

Sample Response

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

Then call the the Cancel Payment Session API with the token provided. The API will return a 200 response indicating that the payment session has been invalidated. If the shopper attempts to authorise this payment session, they will receive an error.

If you receive the following error, the payment session has already been authorised by the customer and it cannot be cancelled. If this occurs, the merchant can initiate a refund, or alternatively fulfil the order if that is deemed to be the appropriate action.

{
    "entityName": "paymentSession",
    "errorKey": "cancel-not-allowed",
    "type": "https://www.waave.com/problem/problem-with-message",
    "title": "Cannot perform cancel on payment session already having status INSTRUCTION_SENT",
    "status": 400,
    "message": "error.cancel-not-allowed",
    "params": "paymentSession"
}

6 - Webhooks

See Webhooks - Payment Session Notifications for more detail.