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.
Updated about 1 month ago