PaymentAgreement API

Overview

The Payment Agreement API lets you create and manage PayTo agreements directly from your integration. A Payment Agreement records the terms your customer authorises, including how often you may collect payments and any applicable amount limits.

Creating an agreement does not collect funds. After the customer authorises the agreement and its status becomes ACTIVE, use the PaymentInitiation API to collect each eligible payment.

How the direct integration works

sequenceDiagram
    participant Merchant as Your system
    participant Azupay
    participant Customer
    participant Bank as Customer's bank

    Merchant->>Azupay: Create Payment Agreement
    Azupay-->>Merchant: Agreement created with CREATED status
    Azupay->>Bank: Register agreement
    Bank->>Customer: Present agreement for authorisation
    Customer->>Bank: Authorise or reject agreement
    Azupay-->>Merchant: Agreement status update
    Merchant->>Azupay: Initiate payment after status is ACTIVE
    Azupay-->>Merchant: Payment Initiation status update

The direct flow has two separate stages:

1. Create and activate the Payment Agreement.
2. Create a Payment Initiation for each payment you want to collect under the authorised terms.

The agreement defines what may be collected. It does not schedule or collect payments by itself.

Before you begin

You need:

• an Azupay client ID for the environment you are using
• a secret API key with permission to call the Payment Agreement APIs
• the customer's PayID or BSB and account number
• a public HTTPS endpoint that UAT can reach if you want to receive agreement or payment status notifications
• a unique clientTransactionId for the agreement

Environment URLs

Your client ID and API key may differ between UAT and production. Keep secret API keys on your server and do not expose them in browser or mobile application code.

If you plan to receive status webhooks, review Webhooks – Implementation and Security for endpoint and security requirements.

Send your secret API key in the Authorization header:

Authorization: SECR_MYBUSINESSID_myapikey

API reference

Choose the agreement structure

Use the agreement structure that matches how you intend to charge the customer.

Only include one of the following objects in agreementDetails:

Supported paymentAgreementType values are:

Choose the value that describes the underlying purpose of the agreement. If none is an obvious fit, confirm the appropriate value with your Azupay representative rather than selecting one based only on the payment frequency.

Set the agreement limits

The values in agreementDetails define when and how you may collect payments under the agreement. Choose them to match the collection pattern the customer is authorising.

Agreement periods are measured from startDate; they are not necessarily calendar weeks or months. For example, a monthly agreement starting on 15 January begins a new period on the 15th of each month. If countPerPeriod is "2", no more than two Payment Initiations that have not failed can be created in each of those periods.

ADHOC agreements do not use recurring periods and are not subject to the countPerPeriod check. Other agreement conditions, including its status, dates and applicable amount limits, still apply.

These settings authorise and limit collections; they do not create payments automatically. Create each payment through the Payment Initiation API or use the Payment Schedule API after the agreement becomes ACTIVE.

Create a fixed monthly Payment Agreement

The following example creates a fixed monthly agreement using a synthetic PayID that produces an ACTIVE agreement in UAT. The test PayID must not be used in production.

The example uses placeholder dates in YYYY-MM-DD format. Replace them with a valid start date and end date before sending the request. Dates are evaluated using the Australia/Sydney calendar date by the Payment Agreement API.

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

{
  "PaymentAgreement": {
    "clientId": "MYBUSINESSID",
    "clientTransactionId": "a-unique-client-transaction-id",
    "contractId": "a-unique-contract-id",
    "payerDetails": {
      "name": "Bob",
      "payIDDetails": {
        "payID": "+61-453123123",
        "payIDType": "PHONE"
      }
    },
    "paymentAgreementType": "OTHER SERVICE",
    "description": "Monthly subscription",
    "agreementDetails": {
      "fixedAgreementDetails": {
        "startDate": "2027-01-01",
        "endDate": "2027-12-31",
        "frequency": "MONTHLY",
        "amount": "344.33",
        "countPerPeriod": "1"
      }
    },
    "paymentAgreementNotification": {
      "endpointURL": "https://merchant.example.com/webhooks/azupay/agreements",
      "authorizationHeader": "replace-with-a-unique-secret"
    }
  }
}

Replace the API key, client ID, transaction ID, contract ID, example dates, purpose code, description, amount, endpoint and webhook authorization value before sending the request. The start date must be today or a future date, and the end date must be on or after the start date. In production, also replace the synthetic UAT PayID with the customer's details.

To use BSB and account-number details instead, replace payerDetails with:

{
  "payerDetails": {
    "name": "Bob",
    "bankAccountDetails": {
      "bsb": "CUSTOMER_BSB",
      "accountNumber": "CUSTOMER_ACCOUNT_NUMBER"
    }
  }
}

