Payment APIs

Overview of how to send outbound payments

Sending Payments

Our PayOut product allows your business to send payments using the New Payments Platform (NPP) via our easy-to-use Payments APIs. This guide will walk you through the steps you need to follow to make outbound real time payments using our Payments APIs.
Let's assume you already have an API Key (myapikey) and a clientId (MYBUSINESSID) with Azupay.

๐Ÿ‘

Who can I pay via PayOut?

You can make a payment to a PayID or to a BSB and Account Number. The account must be an Australian bank account.

๐Ÿ‘

What banks are supported?

We support payments to all BSB's (all Australian banks). However, to get instant payment, the BSB must be reachable via the New Payments Platform (NPP). >99% of Australian banks are connected to NPP.
We provide APIs to facilitate this check. You can also check whether an institution is reachable by checking the New Payments Platform Association (NPPA) website.

Adding funds to your PayOut account

PayOut sends funds out from a settlement account we hold on your behalf.

The PayOut account can be credited with funds as follows:

  1. Login to the dashboard
  2. Copy or note your TopUp PayID visible on your dashboard home page, if you do not see the TopUp PayID it may need to be enabled:
    1. Navigate to Settings
    2. Find the "TopUp PayID" section and click Enable
  3. Make a payment to the specified top-up PayID from your online banking.

๐Ÿ“˜

Toping up your test bank

To top-up your account in test environment use our test-bank utility.

Making a payment

Supported PayID types

You can make a payment to a PayID which is either an:

  • Email
  • Phone Number (landline or mobile)
  • ABN/ACN
  • Organisation ID

Validating a PayID

๐Ÿ“˜

Need a test PayID?

You can use Test PayID's when playing with this API.

You can validate a PayID using the Check PayID Status API prior to making the actual payment. Simply make the following API call:

POST https://api.azupay.com.au/v1/payIDEnquiry
Authorization: SECR_MYBUSINESSID_myapikey
Content-Type: application/json
{
  "payID": "[email protected]",
  "payIDType": "EMAIL"
}

This should yield the following response:

{
  "AccountStatus": {
    "nppReachable": true,
    "accountServices": [
      "x2p1"
    ]
  }
}
  • AccountStatus.nppReachable: This indicates that the PayID is valid and since PayIDs are only on NPP you now know the account is reachable via the NPP.

  • AccountStatus.accountServices: Provides a list of supported NPP services

    • x2p1 indicates that the account is hosted at an Osko certified institution
      which provides stronger assurances of 'instantaneousness'.
    • sct provides a lower level 'instantaneousness' assurance.

Now that you have established that the PayID is reachable via NPP, you can progress to actually making
the payment!

Making a payment to a PayID

It's as simple as issuing an API call:

POST https://api.azupay.com.au/v1/payment
Authorization: SECR_MYBUSINESSID_myapikey
Content-Type: application/json
{
  "Payment": {
    "clientPaymentId": "c8ec39dc-2a70-4440-bc92-0e8f1b263d8f",
    "payeeName": "Mr Someone Somewhere",
    "payID": "[email protected]",
    "payIDType": "EMAIL",
    "paymentAmount": "2200.00",
    "paymentDescription": "Payment for wages August 2020.",
    "paymentNotification": {
      "paymentNotificationEndpointUrl": "string",
      "paymentNotificationAuthorizationHeaderValue": "string"
    }
  }
}

Ok, let's get the obvious stuff out of the way first:

  • Payment.payeeName: This is the account holder's name
  • Payment.payID: This is the PayID you are making a payment to
  • Payment.payIDType: This is the type of PayID. We are paying to an email address so this is set to EMAIL
  • Payment.paymentDescription: This is the description that will appear on the account holders bank statement

Next, the not so obvious stuff:

{
  "Payment": {
    "clientPaymentId": "c8ec39dc-2a70-4440-bc92-0e8f1b263d8f",
    "payeeName": "Mr Someone Somewhere",
    "payID": "[email protected]",
    "payIDType": "EMAIL",
    "paymentAmount": "2200.00",
    "paymentDescription": "Payment for wages August 2020.",
    "ultimatePayerName": "ABC Pty. Ltd."
  }
}
  • Payment.clientPaymentId: Use this field to specify an identifier that can be used to correlate this transaction
    back to a record in your system. In this payroll example, you may consider using an id which is a composite of
    employeeid-month-year or a uuid as per the sample.

  • Payment.ultimatePayerName: The name of the ultimate payer. Lets you control the Payer description (visible to the payee) on the payment:

    • If not populated, then your business name will appear i.e. "My business name".
    • If populated, then the ultimate payer name will appear instead.

