Payment Initiation

Once you have an active Payment Agreement in place you can automatically collect eligible payments aligned to the terms of the Payment Agreement.

🚧

Eligible payments only

You must only collect payments you are legally entitled to under a commercial arrangement you have with your customer. Your payment initiations must also align with the terms of the Payment Agreement you have with that customer, e.g. your payment initiations must be no more than the maximum amount in the Payment Agreement, your payment types must correspond to the payment type specified in the Payment Agreement, your frequency of payments must be consistent with the frequency terms in the Payment Agreement, and other conditions.

If you do initiate an ineligible payment you may find the payment can be reversed at a later time. In general, since your customer has approved the Payment Agreement in their bank there are far fewer situations in which payments are reversed than in other similar payment methods such as Direct Debit or card payments.

To make a payment initiation follow the payload example below:

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

{
  "PaymentInitiation": {
    "paymentInitiationNotification": {
      "endpointURL": "https://mybusiness.free.beeceptor.com",
      "authorizationHeader": "my-secret-header"
    },
    "clientId": "MYBUSINESSID",
    "clientTransactionId": "INV-0000001-1",
    "paymentAmount": "99.99",
    "paymentAgreementId": "86ea437729e81567218cd013aa5e3d36"
  }
}

Objects to note in this request:

• paymentInitiationNotification: As the payment initiation is an asynchronous request, a webhook is required so that your business can be notified once the payment initiation has been completed.

🚧

Failed payments refund behaviour

If a payment initiation is not settled or rejected within 24 hours since it is initiated, it will be marked as FAILED. Any payment received afterward will be refunded.

Status Code and Status Reason

PaymentInitiationStatus.status field will change for different reasons.

The underlying reason will be captured as status code in the PaymentInitiationStatus.statusCode field.
These codes are standard across the NPP network participants and are returned by the destination institution as opposed to Azupay.

The reason description will be captured in the PaymentInitiationStatus.statusReason field.

Failure Codes and Failure Reasons

When:

• creating a payment agreement
• amending a payment agreement
• creating a payment initiation

in 400 error scenarios, you may get a response with an optional details object containing a:

• failureCode and
• failureReason

Example:

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

Below are the mappings for the codes and reasons:

Issuing Refunds

Full refunds

Once you have received a payment initiation, and it is in SETTLED status you can do a full refund by performing an API call like the following, again using the paymentInitiationId:

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

You will get a response like the following

{
  "PaymentInitiation": {
    ...
  },
  "PaymentInitiationStatus": {
    ...
    "status": "RETURN_IN_PROGRESS",
    "refundInformation": {
      "availableBalance": "0.00",
      "requests": [
        {
          "createdDateTime": "2021-04-25T23:52:56.189Z",
          "nppTransactionId": "AZTPAU22XXXN20230419100000000000020",
          "status": "IN_PROGRESS",
          "amount": "500.00"
        }
      ]
    }
  }
}

The status of the PaymentInitiation will go into RETURN_IN_PROGRESS which means it has been initiated but not completed yet.

After some time, and assuming you have enough balance with Azupay to perform the refund, you can enquire about the status for the PaymentInitiation and see a change on the status to RETURN_COMPLETE indicating the refund has completed successfully.

{
  "PaymentInitiation": {
    ...
  },
  "PaymentInitiationStatus": {
     ...
    "status": "RETURN_COMPLETE",
    "refundInformation": {
      "availableBalance": "0.00",
      "requests": [
        {
          "createdDateTime": "2021-04-25T23:52:56.189Z",
          "completedDateTime": "2021-04-25T23:52:58.189Z",
          "nppTransactionId": "AZTPAU22XXXN20230419100000000000020",
          "status": "COMPLETE",
          "amount": "500.00"
        }
      ]
    }    
  }
}

Partial refunds

To do a partial refund you would submit a similar request than for full refund but adding a refundAmount query parameter to the request.

Say you have a completed PaymentInitiation for $100 and you do a partial refund of $25 using a POST like the following.

POST https://{{api-host}}/v1/paymentInitiation/refund?id=a050551479f625c066b559da28fee33c&refundAmount=25
Authorization: SECR_MYBUSINESSID_myapikey
Content-Type: application/json

Once the refund is completed, when you enquire on the PaymentInitiation you will see a response like the one below.

{
  "PaymentInitiation": {
    ...
  },
  "PaymentInitiationStatus": {
    ...,
    "refundInformation": {
      "availableBalance": "75.00",
      "requests": [
        {
          "nppTransactionId": "AZTPAU22XXXN20230419100000000000020",
          "createdDateTime": "2021-04-22T06:40:25.198Z",
          "completedDateTime": "2021-04-23T05:42:09.373Z",
          "status": "COMPLETE",
          "amount": "25.00"
        }
      ]
    },
    "status": "RETURN_COMPLETE",
  }
}

The latest entry in the refundInformation object will contain the information about the partial refund.