Azupay website
Guides
Help CentreService DeskStatus PageDashboard | ProductionDashboard | UATTest Bank

PaymentAgreement APIs

Suggest Edits

Payment Agreements

A payment agreement is the contract between a merchant and their customer, that will allow the merchant to
automatically deduct funds using the customer's banking details i.e. PayID or BSB and account number in real time.

Once you have a Payment Agreement in place with a customer you will be able to automatically collect eligible payments using PaymentInitiation APIs.

There are four main types of payment agreements that can be setup. These are Variable, Fixed, Usage based and Balloon.
Each of which is related to a specific scenario that will be described below.

Types of Payment Agreements

  • Variable Payment Agreement is used to manage recurring payments that have a variable amount each time i.e. ad-hoc wallet top-ups, Uber trips.

  • Usage Based Payment Agreement is used to manage recurring payments that are based on your usage of a service i.e. electricity, water or gas bills.

  • Fixed Payment Agreement is used for fixed recurring payments i.e. Spotify, Netflix, council rates.

  • Balloon Payment Agreement is used to manage recurring payments where there is typically a large payments due at the end i.e. car loan.

📘

Each type of payment agreement will have a unique set of fields that are described in more detail under the agreementDetails object of the Create a Payment Agreement API.

Creating a Payment Agreement

In order to create a payment agreement, we will choose a variable agreement as an example and supply the value in the request body as follows:

POST https://api.azupay.com.au/v1/paymentAgreement
Authorization: SECR_MYBUSINESSID_myapikey
Content-Type: application/json

{
  "PaymentAgreement": {
    "clientId": "MYBUSINESSID",
    "clientTransactionId": "INV-0000001-1",
    "payerDetails": {
      "name": "Bob",
      "bankAccountDetails": {
        "bsb": "100000",
        "accountNumber": "00000000"
      }
    },
    "paymentAgreementType": "MORTGAGE",
    "description": "The description",
    "agreementDetails": {
       "variableAgreementDetails": {
         "startDate": "2022-03-04",
         "endDate": "2022-11-03",
         "frequency": "MONTHLY",
         "maximumAmount": "344.33"
       }
    },
    "paymentAgreementNotification": {
      "endpointURL": "https://mybusiness.free.beeceptor.com",
      "authorizationHeader": "my-secret-header"
    }
  }
}

This is a very simple request message. Now let's have a look at what you submitted:

  • clientId: the unique client identifier that we should have provided you during on-boarding.

  • clientTransactionId: a unique identifier for your business that does not repeat. If you send the same
    clientTransactionId in another request the system will not create a new one, but will return the status of the existing one. This serves as a duplicate check in case you HTTP client retries the same message.
    So it is a good practice to use a globally unique identifier (GUID) or append an extra counter to your invoice identifier in case you need to recreate the PaymentAgreement.

  • payerDetails: the details of the customer who will be making payments on the invoice. This includes their bank details or PayID (only choose one).

  • paymentAgreementType: payment type selected from a range of options specified in the NPP scheme rules. Create a Payment Agreement lists the current eligible values for this field. In the above example we used MORTGAGE

  • description: a more detailed description of the payment agreement

  • agreementDetails: this object contains the specifics of the intended agreement. It does contain some required fields e.g. frequency and startDate.

  • paymentAgreementNotification: this object contains the webhook endpoint you will use to get notified once a payment agreement has been activated.

Once you submit this request you will receive a response like the following.

HTTP/1.1 201 Created
Date: Wed, 06 Apr 2022 02:50:53 GMT
Content-Type: application/json

{
  "PaymentAgreement": {
    "payerDetails": {
      "name": "Bob",
      "bankAccountDetails": {
        "bsb": "100000",
        "accountNumber": "00000000"
      }
    },
    "paymentAgreementType": "MORTGAGE",
    "paymentAgreementNotification": {
      "endpointURL": "https://mybusiness.free.beeceptor.com",
      "authorizationHeader": "my-secret-header"
    },
    "clientId": "MYBUSINESSID",
    "description": "The description",
    "clientTransactionId": "INV-0000001-1",
    "agreementDetails": {
      "variableAgreementDetails": {
        "endDate": "2022-11-03",
        "startDate": "2022-03-04",
        "frequency": "MONTHLY",
        "maximumAmount": "344.33"
      }
    }
  },
  "PaymentAgreementStatus": {
    "paymentAgreementId": "86ea437729e81567218cd013aa5e3d36",
    "createdDatetime": "2022-04-06T02:50:52.876Z",
    "status": "CREATED"
  }
}

You can see there is a new entity called PaymentAgreementStatus. Below are fields to take note of:

paymentAgreementId: This is the id assigned to the new payment agreement.

status: The status of the payment agreement is set to CREATED. In order for your business to start receiving payments via payment initiation, this field must become ACTIVE and this can only be done by your customer approving the Payment Agreement in their own banking app.

Payment Agreement Status

Below is a diagram displaying the different statuses a payment agreement can have. It is important to note that your
customers must approve a payment agreement, before a transaction can be conducted.

In order to change the status of a payment agreement see the section below