Once you submit the request, you will get the following response:

{
  "PaymentStatus": {
    "status": "CREATED",
    "paymentId": "4412792d84524100b7e042add1c7be47",
    "createdDatetime": "2021-07-10T06:39:39.749Z",
    "currentBalance": 999
  }
}
  • PaymentStatus.status: A value of CREATED here means that Azupay has accepted your request for making this payment by checking your account balance and ensuring that the PayID specified is valid.
  • PaymentStatus.paymentId: This is a unique identifier generated by Azupay that can be used to enquire about the status of the payment in the future.
  • PaymentStatus.createdDatetime: The time in GMT offset of when the payment was created.
  • PaymentStatus.currentBalance: The current balance of your outbound payments account.

Now you can check the Payment status

Validating BSB

When using a BSB and Account Number, only the BSB can be validated for NPP reachability. It's not possible to validate that an Account Number is valid. This is still useful and can be done as follows:

POST https://api.azupay.com.au/v1/accountEnquiry
Authorization: SECR_MYBUSINESSID_myapikey
Content-Type: application/json
{
  "bsb": "123456"
}

The response for this will be:

{
  "AccountStatus": {
    "nppReachable": true,
    "accountServices": [
      "x2p1"
    ]
  }
}
  • AccountStatus.nppReachable: This indicates that the BSB is NPP reachable. If this value is false then the payment will either route to Australia's older deferred settlement system (Direct Entry, DE) or will return an error code depending on configuration you set.

    • Our default is to automatically route to DE but you can choose to turn this off if real time settlement is critical to you. DE will typically settle next business day but may take up to 3 days.
  • AccountStatus.accountServices: Provides a list of supported NPP services

    • x2p1 indicates that the institution is Osko certified which provides stronger assurances of
      'instantaneousness'.
    • sct provides a lower level 'instantaneousness' assurance.

Making a payment to a BSB and Account Number

Making a payment to a BSB and Account Number is the almost the same as Making a payment to a PayID.
As you might imagine the only difference in the POST /v1/payment call; omit the payID and payIDType fields and use bsb and accountNumber instead.

Validate if a BSB and Account number is associated with a PayID

There are some cases where you have the BSB, account number and payID and want to validate whether
the PayID is associated with the BSB and account number. For that you can add additional bsb and accountNumber to the parameters of the POST /v1/payIDEnquiry call.

POST https://api.azupay.com.au/v1/payIDEnquiry
Authorization: SECR_MYBUSINESSID_myapikey
Content-Type: application/json
{
  "payID": "[email protected]",
  "payIDType": "EMAIL",
  "bsb": "123456",
  "accountNumber": "9876543"
}

The response for this will be:

{
  "AccountStatus": {
    "nppReachable": true,
    "accountServices": [
      "x2p1"
    ],
    "validBsb": true,
    "validAccountNumber": true,
    "bic11": "BANKXXXXXXX"
  }
}
  • validBsb: a true value here indicates that the BSB associated with PayID [email protected] matches the value supplied in the request field bsb
  • validAccountNumber: a true value here indicates that the Account Number associated with PayID [email protected] matches the value supplied in the request field accountNumber
  • bic11: This field contains the BIC11 code of the underlying institution. This lets you identify the bank, i.e. Commonwealth Bank

Making a payment to an account that is not reachable via the NPP

Whilst the majority of Australian bank accounts are reachable by NPP, some remain accessible only via the slower and older Direct Entry (DE) network. Azupay supports payments to these older accounts via the same set of API's with a few key differences:

  • Will typically settle next business day but can take up to 3 business days to settle.
  • Can only be made to BSB and account number, not a PayID. A PayID is only accessible by the NPP.
  • If the payment fails due to an issue on the target bank side then it will not be reported via the usual PaymentStatus.status field of the Azupay GET /v1/payment api or the webhook.
  • You will receive a webhook for the transition to SETTLED status if successful or RETURNED if the receiving bank notifies of a problem only.

Checking for a Payment status

As the process of settling the payment into the target account is asynchronous, you will need to poll the payment
using the paymentId.

Polling is as simple as:

GET https://api.azupay.com.au/v1/payment?id=4412792d84524100b7e042add1c7be47
Authorization: SECR_MYBUSINESSID_myapikey
Content-Type: application/json
{
  "Payment": {
    "clientPaymentId": "c8ec39dc-2a70-4440-bc92-0e8f1b263d8f",
    "payeeName": "Mr Someone Somewhere",
    "payID": "[email protected]",
    "payIDType": "EMAIL",
    "paymentAmount": "2200.00",
    "paymentDescription": "Payment for wages August 2020."
  },
  "PaymentStatus": {
    "paymentId": "4412792d84524100b7e042add1c7be47",
    "currentBalance": 999,
    "createdDatetime": "2021-07-10T06:39:39.749Z",
    "settlementDatetime": "2021-07-10T06:39:39.398Z",
    "completedDatetime": "2021-07-10T06:39:42.398Z",
    "status": "SETTLED"
  }
}

Great! Looks like the payment has SETTLED and we have some additional timestamps - settlementDatetime and completedDatetime.

Payments can fail for a number of reasons. Some of these failures are immediate and others are identified after the
outbound payment request has been submitted. Immediate failures result in a failure response at the time of issuing
the POST /v1/payment call. Other failures are reflected in the PaymentStatus.status field of the outbound payment request. Here is a table outlining what each of these statuses mean:

StatusMeaning
CREATEDAzupay has accepted and is processing your request to make a payment
SETTLEDThe funds have been credited to the target account
FAILEDThe target institution has not accepted the funds. This could be because the account is no longer valid
PENDINGAzupay is waiting for the institution to acknowledge the credit of funds
RETURNEDThe target institution initially SETTLED the payment but later returned it

๐Ÿ‘

Avoiding Edge Cases

The best way to avoid edge cases is to make payments to a PayID and not a BSB and Account Number. This is because the latter does not allow for validation of account number value.

Failure reason codes

PaymentStatus.status field can be marked as FAILED for different reasons. The underlying reason will be captured in the PaymentStatus.failureReason field. These codes are standard across the NPP network amongst participants and are returned by the destination institution as opposed to azupay.

ReasonCode Description
AB01Clearing process aborted due to timeout. NPP Error. Client should retry for up to 8 hours before failing the payment and crediting the customers account.
AB02Clearing process aborted due to fatal error. NPP Error. Client should retry for up to 8 hours before failing the payment and crediting the customers account.
AC02The Debtor Account Number is invalid or missing.
AC03The Payee is unable to accept a Clearing Request because the account to be credited does not exist.
AC05The original debtor account number is closed and a Payment Return (Unsolicited) cannot be made.
AC06The Account is blocked and cannot accept credits. This includes instances of suspected fraud, sanctions or a credit is unable to be applied to the account type e.g. mortgage, term deposit account.
AC07The account to be credited is closed.
AC14Account exists but cannot accept funds (unreachable via NPP)
AG01Account exists but does not support credits.
AG03The account to be credited is open, but cannot accept NPP credit for the NPP service.
AGNTThe account does not belong to the account servicer (i.e. incorrect agent/reference data usage) or the incorrect clearing and settlement agency relationships are used.
AM01The service prohibits the use of zero dollar Payments.
AM02The transaction is greater than the maximum NPP limit of $99,999,999,999 or rules of a service have a maximum amount limit.
AM03Where the currency cannot be applied to the specified account. The Interbank settlement Currency is not AUD.
AM06Specified transaction amount is less than agreed minimum.
AM12The Amount in the Clearing or Settlement Request is missing, invalid or the amount in the Settlement Request does not match to the amount in the Clearing Request.
AM13Transaction amount exceeds limits set by clearing system.
AM18Number of Transactions is Invalid.
AM19The Number of transactions does not equal to โ€˜1โ€™.
AM22Unable to apply zero amount to designated account.
BE06End customer specified is not known at associated Sort/National Bank Code or does no longer exist in the books.
BE08Debtor name is missing.
BE18Contact details missing or invalid.
BE22The information regarding the Creditor Name is required but not provided.
CH17Element is not allowed.
CH20Number of decimal points not compatible with the currency.
CH21Mandatory element is missing.
DT01Invalid date (e.g. wrong or missing settlement date)
DT02The CreationDateTime in the GroupHeader is not as per the required format (UTC expressed without offset, i.e. YYYY-MM-DDThh:mm:ss.sssZ) or, where the date is too far in the past or in the future.
ED06(Full Participants Only) Under NPPA direction, Participants may reject clearing requests based on the FSS being unavailable.
FF01File Format incomplete or invalid.
FF04The Service Level code is not as per the specified format or is invalid based on the message type or membership.
FF08End to End ID missing or invalid.
FF10Unable to process due to back office issues or outage.
FF11Clearing Request rejected due it being subject to a previous abort operation.
RC05The BIC identifier is invalid or missing.
RR05Regulatory or Central Bank Reporting information missing, incomplete or invalid.
RR07Remittance information structure does not comply with rules for Payment type.
L001Cuscal account error. Cuscal is unable to debit funds to make the payment. Client should retry for up to 8 hours before failing the payment and crediting the customers account
PA01Participant Available. Receiving bank is experiences problems. Client should retry for up to 8 hours before failing the payment and crediting the customers account.
PA02Participant Flooded. Receiving bank is experiences problems. Client should retry for up to 8 hours before failing the payment and crediting the customers account.
PA03Participant Recovering. Receiving bank is experiences problems. Client should retry for up to 8 hours before failing the payment and crediting the customers account.
PA04Participant Not Available. Receiving bank is experiences problems. Client should retry for up to 8 hours before failing the payment and crediting the customers account.
PA05Participant Under Stress. Receiving bank is experiences problems. Client should retry for up to 8 hours before failing the payment and crediting the customers account.
TD03The file format is incomplete or invalid.

