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:

👍

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.

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.

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.

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

BSB and Account Numbers