Do not include payIDDetails and bankAccountDetails in the same request.

Important request fields

Idempotency and duplicate prevention

clientTransactionId identifies one logical create request. If your HTTP client does not receive a response and retries the same request, reuse the same value. Azupay returns the existing agreement rather than creating another one.

Use a new clientTransactionId when you intentionally create a new agreement.

contractId provides an additional duplicate check. When supplied, Azupay will not create another agreement for the same payer and contract while the existing agreement is CREATED, ACTIVE or SUSPENDED.

Create response

A successful request returns HTTP 201 with the agreement and its initial status:

{
  "PaymentAgreement": {
    "payerDetails": {
      "name": "Bob",
      "payIDDetails": {
        "payID": "+61-453123123",
        "payIDType": "PHONE"
      }
    },
    "paymentAgreementType": "OTHER SERVICE",
    "paymentAgreementNotification": {
      "endpointURL": "https://merchant.example.com/webhooks/azupay/agreements",
      "authorizationHeader": "****"
    },
    "clientId": "MYBUSINESSID",
    "description": "Monthly subscription",
    "clientTransactionId": "a-unique-client-transaction-id",
    "contractId": "a-unique-contract-id",
    "agreementDetails": {
      "fixedAgreementDetails": {
        "startDate": "2027-01-01",
        "endDate": "2027-12-31",
        "frequency": "MONTHLY",
        "amount": "344.33",
        "countPerPeriod": "1"
      }
    }
  },
  "PaymentAgreementStatus": {
    "paymentAgreementId": "86ea437729e81567218cd013aa5e3d36",
    "createdDatetime": "2026-10-07T02:50:52.876Z",
    "status": "CREATED"
  }
}

Store PaymentAgreementStatus.paymentAgreementId. You need it to search for the agreement, change its status and create Payment Initiations.

CREATED means the request was accepted and registration or customer authorisation is still in progress. Do not initiate a payment until the agreement becomes ACTIVE.

Test the direct flow in UAT

UAT recognises synthetic payer details that produce predictable agreement outcomes. The phone PayID +61-453123123 used in the example above produces an ACTIVE agreement without requiring access to a real banking app.

Use the Payment Agreement test accounts to exercise other outcomes, including agreements that remain CREATED or become CANCELLED, SUSPENDED or FAILED. These values are for UAT only.

The documented BSB test cases cover failure, CREATED, CANCELLED and SUSPENDED outcomes, but do not include an ACTIVE outcome. Use the synthetic phone PayID for the UAT happy path unless Azupay has provided other test-bank details for your integration.

After the agreement becomes ACTIVE, continue with the PaymentInitiation API guide to test collecting a payment.

Wait for customer authorisation

In production, after the agreement is created, the customer must approve it through their bank's mobile app or online banking. The exact labels vary by bank, but the customer generally:

1. Opens the PayTo or Payment Agreements area in their bank.
2. Selects the pending agreement.
3. Reviews the merchant, description, frequency, amount or limit, and agreement dates.
4. Approves or rejects the agreement.

Agreement creation and authorisation are asynchronous. Keep the customer informed that payment cannot be collected until their bank has confirmed the agreement. In UAT, the synthetic happy-path PayID completes this transition automatically.

Monitor the agreement until it reaches one of these outcomes:

• ACTIVE: the customer authorised the agreement and eligible payments may be initiated.
• CANCELLED: the agreement was cancelled and cannot be used.
• FAILED: registration could not be completed.

Do not assume that an HTTP 201 response means the agreement is ready for payment.

Payment Agreement lifecycle

flowchart TB
    CREATED[CREATED] -->|Customer approves agreement| ACTIVE[ACTIVE]
    CREATED -->|Cancelled before activation| CANCELLED[CANCELLED]
    CREATED -->|Registration fails| FAILED[FAILED]

    ACTIVE -->|Merchant or payer suspends| SUSPENDED[SUSPENDED]
    SUSPENDED -->|Reactivated| ACTIVE

    ACTIVE -->|Cancelled| CANCELLED
    SUSPENDED -->|Cancelled| CANCELLED

SUSPENDED is the API status for a temporarily paused agreement.

Monitor agreement status

You can receive status webhooks, search for the agreement, or use both approaches.

Receive status webhooks

For a transaction-level callback, include paymentAgreementNotification when creating the agreement. This configures the endpoint and authorization header for that Payment Agreement.

Azupay can also configure a reusable client-level webhook destination. Client-level destination URLs and authorization credentials are managed in your client configuration and cannot be added or changed through the dashboard. Contact Azupay Support if you need this option.