Return reason codes

PaymentStatus.status field can be marked as RETURNED for different reasons. The underlying reason will be captured in the PaymentStatus.returnedReason field. These codes are standard across the NPP network amongst participants and are returned by the destination institution as opposed to azupay.

ReasonCode Description
AC03Wrong IBAN in BSCT
AC04Account number specified has been closed on the bank of accountโ€™s books
AC06Account specified is blocked, prohibiting posting of transactions against it.
AM03Specified message amount is a non processable currency outside of existing agreement
AM05Duplication
AM09Amount received is not the amount agreed or expected
BE05Party who initiated the message is not recognised by the end customer
BE08Returned as a result of a bank error

Webhooks

If you prefer to receive an HTTP call whenever a payment has reached SETTLED or FAILED status,
you can do so by passing additional parameters for the endpoint and secret header when creating the Payment.

{
  "Payment": {
    "clientPaymentId": "c8ec39dc-2a70-4440-bc92-0e8f1b263d8f",
    "payeeName": "Mr Someone Somewhere",
    "payID": "[email protected]",
    "payIDType": "EMAIL",
    "paymentAmount": "2200.00",
    "paymentDescription": "Payment for wages August 2020.",
    "paymentNotification": {
      "paymentNotificationEndpointUrl": "string",
      "paymentNotificationAuthorizationHeaderValue": "string"
    }
  }
}
  • Payment.paymentNotification can be populated to enable a webhook. This means that Azupay will invoke your webhook when the payment has either SETTLED or FAILED (more on statuses later).
  • Payment.paymentNotification.paymentNotificationEndpointUrl: Supply an internet accessible endpoint that Azupay can invoke.
  • Payment.paymentNotification.paymentNotificationAuthorizationHeaderValue: Supply a value that can be used by Azupay to pass any authorization and authentication checks on your system. We highly recommend using a unique value per outbound payment for maximum security.

๐Ÿšง

Webhook calls are made on a 'best effort' basis

This webhook call is made by Azupay on a best effort basis. Azupay will implement retry mechanisms to ensure transient network failures do not affect the ability to call this endpoint. Azupay may call this endpoint more than once with the same payload so the merchant must ensure that the endpoint implements idempotent behaviour.

AzupayOut statuses

The following is a state diagram for AzupayOut payments.

StatusMeaning
CREATEDAzupay has accepted and is processing your request to make a payment
SETTLEDThe funds have been credited to the target account
FAILEDThe target institution has not accepted the funds. This could be because the account is no longer valid
PENDINGAzupay is waiting for the institution to acknowledge the credit of funds
RETURNEDThe target institution initially SETTLED the payment but later returned it

Test Accounts

In the UAT environment, we provide you with fictitious accounts and PayID's in order to test all possible outbound payment outcomes for the AzupayOut product. These are listed below:

PayID's

PayIDPayIDTypeExpected Behaviour
[email protected]EmailA call to POST /v1/payment will fail with 400 status code
[email protected]EmailSuccessful payment
orgnnameORGSuccessful payment
+61-454444555PHONESuccessful payment
34455445454ABNSuccessful payment

BSB and Account Numbers

BSBAccount NumberPOST /v1/paymentGET /v1/payment
PaymentStatus.status
GET /v1/payment
PaymentStatus.failureReason
GET /v1/payment
PaymentStatus.sentViaDE
06200012345999Will succeedSETTLEDN/AN/A
06200012345678Will succeedFAILEDAGNTN/A
06200012345777Will succeedSETTLEDN/Atrue
06200012345888Will succeedPENDING then later SETTLEDN/AN/A
06200012345444Will succeedSETTLED then later RETURNEDN/AN/A