Amending a Payment Agreement

Bilateral Amendment

To amend a payment agreement's details such as setting a new end date or even a different payment agreement type, follow the payload example supplied below:

POST https://api.azupay.com.au/v1/paymentAgreement/amendment
Authorization: SECR_MYBUSINESSID_myapikey
Content-Type: application/json

{
  "PaymentAgreementAmendment": {
    "paymentAgreementId": "6381994bcd774920b50ce5bda3629ef2",
    "clientTransactionId": "INV-0000001-1",
    "agreementDetails": {
      "balloonAgreementDetails": {
        "frequency": "ADHOC"
      }
    },
    "paymentAgreementAmendmentNotification": {
      "endpointURL": "https://mybusiness.free.beeceptor.com",
      "authorizationHeader": "my-secret-header"
    }
  }
}

Some key points to make note of in the above post request, for this amendment we have changed two pieces of information.

  1. We have changed the payment agreement type from variable to balloon denoted by the balloonAgreementDetails object
  2. The frequency has changed from MONTHLY to ADHOC

Details that were not included in the amendment will remain the same (where they are still valid fields in the new
agreement type).

In the example, changing to a balloon agreement didn't require us to add the startDate, as it was carried over from the original payment agreement.

📘

Bilateral Amendments

Payment agreement's agreementDetails amendment require authorisation from the payer. We refer to this type of amendment as bilateral amendment.

Unilateral Amendment

Unilateral fields are fields in the payment agreement that can be amended, without needing the payer to re-authorise
the agreement.

Supported unilateral fields are:

  • description
  • payeeName

To amend unilateral fields, supply the amendment in the commonDetails fields. An example shown below:

POST https://api.azupay.com.au/v1/paymentAgreement/amendment
Authorization: SECR_MYBUSINESSID_myapikey
Content-Type: application/json

{
  "PaymentAgreementAmendment": {
    "paymentAgreementId": "6381994bcd774920b50ce5bda3629ef2",
    "clientTransactionId": "INV-0000001-1",
    "commonDetails": {
      "payeeName": "Northwind Inc.",
      "description": "Mortgage Repayment"
    },
    "paymentAgreementAmendmentNotification": {
      "endpointURL": "https://mybusiness.free.beeceptor.com",
      "authorizationHeader": "my-secret-header"
    }
  }
}

📘

Authorisation on amendments

Payment agreement's commonDetails amendment do not require authorization from the payer. This is an opt-in feature. To enable this feature, please raise a support ticket (via this link or get in touch with your Azupay customer representative)

Search for a Payment Agreement

In order to search for payment agreements supply the request object below.

POST https://api.azupay.com.au/v1/paymentAgreement/search
Authorization: SECR_MYBUSINESSID_myapikey

Change Status of a Payment Agreement

In order to change the status of a payment agreement you must have the Payment Agreement ID and use one of the valid enums available.
This can be seen in the example request object supplied below.

POST https://api.azupay.com.au/v1/paymentAgreement/changeStatus?id=6381994bcd774920b50ce5bda3629ef2&status=CANCELLED
Authorization: SECR_MYBUSINESSID_myapikey

Migrating from Direct Debit Arrangements (DDR)

If you have existing Direct Debit Arrangements with your customers we can automatically migrate these agreements to PayTo Agreements for a better experience for you and your customers - without needing your customers to authorise the new PayTo Agreements. To enable this feature, please raise a support ticket (via this link or get in touch with your Azupay customer representative).

🚧

DDR Migration has certain consumer protections you need to be aware of

There are mandatory business processes you must follow for DDR Migrations to be valid and we can discuss these with you.

To enable this, please raise a support ticket (via this link or get in touch with your Azupay customer representative) expressing interest in DDR Migration before starting any implementation on this feature.

You will need to supply us with all Bulk Electronic Clearing System (BECS) identifier(s) associated to the DDRs to
be migrated, and we will assign this to your account's client configuration.

Once configured, the migration can be done simply by creating a payment agreement and specifying the payer's
bank account details (payerDetails.bankAccountDetails) and the payee's BECS (payeeDetails.becsUserId).

There is a 5 (calendar) day grace period after the migration, where transactions cannot be initiated. An attempt to
initiate payment before the end of the grace period will be rejected.

Example of the API call is shown below: 

POST https://api.azupay.com.au/v1/paymentAgreement
Authorization: SECR_MYBUSINESSID_myapikey
Content-Type: application/json

{
  "PaymentAgreement": {
    "clientId": "MYBUSINESSID",
    "clientTransactionId": "INV-0000001-1",
    "payerDetails": {
      "name": "Bob",
      "bankAccountDetails": {
        "bsb": "100000",
        "accountNumber": "00000000"
      }
    },
    "payeeDetails": {
      "becsUserId": "BECS99"
    },
    "agreementDetails": {
       "variableAgreementDetails": {
         "startDate": "2022-03-04",
         "endDate": "2022-11-03",
         "frequency": "MONTHLY",
         "maximumAmount": "344.33"
       }
    }
  }
}

Updated about 1 year ago