PaymentAgreementRequest API

Overview

The PaymentAgreementRequest API is used in conjunction with Azupay's Subscription UX checkout solution. The use case for calling the PaymentAgreementRequest API is to set up a PayTo agreement with your customer. This API used with the Subscriptions UX checkout does not collect payments directly — merchants must initiate separate API calls to actually collect payments after the agreement has been set up.

API References

How do I use Subscriptions UX solution via API?

In order to use Azupay's Subscription UX solution, you need to do the following:

• Obtain a one-time link URL and a tentative paymentAgreementId using the POST/PaymentAgreementRequest
  API. At this point the Payment Agreement has not been created yet. You must use an API Key ( API_KEY ) with
  permissions for POST/PaymentAgreementRequest.

Request

POST https://api.azupay.com.au/v1/paymentAgreementRequest
Authorization: {{API_KEY}}
Content-Type: application/json

{
  "PaymentAgreementRequest": {
    "clientTransactionId": "b844123d-0f45-498d-bcd3-ff84cd267407",
    "agreementMaximumAmount": "900.00"
  }
}

Response

HTTP/2 201 Created
content-type: application/json

{
  "PaymentAgreementRequest": {
    "clientTransactionId": "b844123d-0f45-498d-bcd3-ff84cd267407",
    "agreementMaximumAmount": "900.00"
  },
  "PaymentAgreementRequestStatus": {
    "paymentAgreementId": "ee55da07d8bcb3d3077f1def7b958e2b",
    "sessionUrl": "https://subscriptions.apps.azupay.com.au/78e7941b6c844f70b50292ce5d4325b8"
  }
}

• Save the paymentAgreementId against the authenticated user identifier for the payer so that you can use it to
  take payments later.
• Redirect your payer into this one-time link (sessionUrl) and provide both redirectURL and
  cancelRedirectURL as URL encoded query parameters so that your system can be notified of the outcome.
• When the agreement is Active, the payer will be directed to the redirectURL you provided. At this point you
  should mark it active in your system and you can use a [POST /PaymentInitiation](https://developer.azupay.com.au/reference/makepaymentinitiation) API call using the paymentAgreementId to obtain payments.
• If the payer fails to complete the process, they will be directed to the cancelRedirectURL and you can optionally start the process again.

Controlling how long the payer has to authorise

By default, the payment agreement created when calling the Payment Agreement Request API remains valid for 10 minutes. If the payer does not complete authorisation within that time, the payment agreement expires.

Use agreementExpiryMinutes to set a longer or shorter window, for example to give payers more time to login to their online banking or mobile banking to authorise the agreement.

• agreementExpiryMinutes is optional and is an integer number of minutes
• the minimum is 5 and the maximum is 7199
• when omitted, the expiry defaults to 10 minutes

Example request with a 60 minute expiry:

{
  "PaymentAgreementRequest": {
    "clientTransactionId": "b844123d-0f45-498d-bcd3-ff84cd267407",
    "agreementMaximumAmount": "900.00",
    "agreementExpiryMinutes": 60
  }
}