Collect a payment with the Payment Initiation API

Use the Payment Initiation API to collect an eligible PayTo payment under an active Payment Agreement.

A Payment Initiation is one collection attempt. For a recurring arrangement, your system is responsible for scheduling and creating a new Payment Initiation for each payment that becomes due. Azupay does not automatically create later Payment Initiations from the agreement. Every collection must remain within the amount, frequency and other conditions authorised by the customer in the Payment Agreement.

Let Azupay schedule payments

If you do not want to create each Payment Initiation from your own system, you can use the Payment Schedule API to have Azupay initiate future payments against an ACTIVE Payment Agreement. The schedule and each payment must remain within the terms authorised by the customer.

Learn more about the Payment Schedule API.

API reference

Before you begin

You need:

• an Azupay client ID for the environment you are using
• an API key for the same environment
• an ACTIVE Payment Agreement; if you do not have one, see Create a Payment Agreement
• an amount that complies with the Payment Agreement
• a unique clientTransactionId for this collection attempt
• an HTTPS endpoint if you want to receive status webhooks

Use the client ID and API key issued for the environment you are calling. UAT and production credentials are different.

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

How it works

flowchart TB
    A[Active Payment Agreement] --> B[Create Payment Initiation]
    B --> C[CREATED]
    C -->|Processing continues| D[PENDING]
    C -->|Immediate settlement| E[SETTLED]
    C -->|Immediate rejection| F[FAILED]
    D -->|Settlement confirmed| E
    D -->|Rejected or processing times out| F
    E -->|Later refund or return| G[RETURN_IN_PROGRESS]
    F -.->|Rare: late settlement received| G
    G -->|Return succeeds| H[RETURN_COMPLETE]
    G -->|Return fails| I[RETURN_FAILED]
    H -->|Refund remaining balance| G
    I -->|Retry an eligible refund| G

The create request is asynchronous. A successful HTTP response means Azupay accepted the Payment Initiation; it does not necessarily mean the payment has settled.

Most Payment Initiations follow one of two paths:

• Immediate outcome: the status changes directly to SETTLED or FAILED.
• Processing continues: the status changes to PENDING. Azupay monitors the payment until it settles, is rejected or reaches the end of the processing window. If no final outcome is available when that window ends, the status changes to FAILED.

In rare cases, settlement confirmation can arrive after a Payment Initiation has changed to FAILED. Azupay automatically returns those late-arriving funds, as described in Late-arriving funds after FAILED.

Use PaymentInitiationStatus.status to determine the outcome:

• CREATED and PENDING are non-final states.
• SETTLED is the successful outcome for the original collection.
• FAILED is the unsuccessful outcome for the original collection.
• RETURN_IN_PROGRESS, RETURN_COMPLETE and RETURN_FAILED describe a later refund or return.

You can receive status changes by webhook, retrieve the latest status with the Get Payment Initiation API, or use both approaches.

Step 1: Create a Payment Initiation

Send a POST request to /v1/paymentInitiation.

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

{
  "PaymentInitiation": {
    "clientId": "MYBUSINESSID",
    "clientTransactionId": "INV-0000001-1",
    "paymentAmount": "99.99",
    "paymentAgreementId": "86ea437729e81567218cd013aa5e3d36",
    "reference": "INVOICE-0000001",
    "description": "Monthly subscription payment",
    "paymentInitiationNotification": {
      "endpointURL": "https://merchant.example.com/webhooks/azupay",
      "authorizationHeader": "merchant-generated-secret"
    }
  }
}

Request fields

How agreement frequency limits Payment Initiations

You do not provide frequency or countPerPeriod when creating a Payment Initiation. Azupay reads these values from the associated Payment Agreement and checks each new collection against its authorised terms.

For frequency-based agreements:

• countPerPeriod is the maximum number of Payment Initiations allowed during each agreement period.
• Each period is measured from the agreement's startDate. For example, a monthly agreement follows monthly periods anchored to its start date rather than calendar months.
• If countPerPeriod was not specified, the limit defaults to one Payment Initiation per period.
• Payment Initiations count towards the limit unless their current status is FAILED. A failed attempt therefore does not consume the allowance when Azupay validates a later request.
• ADHOC agreements are not subject to this per-period count check, although all other agreement conditions still apply.

If the limit has already been reached, Azupay rejects the request with HTTP 400 and failure code AZP5.18. A new Payment Initiation is not created. Review the agreement terms or wait until the next authorised period before creating another collection.

Additional details

If you include additionalDetails, provide customerNumber, userID, authMethod and channelType. The remaining fields are conditional or optional as shown below.

Step 2: Store the creation response

A successful request returns HTTP 201. Store PaymentInitiationStatus.paymentInitiationId; you need it to retrieve the latest status and reconcile webhook notifications.

The following example is abridged to highlight the fields used by the integration:

{
  "PaymentInitiation": {
    "clientId": "MYBUSINESSID",
    "clientTransactionId": "INV-0000001-1",
    "paymentAmount": "99.99",
    "paymentAgreementId": "86ea437729e81567218cd013aa5e3d36",
    "reference": "INVOICE-0000001",
    "description": "Monthly subscription payment",
    "paymentInitiationNotification": {
      "endpointURL": "https://merchant.example.com/webhooks/azupay",
      "authorizationHeader": "****"
    }
  },
  "PaymentInitiationStatus": {
    "paymentInitiationId": "a050551479f625c066b559da28fee33c",
    "nppTransactionId": "AZTPAU22XXXN20230419100000000000020",
    "status": "CREATED",
    "createdDatetime": "2026-10-07T00:00:00.000Z"
  },
  "PaymentAgreement": {
    "clientId": "MYBUSINESSID"
  }
}

The response also includes the Payment Agreement associated with the collection. The authorizationHeader value is never returned in plain text.

Step 3: Monitor the payment

Option A: Receive status webhooks

For a transaction-level callback, include paymentInitiationNotification in the create request. This configures the endpoint and authorization header for that Payment Initiation.

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 Initiation status event occurs.

POST https://merchant.example.com/webhooks/azupay
Authorization: merchant-generated-secret
Content-Type: application/json

Unless Thin Payload is enabled for your client, the webhook contains the Payment Initiation and its latest status. The following example is abridged:

{
  "PaymentInitiation": {
    "clientId": "MYBUSINESSID",
    "clientTransactionId": "INV-0000001-1",
    "paymentAmount": "99.99",
    "paymentAgreementId": "86ea437729e81567218cd013aa5e3d36",
    "paymentInitiationNotification": {
      "endpointURL": "https://merchant.example.com/webhooks/azupay",
      "authorizationHeader": "****"
    }
  },
  "PaymentInitiationStatus": {
    "paymentInitiationId": "a050551479f625c066b559da28fee33c",
    "status": "SETTLED",
    "statusCode": "ACSC",
    "statusReason": "Accepted & Settled",
    "completedDatetime": "2026-10-07T00:01:30.000Z",
    "nppTransactionId": "AZTPAU22XXXN20230419100000000000020"
  }
}

Your webhook endpoint must:

1. Validate the HTTP Authorization header. For a transaction-level callback, compare it with the value supplied in paymentInitiationNotification. For a client-level destination, compare it with the authorization credentials configured by Azupay.
2. Correlate the notification using PaymentInitiationStatus.paymentInitiationId. A full payload also includes PaymentInitiation.clientTransactionId.
3. Process the notification idempotently because the same payload may be delivered more than once. For the original collection lifecycle, use paymentInitiationId and status together to recognise a repeated notification. For refunds, reconcile each attempt using refundInformation.requests[].nppTransactionId and refundInformation.requests[].status. Retrieve the Payment Initiation first if you receive a thin payload.
4. Return HTTP 200 after the notification has been handled, including when it is a duplicate.

Option B: Retrieve the latest status

Use the ID returned by the create request:

GET https://api-uat.azupay.com.au/v1/paymentInitiation?id=a050551479f625c066b559da28fee33c
Authorization: SECR_MYBUSINESSID_myapikey

The response contains PaymentInitiation, PaymentInitiationStatus and the associated PaymentAgreement. The following example is abridged:

{
  "PaymentInitiation": {
    "clientId": "MYBUSINESSID",
    "clientTransactionId": "INV-0000001-1",
    "paymentAmount": "99.99",
    "paymentAgreementId": "86ea437729e81567218cd013aa5e3d36"
  },
  "PaymentInitiationStatus": {
    "paymentInitiationId": "a050551479f625c066b559da28fee33c",
    "status": "PENDING",
    "statusCode": "SENT",
    "statusReason": "Sent",
    "createdDatetime": "2026-10-07T00:00:00.000Z",
    "nppTransactionId": "AZTPAU22XXXN20230419100000000000020"
  },
  "PaymentAgreement": {
    "clientId": "MYBUSINESSID"
  }
}

Stop polling for the outcome of the original collection when status becomes SETTLED or FAILED.

If you need to track a later refund or the automatic return of late-arriving funds, keep the relevant RETURN_* webhook events enabled. When a return moves to RETURN_IN_PROGRESS, use webhook updates or retrieve the latest status until it reaches RETURN_COMPLETE or RETURN_FAILED.

The API does not prescribe a fixed polling interval. Use webhooks as the primary status channel where possible, and define a bounded reconciliation schedule that matches your operational needs. Avoid continuous or high-frequency requests, stop polling as soon as a final status is returned, and contact Azupay Support before implementing high-frequency polling.

Statuses

In this table, Yes means that the current collection or return attempt has reached an outcome. It does not mean that the Payment Initiation can never change again. If a refundable balance remains, another eligible refund request can move a Payment Initiation from RETURN_COMPLETE or RETURN_FAILED back to RETURN_IN_PROGRESS.

RETURN_IN_PROGRESS, RETURN_COMPLETE and RETURN_FAILED describe subsequent movement of funds. They do not change the recorded outcome of the original collection attempt.

Status fields

Use status first. statusCode and statusReason provide supporting information and may be absent. A FAILED Payment Initiation does not always have a rejection code, and an intermediate code may remain present if processing later times out.

Refund a Payment Initiation

Use the Refund Payment Initiation API to return all or part of a collected payment to the customer. A merchant-requested refund is different from the automatic return of late-arriving funds described above, although both use the RETURN_* statuses.

You can request a refund when the Payment Initiation has one of these statuses:

• SETTLED
• RETURN_COMPLETE
• RETURN_FAILED

You cannot request another refund while the status is RETURN_IN_PROGRESS. The Payment Initiation must have been created independently of a Payment Request, and your Azupay account must have enough available balance to process the refund.

Full refund

For a SETTLED Payment Initiation that has not already been partially refunded, provide the Payment Initiation ID and omit refundAmount:

POST https://api-uat.azupay.com.au/v1/paymentInitiation/refund?id=a050551479f625c066b559da28fee33c
Authorization: SECR_MYBUSINESSID_myapikey
Content-Type: application/json

Partial refund

To refund part of the payment, provide refundAmount. The amount cannot exceed PaymentInitiationStatus.refundInformation.availableBalance when that field is present.

The following request refunds $25.00:

POST https://api-uat.azupay.com.au/v1/paymentInitiation/refund?id=a050551479f625c066b559da28fee33c&refundAmount=25.00
Authorization: SECR_MYBUSINESSID_myapikey
Content-Type: application/json

Refund response and status

An accepted refund returns HTTP 200 and moves the Payment Initiation to RETURN_IN_PROGRESS. The response includes the remaining refundable balance and a record of each refund attempt:

{
  "PaymentInitiation": {
    "clientId": "MYBUSINESSID",
    "clientTransactionId": "INV-0000001-1",
    "paymentAmount": "100.00",
    "paymentAgreementId": "86ea437729e81567218cd013aa5e3d36"
  },
  "PaymentInitiationStatus": {
    "paymentInitiationId": "a050551479f625c066b559da28fee33c",
    "status": "RETURN_IN_PROGRESS",
    "refundInformation": {
      "availableBalance": "75.00",
      "requests": [
        {
          "createdDateTime": "2026-10-07T01:00:00.000Z",
          "nppTransactionId": "AZTPAU22XXXN20230419100000000000021",
          "status": "IN_PROGRESS",
          "amount": "25.00"
        }
      ]
    }
  }
}

Use refundInformation.requests to reconcile individual refund attempts:

When processing succeeds, the refund attempt moves to COMPLETE and the Payment Initiation moves to RETURN_COMPLETE. If processing fails, the attempt moves to FAILED, the Payment Initiation moves to RETURN_FAILED, and the failed amount becomes available to refund again.

Monitor refund status through the same Payment Initiation webhook and Get Payment Initiation API used for the original collection. If availableBalance is greater than zero after RETURN_COMPLETE, you can request another partial refund.

Refund errors

If a refund request is rejected with HTTP 400, the response uses details.failureCode = ERR0.03. Read details.failureReason for the specific cause. Common causes include:

• the refund amount is invalid or exceeds the available refundable balance
• another refund is already in progress
• the Payment Initiation is not in an eligible status
• the Payment Initiation is linked to a Payment Request and cannot be refunded through this API
• your Azupay account has insufficient available balance

HTTP 404 is returned when the Payment Initiation or its associated Payment Agreement cannot be found.

A rejected refund request does not move the Payment Initiation to RETURN_FAILED. That status is used only when an accepted refund later fails during processing.

Handle errors and retries

Payment Initiation failures occur at two different stages. Handle them differently.

Request-level error example

Handle the HTTP response before interpreting any Payment Initiation status:

403, 429 and 5xx responses are not defined outcomes for the Initiate a Payment operation in the published API contract. If one is received, handle it as an unexpected outcome rather than assuming that a Payment Initiation was or was not created.

Request errors are commonly returned with HTTP 400:

{
  "message": "The payment initiation limit has been reached for the current agreement period.",
  "details": {
    "failureCode": "AZP5.18",
    "failureReason": "The payment initiation limit has been reached for the current agreement period."
  }
}

An ERR0.03 response can indicate that:

• the Payment Agreement is not ACTIVE
• the Payment Agreement has not started or has expired
• a migrated direct debit arrangement is still within its five-day waiting period
• the amount exceeds the agreement limit or outstanding balance
• the request does not comply with a linked Payment Request
• the supplied metadata does not meet the required format

Processing codes

These codes provide additional information while a Payment Initiation is being processed. They are not HTTP API errors.

Common rejection codes

The following codes are commonly associated with a Payment Initiation that has entered FAILED.

Where the suggested response says to try again, the existing FAILED Payment Initiation remains final. Each retry is a separate collection attempt: create a new Payment Initiation with a new clientTransactionId and track its outcome separately.

Every new attempt is checked against the Payment Agreement as it exists at that time, including its status, validity dates, amount and applicable collection limits. Track retry counts and time windows in your integration, and stop when the individual code's limit is reached.

Some codes advise trying again later without defining a code-specific interval or attempt limit. Do not retry indefinitely. Apply a bounded retry policy defined for your integration, track every new attempt, and stop automated retries if the failure continues. Contact Azupay Support if you are unsure whether another collection attempt is permitted.

Search for Payment Initiations

Use the Payment Initiation Search API to find previously submitted collections. Date filters apply to the Payment Initiation's creation time—the time when the collection request was submitted—not its settlement or completion time.

Send a POST request to /v1/paymentInitiation/search:

POST https://api-uat.azupay.com.au/v1/paymentInitiation/search?numberOfRecords=100
Authorization: SECR_MYBUSINESSID_myapikey
Content-Type: application/json

Use only one search criterion in each request:

