This guide describes how the merchant can create a standing agreement with customers to tokenise and charge their bank account without requiring a browser redirection to Waave Pay by Bank each time.

Overview

The process follows the standard payment flow described in Payments - Online with some additional steps. Please familiarise yourself with the standard flow first before reading on.

High-level steps

Creating a recurring agreement with the first payment

1. The merchant passes some additional parameters when making a payment. If the first payment is successful, we generate a recurring agreement and a token for it.
2. The merchant stores the recurring agreement ID and token against the shopper profile for future use. This information is necessary to subsequently charge the shopper under the agreement via a merchant-initiated transaction (MIT).

Charging the shopper using a recurring agreement

1. The shopper returns for a subsequent purchase. The merchant retrieves the vaulted recurring agreement and token for the shopper profile.
2. The merchant passes the recurring agreement ID and token to the Payment API to charge the shopper's bank account (MIT). There is no need to redirect the shopper to the Waave Pay by Bank site.
3. The merchant receives a webhook indicating the outcome (success/failure) of the payment.

Cancelling a recurring agreement

1. The shopper choses to cancel the standing agreement (recurring agreement).
2. The merchant calls the Waave API to cancel the recurring agreement, and deletes the recurring agreement id and token from the shopper profile.

Prerequisites

The Account on File feature is only available to approved merchants. Please contact Waave Team if you are interested in using this feature.

Once approved, you will have access to the following scopes for access tokens, which are required to use this feature.

recurring-agreements:create
recurring-agreements:read
recurring-agreements.status:read
recurring-agreements:cancel

1 - Create a first Payment

Simply add the additional element recurringAgreement in the request payload when calling the Create Payment API (Online) API. For more details, please read Payments - Online.

You need the recurring-agreements:create scope in the access token in addition to the standard payment-related scopes.

{
    "customerReference": "orderRef-20220610123125",  
    "totalAmount": 900,
    "currency": "AUD",
    "effectiveFromAt": null,
    "effectiveToAt": "2022-07-11T04:40:42.500126870Z",
    "returnUrl": "https://your_return_url",
    "notificationUrl": "https://your_payment_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"
        }
    ],
    "email": "[email protected]",
    "phoneNumber": "0412345678",
    "additionalData": {
        "firstName": "Jane",
        "lastName": "Doe"
    },
    "recurringAgreement": {
        "type": "ACCOUNT_ON_FILE",
        "customerReferennce":"8903498",
        "notificationUrl":"https://your_agreement_notification_url"
    }
}

Once the Payment object has been created, you need to redirect the shopper to the Pay URL.

The shopper will interact with the Waave Pay by Bank UI to authorise the first payment and agree to the creation of the recurring agreement.

2 - Receive Recurring Agreement Information

Upon successful payment, you can either use REST APIs and/or the Recurring Agreement Webhook to receive recurring agreement information.

Method 1: REST API

If the first payment is successful, you can retrieve the recurring agreement id and token by making REST API calls.

First, call Get Payment API just after the first payment. The response will contain recurringAgreementId if the payment is successful.

Sample Response from Get Payment API (Excerpt)

{
...
    "recurringAgreement": {
        "type": "ACCOUNT_ON_FILE",
        "notificationUrl":"https://your_agreement_notification_url",
        "recurringAgreementId":"11e51dfb-a268-4609-bfe2-bb78ee0f8bff"
    }
}

Then call Get Agreement API for the recurringAgreementId. The API response will contain the token for the recurring agreement along with the bank name, logo and masked account number.

Sample Response from Get Agreement API

{
    "recurringAgreementId": "52fc517f-ed42-4e1b-a805-6416ef2bf050",
    "customerReference": "8903498",
    "createdAt": "2024-02-01T02:54:04.748342Z",
    "status": "AUTHORISED",
    "type": "ACCOUNT_ON_FILE",
    "currency": "AUD",
    "businessCode": "bens_bakeshop",
    "businessName": null,
    "originalPaymentSessionId": "a2c61632-4e81-47ce-8e39-dd62b6d274c5",
    "bankName": "CommBank",
    "bankLogo": "https://waave.com/bank_logo/cba.png",
    "maskedAccountNumber": "****1234",
    "token": "YRcJKOgncng98iOU"
}

Bank name, logo and masked account number can be shown on your payment page so the shopper knows which bank account is tokenised.