Azupay sends an HTTP POST request when an enabled Payment Agreement status event occurs.

The transaction-level configuration uses this request object:

{
  "paymentAgreementNotification": {
    "endpointURL": "https://merchant.example.com/webhooks/azupay/agreements",
    "authorizationHeader": "replace-with-a-unique-secret"
  }
}

Unless Thin Payload is enabled for your client, the webhook uses the same overall shape as the create response:

{
  "PaymentAgreement": {
    "clientId": "MYBUSINESSID",
    "clientTransactionId": "a-unique-client-transaction-id",
    "contractId": "a-unique-contract-id",
    "description": "Monthly subscription",
    "paymentAgreementType": "OTHER SERVICE",
    "payerDetails": {
      "name": "Bob",
      "payIDDetails": {
        "payID": "+61-453123123",
        "payIDType": "PHONE"
      }
    },
    "agreementDetails": {
      "fixedAgreementDetails": {
        "startDate": "2027-01-01",
        "endDate": "2027-12-31",
        "frequency": "MONTHLY",
        "amount": "344.33",
        "countPerPeriod": "1"
      }
    }
  },
  "PaymentAgreementStatus": {
    "paymentAgreementId": "86ea437729e81567218cd013aa5e3d36",
    "status": "ACTIVE",
    "previousStatus": "CREATED",
    "lastStatusBy": "PAYER",
    "createdDatetime": "2026-10-07T02:50:52.876Z",
    "registrationDatetime": "2026-10-07T02:52:10.000Z"
  }
}

Your webhook endpoint must:

1. Validate the HTTP Authorization header. For a transaction-level callback, compare it with the value supplied in paymentAgreementNotification. For a client-level destination, compare it with the authorization credentials configured by Azupay.
2. Correlate the notification using PaymentAgreementStatus.paymentAgreementId. A full payload also includes PaymentAgreement.clientTransactionId.
3. Process the notification idempotently because the same payload may be delivered more than once. Do not move a stored agreement back to an older status if events arrive out of order. Search for the agreement when you need to confirm its current status.
4. Return HTTP 200 after the notification has been handled, including when it is a duplicate.

Treat Payment Agreement webhook payloads as sensitive data and avoid unnecessary logging or retention of payer account details.

Search for status

If you do not configure an agreement webhook, or you need to reconcile after a missed notification, search using paymentAgreementId:

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

{
  "PaymentAgreementSearch": {
    "paymentAgreementId": "86ea437729e81567218cd013aa5e3d36"
  }
}

The search response returns matching records. Read PaymentAgreementStatus.status to determine whether the agreement can be used.

Status information

An agreement response or status webhook may contain:

Collect payments after activation

An ACTIVE Payment Agreement authorises you to collect eligible payments within its agreed terms. It does not automatically schedule or collect those payments.

Create a separate Payment Initiation each time you want to collect funds. Payment Initiations are asynchronous, and their status is monitored separately from the Payment Agreement.

See the PaymentInitiation API guide for the request format, status lifecycle, notifications, error handling, retries and refunds.

Understand Payment Agreement errors

Errors can occur when the request is submitted or later while the agreement is being registered.

Request rejected

Request-level errors are returned immediately, usually with HTTP 400. They do not create a new usable agreement or amendment.

{
  "message": "PayID format is incorrect",
  "details": {
    "failureCode": "AZP5.2",
    "failureReason": "PayID format is incorrect"
  }
}

Use details.failureCode for consistent error handling and details.failureReason to understand what must be corrected.

General API codes such as ERR0.03 or ERR0.04 may also be returned for request validation or missing resources. Use the accompanying failureReason for the specific cause.

If the API rejected the request before creating an agreement, correct the issue and resend the logical request. If an agreement record was created and you intentionally need a new attempt, use a new clientTransactionId.

Agreement registration failed

Creation is asynchronous. The API may return an agreement with CREATED while registration continues. If registration cannot be completed, the agreement moves to FAILED.

When available, failure details appear in:

• PaymentAgreementStatus.failureCode
• PaymentAgreementStatus.failureReason

failureCode and failureReason are optional. An agreement may have a FAILED status without these fields.

Agreement cancelled or suspended

When an agreement is cancelled or suspended, use reasonCode with reasonDescription to understand why.

Amend a Payment Agreement

Use the amendment API to change an existing agreement. The effect on customer authorisation depends on the fields being changed.

Bilateral amendments

Changes to agreementDetails require the customer to authorise the amendment.

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

