Azupay website
Guides
Help CentreService DeskStatus PageDashboard | ProductionDashboard | UATTest Bank
Start typing to search…

Testing & integration - PaymentInitiation API

Before you begin - test setup in UAT

In the UAT environment, you'll be provided with a UAT clientId. Additionally, ensure you have:

  • An activepaymentAgreementId.
  • A webhook endpoint ready for callback notifications

These are necessary for simulating live payment flows, refunds, and error conditions in testing.

Create payment initiation- happy path

Test Case 1: Create payment initiation

Steps to Complete:

  • Call PaymentInitiation API with a POST request : https://api-uat.azupay.com.au/v1/paymentInitiation
  • Send in valid fields: clientId, clientTransactionId, paymentAgreementId, paymentAmount, description and a valid paymentInitiationNotification block including endpointURL and authorizationHeader.

Sample request:

\{
  
  "PaymentInitiation": {
    "paymentInitiationNotification": {
      "endpointURL": "https://yourapp.example.com/webhook/payment-initiation",
      "authorizationHeader": "Bearer your-secret-token"
    },
    "clientId": "AZUPAYDemoClient",
    "clientTransactionId": "DFHGFFDSZRTYDG12976544789",
    "paymentAmount": "99.99",
    "paymentAgreementId": "abd5fea08d3a7290991fd6ce09f00d79",
    "description": "Payments for goods and services"
  }
  • Observe the API response (see API response example below) and watch for the webhook (if configured) or poll via GET /v1/paymentInitiation.

API response

\{
  
    "PaymentInitiation": {
        "paymentInitiationNotification": {
            "endpointURL": "https://yourapp.example.com/webhook/payment-initiation",
            "authorizationHeader": "****"
        },
        "clientId": "AZUPAYDemoClient",
        "clientTransactionId": "DFHGFFDSZRTYDG12976544789",
        "paymentAmount": "99.99",
        "paymentAgreementId": "abd5fea08d3a7290991fd6ce09f00d79",
        "description": "Payments for goods and services",
        "metaData": {}
    },
    "PaymentInitiationStatus": {
        "paymentInitiationId": "da377b192319e36e4eec5933c7b1d666",
        "nppTransactionId": "AZTPAU22XXXI20250814000000000000140",
        "status": "CREATED",
        "createdDatetime": "2025-08-14T01:22:03.424Z"
    },
    "PaymentAgreement": {
        "payerDetails": {
            "name": "Sally Smith",
            "type": "Person",
            "payIDDetails": {
                "payIDType": "PHONE",
                "payID": "+61-400123123"
            }
        },
        "paymentAgreementType": "RETAIL",
        "clientId": "AZUPAYDemoClient",
        "variant": "API",
        "description": "Payment Agreement testing",
        "clientTransactionId": "6206968f-c626-4afe-a729-3baa9199fd47",
        "agreementDetails": {
            "variableAgreementDetails": {
                "startDate": "2025-08-14",
                "maximumAmount": "500.00",
                "frequency": "ADHOC"
            }
        }
    }
}

Expected Outcome:

  • API returns 201 – Payment Initiated.

Create payment initiation - Negative Test Cases

Error conditions triggered by malformed or invalid inputs:

Test Case 2: Invalid clientId

Steps to Complete:

Test Case 3: Non-existent paymentAgreementId

Steps to Complete:

Test Case 4: State or Amount Violations

Steps to Complete:

  • Call PaymentInitiation API with a POST requesthttps://api-uat.azupay.com.au/v1/paymentInitiation
  • Trigger errors like fixedAgreementFirstPaymentAmountError, invalidStateError, or validityPassedError by using expired or amount-out-of-bounds agreement conditions.
  • Expect corresponding 400 error codes.

Test Case 5: Malformed Request

Steps to Complete:


Receiving Payments - happy path

Test Case 6: Successful payment initiation against active Payment agreement

Steps to Complete:

  • Use PaymentAgreementRequest API via Subscriptions to create payment agreement with PayID: +61-400123123
  • Create payment initiation against the Payment agreement, payment amount can be any amount
  • Payment initiation status should change from CREATED to SETTLED - verify with webhook notification of payment initation status change or check status of payment initiation with GET request at https://api-uat.azupay.com.au/v1/paymentInitiation

Receiving Payments - payment initiation failure

Test Case 7: Payment initiation created and payment fails due to insufficient funds

  • Use PaymentAgreementRequest API via Subscriptions to create payment agreement with PayID: +61-400111222
  • Create payment initiation against the Payment agreement, payment amount can be any amount
  • Payment initiation should be successfully created but status should change from CREATED to FAILED with failure code AM04, statusReason ‘Insufficient funds. Please try again later up to 5 times within 24 hours’. Verify with webhook notification of payment initiation status change or check status of payment initiation with GET request at https://api-uat.azupay.com.au/v1/paymentInitiation

Test Case 8: Payment initiation created and payment fails due to generic error

  • Use PaymentAgreementRequest API via Subscriptions app to create payment agreement with PayID: +61-400123123
  • Create payment initiation against the Payment agreement, set paymentAmount to $88.88
  • Payment initiation should be successfully created but status should change from CREATED to FAILED with failure code: AC02, statusReason “The Debtor Account Number is invalid or missing”. Verify with webhook notification of payment initiation status change or check status of payment initiation with GET request at https://api-uat.azupay.com.au/v1/paymentInitiation

Test Case 9: Attempt to create payment initiation against cancelled payment agreement

  • Use PaymentAgreementRequest API via Subscriptions app to create payment agreement with PayID: [email protected]
  • Create payment initiation against the Payment agreement, set any amount
  • Payment initiation creation is unsuccessful with API error response, ERRO.03 “Invalid Payment Agreement status. Should be ACTIVE.”

Test Case 10: Attempt to create payment initiation against suspended payment agreement

  • Use PaymentAgreementRequest API via Subscriptions app to create payment agreement with PayID: [email protected]
  • Create payment initiation against the Payment agreement, set any amount
  • Payment initiation creation is unsuccessful with API error response, ERRO.03 “Invalid Payment Agreement status. Should be ACTIVE.”

Refund Flow

Test Case 11: Partial refunds

**Steps to Complete: **

  • Call PaymentInitiation API with a POST requesthttps://api-uat.azupay.com.au/v1/paymentInitiation/refund
  • Send in: id, refundAmount(refund amount less than total payment initiation amount)
  • Expected outcome: Receive API response 200: Payment Refunded . Webhooks: RETURN_IN_PROGRESS and RETURN_COMPLETE

Test Case 12 : Full refund

Steps to Complete:

  • Call PaymentInitiation API with a POST requesthttps://api-uat.azupay.com.au/v1/paymentInitiation/refund
  • Send in: id, refundAmount (refund amount equal to total payment initiation amount)
  • Expected outcome: Receive API response 200: Payment Refunded . Webhooks: RETURN_IN_PROGRESS and RETURN_COMPLETE

Webhook & Status Monitoring

Test Case 13: Asynchronous Status Flow

After sending a valid POST /v1/paymentInitiation, monitor via:

  • Webhook events, if enabled
  • GET /v1/paymentInitiation with the paymentInitiationId

Expected Outcome:

  • Observe logical status transitions such as PENDING →` SETTLED`` or failure codes when errors occur.
  • Ensure statusReason fields are meaningful.

Updated 5 days ago