Do not combine clientTransactionId, paymentAgreementId or a date range in the same request.

Search by client transaction ID

{
  "PaymentInitiationSearch": {
    "clientTransactionId": "INV-0000001-1"
  }
}

Search by creation date

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

Search response and pagination

The response contains recordCount and a records array. Each record contains PaymentInitiation, PaymentInitiationStatus and the associated PaymentAgreement snapshot.

{
  "recordCount": 1,
  "records": [
    {
      "PaymentInitiation": {
        "clientId": "MYBUSINESSID",
        "clientTransactionId": "INV-0000001-1",
        "paymentAmount": "99.99",
        "paymentAgreementId": "86ea437729e81567218cd013aa5e3d36"
      },
      "PaymentInitiationStatus": {
        "paymentInitiationId": "a050551479f625c066b559da28fee33c",
        "status": "SETTLED",
        "createdDatetime": "2026-10-07T00:00:00.000Z",
        "completedDatetime": "2026-10-07T00:01:30.000Z"
      },
      "PaymentAgreement": {
        "clientId": "MYBUSINESSID"
      }
    }
  ]
}

numberOfRecords is optional and defaults to 100. When the response includes nextPageId, repeat the same search and pass that value in the query string to retrieve the next page:

POST https://api-uat.azupay.com.au/v1/paymentInitiation/search?numberOfRecords=100&nextPageId={nextPageId}
Authorization: SECR_MYBUSINESSID_myapikey
Content-Type: application/json

Test your integration in UAT

Before moving to production, test successful collections, expected failures, refunds and status monitoring in UAT.

For the standard happy path, UAT automation:

• approves Payment Agreements created using any PayID or BSB and account number
• processes Payment Initiations created against those agreements and moves them to SETTLED

You do not need to use a specific PayID or bank account to test successful agreement approval and payment settlement.

Specific test inputs are configured for repeatable unhappy-path scenarios. Use these two guides when planning and running your tests:

• Payment Initiation testing guide — follow the end-to-end procedure for collections, request validation, refunds and status monitoring.
• Payment Initiation test accounts — use the configured inputs for specific failure outcomes and rejection codes.

For each asynchronous scenario, verify the outcome through the configured webhook, the Get Payment Initiation API, or both.

Implementation checklist

Before moving to production, confirm that your integration:

• uses the correct base URL, client ID and API key for each environment
• creates payments only against an ACTIVE Payment Agreement
• validates that each amount complies with the agreement
• assigns one unique clientTransactionId to each collection attempt
• reuses that identifier only when retrying an uncertain create request
• stores PaymentInitiationStatus.paymentInitiationId from the HTTP 201 response
• treats CREATED and PENDING as non-final
• treats SETTLED and FAILED as final for the original collection attempt
• continues to reconcile later RETURN_* updates when refund or automatic-return tracking is required
• supports the configured full or thin webhook payload
• validates the webhook Authorization header against the value supplied for the transaction-level callback or the credentials configured by Azupay for a client-level destination
• handles duplicate webhook deliveries safely
• returns HTTP 200 for successfully handled webhook deliveries, including duplicates
• can retrieve the latest status when a webhook is delayed or unavailable
• creates a new Payment Initiation with a new clientTransactionId when retrying after FAILED
• tracks retry counts and time windows for each collection
• stops automated retries when the applicable code-specific limit is reached
• applies a documented bounded retry policy when a code does not define a specific interval or attempt limit
• checks refund eligibility and available balance before requesting a refund
• tracks each refund using refundInformation.requests
• follows nextPageId until all required Payment Initiation search results have been retrieved
• completes the documented UAT success, failure, refund and status-monitoring scenarios

Support

Contact Azupay Support if:

• a Payment Initiation remains unresolved longer than expected
• an unexpected or fatal rejection code is returned
• an agreement appears ACTIVE but the payment is reported as unauthorised
• you are unsure whether another collection attempt is permitted under the Payment Agreement

Raise a request through the Azupay Service Desk.