{
  "PaymentAgreementAmendment": {
    "paymentAgreementId": "6381994bcd774920b50ce5bda3629ef2",
    "clientTransactionId": "INV-0000001-AMENDMENT-1",
    "agreementDetails": {
      "variableAgreementDetails": {
        "frequency": "WEEKLY",
        "maximumAmount": "500.00",
        "countPerPeriod": "1"
      }
    },
    "paymentAgreementAmendmentNotification": {
      "endpointURL": "https://merchant.example.com/webhooks/azupay/agreement-amendments",
      "authorizationHeader": "replace-with-a-unique-secret"
    }
  }
}

In this example, the agreement changes from a fixed structure to a variable structure. Fields not included in the amendment remain unchanged where they are valid for the new structure.

Unilateral amendments

The following fields can be amended without asking the customer to authorise the agreement again:

• description
• payeeName

Supply unilateral changes under commonDetails:

{
  "PaymentAgreementAmendment": {
    "paymentAgreementId": "6381994bcd774920b50ce5bda3629ef2",
    "clientTransactionId": "INV-0000001-AMENDMENT-2",
    "commonDetails": {
      "payeeName": "Northwind Inc.",
      "description": "Monthly subscription"
    },
    "paymentAgreementAmendmentNotification": {
      "endpointURL": "https://merchant.example.com/webhooks/azupay/agreement-amendments",
      "authorizationHeader": "replace-with-a-unique-secret"
    }
  }
}

Search for Payment Agreements

POST /paymentAgreement/search supports searches by:

• paymentAgreementId
• contractId
• creation-date range

Do not combine an ID search with date fields in the same request.

The following request searches for agreements created within a UTC date range:

{
  "PaymentAgreementSearch": {
    "fromDate": "2026-10-01T00:00:00.000Z",
    "toDate": "2026-10-31T23:59:59.999Z"
  }
}

The date filters apply to the agreement's creation time, not its start date, end date or most recent status change.

Change the status of a Payment Agreement

Use the status API to suspend, reactivate or cancel an agreement:

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

The merchant-permitted transitions are:

Confirm the status change

Valid status changes for an agreement currently in ACTIVE or SUSPENDED status are processed asynchronously:

• ACTIVE → SUSPENDED or CANCELLED
• SUSPENDED → ACTIVE or CANCELLED

An HTTP 201 response confirms that the change was submitted, not completed. Continue monitoring the agreement through status notifications, or use the Search Payment Agreements API, until it reaches the requested status.

For an agreement in CREATED status, only cancellation is supported. This change is processed synchronously, and an HTTP 200 response confirms that the agreement is CANCELLED.

The status API cannot be used to perform the initial CREATED to ACTIVE transition. Initial activation requires customer authorisation.

Use Azupay's hosted customer experience

The direct API requires your system to collect the customer's PayID or BSB and account number. If you prefer Azupay to capture those details, use the PaymentAgreementRequest API with Azupay's hosted Subscriptions experience.

This option can:

• reduce the sensitive bank-account information handled by your interface
• reduce the development effort required to build the account-capture experience
• reduce the compliance effort associated with handling those details

The hosted experience creates the agreement; it does not collect a payment. After activation, use the Payment Initiation API in the same way as a directly created agreement.

Migrate Direct Debit Arrangements

Existing Direct Debit Arrangements may be eligible for migration to PayTo without requiring customers to authorise new agreements individually.

After Azupay configures your Bulk Electronic Clearing System (BECS) user ID, create the agreement with:

• the payer's BSB and account number in payerDetails.bankAccountDetails
• your configured BECS user ID in payeeDetails.becsUserId

There is a five-calendar-day grace period after migration. Payment Initiations submitted before the grace period ends are rejected. Replace the date labels in the following example with valid current or future dates before sending it.

{
  "PaymentAgreement": {
    "clientId": "MYBUSINESSID",
    "clientTransactionId": "INV-0000001-DDR-MIGRATION",
    "payerDetails": {
      "name": "Bob",
      "bankAccountDetails": {
        "bsb": "100000",
        "accountNumber": "00000000"
      }
    },
    "payeeDetails": {
      "becsUserId": "BECS99"
    },
    "paymentAgreementType": "OTHER SERVICE",
    "description": "Migrated direct debit arrangement",
    "agreementDetails": {
      "variableAgreementDetails": {
        "startDate": "REPLACE_WITH_VALID_START_DATE",
        "endDate": "REPLACE_WITH_VALID_END_DATE",
        "frequency": "MONTHLY",
        "maximumAmount": "344.33"
      }
    }
  }
}

Next steps

• Review the Create a Payment Agreement API reference for complete schemas and allowed values.
• Use the PaymentInitiation API guide to collect payments after activation.
• Use the PaymentAgreementRequest API when you want Azupay to host the customer account-capture experience.
• Review the Webhooks guide before implementing production notification handling.