Integrating with Subscriptions App

Use this guide when you want to integrate Azupay’s Subscriptions App to create a recurring PayTo agreement and collect payments from it over time.

The Subscriptions App is designed for recurring collection only. It uses:

• the Payment Agreement Request API to create the recurring agreement setup session
• the Payment Initiation API to collect payments once the agreement is active

Before you begin

Make sure you have:

• an Azupay API key with access to the Payment Agreement Request API
• access to the Payment Initiation API for collecting payments after agreement approval
• a server-side integration point for creating agreement requests
• a frontend flow that can redirect the customer to the returned sessionUrl
• a webhook endpoint to receive agreement and payment status updates

How the integration works

1. Create a recurring Payment Agreement Request through the Azupay API.
2. Receive a sessionUrl and paymentAgreementId in the response.
3. Redirect the customer to the hosted Subscriptions App experience.
4. The customer reviews and approves the recurring PayTo agreement in their banking environment.
5. Azupay notifies you when the agreement becomes active.
6. Use the Payment Initiation API to collect payments against the approved agreement.

sequenceDiagram
    participant MB as Merchant Backend
    participant API as Azupay API
    participant UX as Subscriptions App
    participant BANK as Customer Bank
    participant WH as Webhook Endpoint

    MB->>API: Create Payment Agreement Request
    API-->>MB: Return sessionUrl and paymentAgreementId
    MB->>UX: Redirect customer to sessionUrl
    UX->>BANK: Customer reviews and approves agreement
    BANK-->>API: Agreement approved
    API-->>WH: Send agreement status update
    WH-->>MB: Mark agreement active
    MB->>API: Create Payment Initiation
    API-->>WH: Send payment status update
    WH-->>MB: Update billing workflow

Recurring PayTo agreement

Best for:

• subscriptions
• memberships
• instalment plans
• repeat service payments

What to expect:

• the customer authorises an ongoing PayTo agreement
• future payments can be collected under that agreement
• the hosted UX supports agreement setup, review, and approval
• once active, the agreement can be used for repeat payment initiation

{
  "PaymentAgreementRequest": {
    "clientTransactionId": "b844123d-0f45-498d-bcd3-ff84cd267407",
    "agreementStartDate": "2026-04-14",
    "agreementEndDate": "2027-04-14",
    "agreementFrequency": "MONTHLY",
    "agreementMaximumAmount": "50.00"
  },
  "successRedirectURL": "https://merchant.example/success",
  "cancelRedirectURL": "https://merchant.example/cancel"
}

Customer setup options

Customers can set up their recurring PayTo agreement using either:

• PayID
• BSB and account number

📘

You can also provide suggestedPayerDetails when you already know the customer’s preferred payment details.

Step 1: Create a Payment Agreement Request

To start the recurring agreement setup flow, create a Payment Agreement Request using the Payment Agreement Request API.

For a recurring agreement, you will typically also include:

{
  "PaymentAgreementRequest": {
    "clientTransactionId": "b844123d-0f45-498d-bcd3-ff84cd267407",
    "agreementStartDate": "2026-04-14",
    "agreementEndDate": "2027-04-14",
    "agreementFrequency": "MONTHLY",
    "agreementMaximumAmount": "50.00"
  },
  "successRedirectURL": "https://merchant.example/success",
  "cancelRedirectURL": "https://merchant.example/cancel"
}

Step 2: Handle the API response

A successful response includes:

• paymentAgreementId
• sessionUrl

Store the paymentAgreementId in your system against the relevant customer or subscription record. You will need it later when creating payment initiations.

Store the paymentAgreementId in your system against the relevant customer or subscription record. You will need it later when creating payment initiations.

A typical response shape looks like this:

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

Step 3: Redirect the customer to the hosted experience

Use the returned sessionUrl to direct the customer into the hosted Subscriptions App experience.

The customer will:

• review the agreement details
• enter their PayID or bank account details if required
• approve the recurring PayTo agreement through their banking environment

Step 4: Wait for agreement activation

• Do not attempt to collect payments until the agreement is active.

Use webhook updates to:

• detect when the agreement has been approved
• mark the paymentAgreementId as active in your system
• trigger downstream subscription or billing workflows

Step 5: Create a Payment Initiation

Once the agreement is active, use the Payment Initiation API to collect funds.

At a minimum, you will need the paymentAgreementId

A simple payment initiation shape looks like this:

This lets your system collect payments from the approved PayTo agreement without repeating the customer setup flow.

{
  "PaymentInitiation": {
    "clientTransactionId": "c6d3a2e8-7e5b-4c8e-9f4c-123456789abc",
    "paymentAmount": "50.00",
    "paymentAgreementId": "ee55da07d8bcb3d3077f1def7b958e2b"
  }
}

What to store in your system

For each recurring agreement flow, store:

• clientTransactionId
• paymentAgreementId
• the customer or subscription record linked to the agreement
• the agreement status
• payment initiation results and webhook updates

This will make agreement lifecycle handling, billing, and reconciliation much simpler.

What the customer sees

The hosted Subscriptions App guides the customer through:

• reviewing the recurring agreement details
• entering PayID or bank account details
• approving the agreement through their banking environment
• completing setup for future payment collection
• Use the sessionUrl
• Once your Payment Agreement Request has been created, use the returned sessionUrl to direct the customer into the hosted Subscriptions App experience.

The hosted experience will:

• present the recurring agreement details to the customer
• guide them through the PayTo authorisation flow
• support recurring agreement setup
• return agreement and payment status updates through API responses and webhooks