🚧

For security reasons, the API only returns token in the first 24 hours after the recurring agreement is created. You need to call the API and store the token in your database as soon as the recurring agreement is created.

Method 2: Recurring Agreement Webhook

If you specify recurringAgreement.notificationUrl in the request message when creating a payment, you will receive a webhook for the recurring agreement in addition to the standard payment webhook.

{
    "businessCode": "waave_test_business",
    "customerReference": "ref-20240207140904",
    "entityType": "RECURRING_AGREEMENT",
    "identifier": "fd7fb297-3571-4963-a1bd-0c9b4df3ec37",
    "signature": null,
    "status": "AUTHORISED",
    "additionalData":
    {
        "original_payment_session_id": "53e7db26-1afe-4427-b5cc-5667334230d8",
        "token": "dqbzGwU4YTxPwzvn",
        "bankName":"CommBank",
        "bankLogo":"https://waave.com/bank_logo/cba.png",
        "maskedAccountNumber":"****1234"
    }
}

• entityType 'RECURRING_AGREEMENT' indicates the webhook is for recurring agreements
• status of AUTHORISED indicates that the recurring agreement was authorised by the customer
• The following information must be stored with the shopper record by the merchant:
  • identifier - UUID for the recurring agreement
  • token - required by the charge API
• Optionally, bank name, logo and masked account number can be stored and shown on your payment page so the shopper knows which bank account is tokenised.

Note that you will only receive the recurring agreement webhook if the payment is successful.

3 - Charge Shopper's Account

Once the agreement is created and stored, the merchant can charge the shopper using the agreement.

Call the Create Payment API (Online) API with the recurring agreement UUID and the token under the recurringCharge object in the payload.

Request

{
    "customerReference": "orderRef-20220610123125",
    "totalAmount": 300,
    "currency": "AUD",
    "businessCode": "your_business_code",
    "orderItems": [
        {
            "name": "bournvita health drink",
            "quantity": 1,
            "amount": 300,
            "currency": "AUD"
        }
    ],
    "notificationUrl": "https://your_payment_notification_url",
    "recurringCharge": {
        "agreementId": "fd7fb297-3571-4963-a1bd-0c9b4df3ec37",
        "token":"dqbzGwU4YTxPwzvn"
    }
}

Response

{
    "paymentSessionId": "e00386b5-3347-42bd-88b1-ac5302f9e21f",
    "customerReference": "orderRef-20220610123125",
    "totalAmount": 300,
    "currency": "AUD",
    "businessCode": "your_business_code",
    "createdAt": "2024-02-20T07:43:27.946994Z",
    "expiresAt": "2024-02-25T07:43:27.946994Z",
    "status": "ACCEPTED",
    "orderItems": [
        {
            "name": "bournvita health drink",
            "quantity": 1,
            "amount": 300,
            "currency": "AUD"
        }
    ],
    "notificationUrl": "https://your_payment_notification_url"
}

The status of ACCEPTED means the request has been accepted and does not mean the payment has been authorised.

4 - Verify Payment Status

After the Create Payment API (Online) API is called, the merchant must verify the final payment status by listening for the webhook and/or polling the Get Payment Status API with the paymentSessionId.

For payments created under a recurring agreement, the following final statuses apply.

• INSTRUCTION_SENT - The payment has been authorised, and the merchant can fulfil the order. This is the only status that indicates successful payment authorisation.
• DECLINED - Waave have declined the payment.
• ERROR - There was an error while processing the payment session.

Webhook Sample Payload

{
    "businessCode": "waave_test_business",
    "customerReference": "Health drink",
    "entityType": "PAYMENT_SESSION",
    "identifier": "68cd19c0-510c-4da0-837b-1285dbb986a4",
    "signature": null,
    "status": "INSTRUCTION_SENT",
    "additionalData":
    {
        "binding_agreement_id": "fd7fb297-3571-4963-a1bd-0c9b4df3ec37"
    }
}

5 - Cancel Recurring Agreement

It is recommended to provide a functionality within your site to allow shoppers to cancel their recurring agreements / tokenised payments.

When the shopper opts to cancel the agreement, you should call Cancel Agreement API, in addition to deleting the tokenised payment from the shopper's profile in your system. This will ensure that the recurring agreement cannot be used for future payments.