Send outbound NPP payments to a PayID or to a BSB and account number, then poll for settlement status. Search prior payments. Part of Azupay's AzupayOut disbursement/payout product for real-time money movement.
openapi: 3.0.1
info:
title: Azupay Payment API
description: API Reference
version: v1
contact:
email: contactus@azupay.com.au
servers:
- url: https://api-uat.azupay.com.au/v1
description: UAT environment
- url: https://api.azupay.com.au/v1
description: Production environment
tags:
- name: Payment
description: 'This API allows you to make outbound payments to PayID or NPP enabled BSB accounts.
'
paths:
/payment:
get:
operationId: getPayment
security:
- SecretKey: []
tags:
- Payment
summary: Get a Payment.
description: Retrieves the status of a previous Make a Payment call. Use the contents of the response
body to determine whether the payment has completed.
parameters:
- in: query
name: id
description: ID of Payment to retrieve. This is the paymentId returned by the makePayment call.
required: true
schema:
type: string
responses:
'200':
description: The payment object
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PaymentObj'
- $ref: '#/components/schemas/PaymentStatusObj'
'400':
description: Invalid request
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ErrorModel'
'401':
description: Invalid Authorization header
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ErrorModel'
'404':
description: Payment Request Not Found
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ErrorModel'
post:
security:
- SecretKey: []
tags:
- Payment
summary: Make a Payment.
description: 'Make an outbound payment to the provided PayID or BSB/Account Number.
Once made, you can poll for PaymentStatus using getPayment to determine
whether or not the payment was settled to the payee.
'
operationId: makePayment
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentObj'
examples:
PayID via Email Successful (Test Case):
value:
Payment:
clientPaymentId: update-me-to-some-unique-value
payeeName: Edward Engineer
payID: engineering@azupay.com.au
payIDType: EMAIL
paymentAmount: '100.00'
paymentDescription: A successful test case when a PayID via Email succeeds
paymentReference: update-me-to-some-unique-value
PayID via Org Successful (Test Case):
value:
Payment:
clientPaymentId: update-me-to-some-unique-value
payeeName: Edward Engineer
payID: orgnname
payIDType: ORG
paymentAmount: '120.00'
paymentDescription: A successful test case when a PayID via Org succeeds
paymentReference: update-me-to-some-unique-value
PayID via Phone Successful (Test Case):
value:
Payment:
clientPaymentId: update-me-to-some-unique-value
payeeName: E. Engineering Pty Ltd
payID: +61-454444555
payIDType: PHONE
paymentAmount: '1800.00'
paymentDescription: A successful test case when a PayID via Phone succeeds
paymentReference: update-me-to-some-unique-value
PayID via ABN Successful (Test Case):
value:
Payment:
clientPaymentId: update-me-to-some-unique-value
payeeName: E. Engineering Pty Ltd
payID: '34455445454'
payIDType: ABN
paymentAmount: '344.00'
paymentDescription: A successful test case when a PayID via ABN succeeds
paymentReference: update-me-to-some-unique-value
PayID Not Found Error (Test Case):
value:
Payment:
clientPaymentId: update-me-to-some-unique-value
payeeName: Carmen Saint Diago
payID: not-found@example.com
payIDType: EMAIL
paymentAmount: '100.00'
paymentDescription: An unsuccessful test case when a PayID can't be found
paymentReference: update-me-to-some-unique-value
BSB and Account via NPP Rails Successful (Test Case):
value:
Payment:
clientPaymentId: update-me-to-some-unique-value
payeeName: Ashley Account
bsb: '062000'
accountNumber: '12345999'
paymentAmount: '100.00'
paymentDescription: A successful test case when an NPP payment is made via BSB and
Account Number
paymentReference: update-me-to-some-unique-value
BSB and Account via NPP Rails Successful but delayed in settling (Test Case):
value:
Payment:
clientPaymentId: update-me-to-some-unique-value
payeeName: Ashley Account
bsb: '062000'
accountNumber: '12345888'
paymentAmount: '100.00'
paymentDescription: A successful test case when an NPP payment is made via BSB and
Account Number but delayed in settling.
paymentReference: update-me-to-some-unique-value
BSB and Account via NPP Rails Successful but later returned (Test Case):
value:
Payment:
clientPaymentId: update-me-to-some-unique-value
payeeName: Ashley Account
bsb: '062000'
accountNumber: '12345444'
paymentAmount: '100.00'
paymentDescription: A successful test case when an NPP payment is made via BSB and
Account Number but later returned.
paymentReference: update-me-to-some-unique-value
BSB and Account via NPP Rails Unsuccessful (Test Case):
value:
Payment:
clientPaymentId: update-me-to-some-unique-value
payeeName: Ashley Account
bsb: '062000'
accountNumber: '12345678'
paymentAmount: '100.00'
paymentDescription: An unsuccessful test case when an NPP payment is made via BSB
and Account Number
paymentReference: update-me-to-some-unique-value
BSB and Account via DE Rails Successful (Test Case):
value:
Payment:
clientPaymentId: update-me-to-some-unique-value
payeeName: Ashley Account
bsb: '062000'
accountNumber: '12345777'
paymentAmount: '100.00'
paymentDescription: A successful test case when a DE payment is made due to an account
being NPP unreachable.
paymentReference: update-me-to-some-unique-value
responses:
'201':
description: Payment received
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentStatusObj'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'401':
description: Invalid Authorization header
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'409':
description: Duplicated payment
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
callbacks:
PaymentStatus:
'{$request.body#/Payment/paymentNotification/paymentNotificationEndpointUrl}':
post:
summary: Payment Status Event
description: 'If the merchant specifies values for the
`Payment/paymentNotification` object during the Make Payment invocation, then an event
message is sent once the
payment has reached a status of `SETTLED` or `FAILED`.
The event will use `paymentNotification.paymentNotificationEndpointUrl` as endpoint and
`paymentNotification.paymentNotificationAuthorizationHeaderValue` as `Authorization` header.
We strongly recommend to use a different value for `paymentNotificationAuthorizationHeaderValue`
on each payment request to increase the level of security.
If the target endpoint does not return HTTP `200`, azupay will retry the webhook call
45 times with a 20 second delay.
The merchant system can correlate the event message using either the `Payment.clientPaymentId`
provided on the
original request or the `PaymentStatus.paymentId` provided in the response of the original
request. Also it is required the merchant endpoint to be idempotent, so the outcome of
the event
is the same even if the same event is sent more than once.
'
parameters:
- in: header
name: Authorization
description: 'The value will be what was specified in
{$request.body#/Payment/paymentNotification/paymentNotificationAuthorizationHeaderValue}
'
schema:
type: string
required: true
requestBody:
required: true
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PaymentObj'
- $ref: '#/components/schemas/PaymentStatusObj'
responses:
'200':
description: The merchant's server should return this code
/payment/search:
post:
security:
- SecretKey: []
tags:
- Payment
summary: Search for Payments.
description: 'Search for Payments
'
operationId: searchPayment
parameters:
- in: query
name: nextPageId
description: The next page ID that was obtained on a previous search result. Used to obtain the
next set of results
required: false
schema:
type: string
- in: query
name: numberOfRecords
description: Number of records to retrieve. Defaults to 100 if not provided
required: false
schema:
type: number
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentSearchObj'
responses:
'200':
description: The requested page of outbound payments
content:
application/json:
schema:
type: object
properties:
nextPageId:
type: string
description: 'If there are more results you can invoke this search again providing
the nextPageId in
the query parameters to retrieve the next set of results.
'
recordCount:
type: number
description: 'The number of records that were retrieved.
'
records:
type: array
description: 'The result from the search
'
items:
$ref: '#/components/schemas/PaymentSearchResponseObj'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
'401':
description: Invalid Authorization header
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorModel'
components:
schemas:
ErrorModel:
type: object
additionalProperties: false
required:
- message
properties:
message:
type: string
details:
type: object
additionalProperties: false
properties:
failureCode:
type: string
failureReason:
type: string
required:
- failureCode
- failureReason
PaymentObj:
type: object
additionalProperties: false
required:
- Payment
properties:
Payment:
type: object
additionalProperties: false
required:
- payeeName
- clientPaymentId
- paymentAmount
- paymentDescription
properties:
clientPaymentId:
description: Unique Id for the payment created by the merchant system
type: string
minLength: 5
maxLength: 100
pattern: ^[a-zA-Z0-9\-_]*$
example: c8ec39dc-2a70-4440-bc92-0e8f1b263d8f
payeeName:
description: The name of the Payee this payment is being sent to.
type: string
pattern: ^[ -~]{1,140}$
example: Mr John Smith or ABC Corp Pty Ltd
payID:
type: string
minLength: 1
maxLength: 140
description: 'The PayID for this payment. Payer can supply either a PayID or BSB/Account
Number combination but not both.
'
example: johndoe@example.com
payIDType:
type: string
description: 'PayID Type. Only used when payment is addressed to a PayID. Valid Values:
- ''PHONE’ Can be a mobile phone number or landline with area code. For example `+61-400000000
- ‘EMAIL’ Email address
- ‘ABN’ Australian Business Number
- ‘ORG’ Organisation Name'
enum:
- PHONE
- EMAIL
- ABN
- ORG
bsb:
description: 'The BSB of the recipients bank. When using a BSB/Account number payments you
should verify that the bsb is valid.
'
type: string
pattern: ^[0-9]*$
minLength: 6
maxLength: 6
example: '012306'
accountNumber:
description: The payee's account number at the receiving financial institution.
type: string
pattern: ^[0-9]*$
minLength: 4
maxLength: 12
example: '12345678'
paymentAmount:
type: string
pattern: ^[0-9]+(\.[0-9]{2})$
description: Amount in AUD to be paid to the Payee
example: '101.95'
paymentDescription:
description: Description of this payment. Will appear as the payment description in the
Payee's online banking and bank statement.
type: string
minLength: 5
maxLength: 280
example: Payment for wages August 2020.
paymentReference:
type: string
maxLength: 35
description: 'A reference to the payee so that they can easily identify the payer or purpose
of the transaction
'
example: ec6507a4-7f2c-4f41-b3b8-a989c222648d
ultimatePayerName:
description: "The name of the ultimate payer. Lets you control the Payer description (visible\
\ to the payee) on the \npayment:\n- If not populated, then your business name will appear\
\ i.e. \"My business name\".\n- If populated, then the ultimate payer name will appear\
\ instead.\n"
type: string
pattern: ^[a-zA-Z0-9\-_ ]*$
minLength: 1
maxLength: 140
example: Mr John Smith or ABC Corp Pty Ltd
paymentNotification:
description: Definition of the endpoint used to notify about payment updates.
type: object
additionalProperties: false
required:
- paymentNotificationAuthorizationHeaderValue
- paymentNotificationEndpointUrl
properties:
paymentNotificationEndpointUrl:
description: 'An internet accessible url which Azupay will invoke when the status of
a Payment has reached "COMPLETE" status. The call will be done using the HTTP POST
method. The endpoint exposed by the client must be TLS 1.2 and the server certificate
must be issued by a well known commercial certificate authority and that self-signed
or internally signed certs are not acceptable.
'
type: string
format: url
paymentNotificationAuthorizationHeaderValue:
description: The string that Azupay will put into the Authorization request header when
making the payment notification call.
type: string
metaData:
type: object
additionalProperties: true
description: An object containing metaData field about the payment
PaymentSearchObj:
type: object
properties:
PaymentSearch:
type: object
properties:
clientPaymentId:
type: string
pattern: ^[a-zA-Z0-9\-_]*$
minLength: 5
maxLength: 100
description: Unique Id for the payment created by the merchant system
example: c8ec39dc-2a70-4440-bc92-0e8f1b263d8f
fromDate:
$ref: '#/components/schemas/fromDateUTC'
toDate:
$ref: '#/components/schemas/toDateUTC'
additionalProperties: false
PaymentSearchResponseObj:
type: object
allOf:
- $ref: '#/components/schemas/PaymentObj'
- $ref: '#/components/schemas/PaymentStatusObj'
PaymentStatusObj:
type: object
additionalProperties: false
required:
- PaymentStatus
properties:
PaymentStatus:
type: object
required:
- paymentId
- status
- createdDatetime
properties:
paymentId:
type: string
description: 'An identifier generated by Azupay. Used to reference the object in subsequent
operations such as getPayment.
'
example: K+9p4EE0rJnMtomRfWKWEDRh82BnAboHP2KwgIPyEIA=
readOnly: true
status:
type: string
description: Status of the requested payment.
readOnly: true
enum:
- CREATED
- SETTLED
- FAILED
- PENDING
- RETURNED
createdDatetime:
type: string
format: date-time
description: Timestamp when the payment request was created.
readOnly: true
settlementDatetime:
type: string
format: date-time
description: Timestamp when the payment was settled. Only if `status=SETTLED`.
readOnly: true
completedDatetime:
type: string
format: date-time
description: 'Timestamp when the payment was processed by Azupay. Only for `status` different
than `CREATED`.
'
readOnly: true
failureReason:
type: string
description: A reason code for a payment that is in `status=FAILED`.
example: AG01
readOnly: true
returnedReason:
type: string
description: A reason code for a payment that is in `status=RETURNED`.
example: AG01
readOnly: true
returnedDatetime:
type: string
format: date-time
description: Timestamp when the payment was returned. Only if `status=RETURNED`.
readOnly: true
currentBalance:
type: number
description: 'The liquidity balance of the your account with Azupay. This balance is the
funds remaining in your account after the amount for this payment has been deducted.
It is approximate only as other payments processed in parallel will also have altered
the available liquidity.
'
example: 31050.95
readOnly: true
nppTransactionId:
description: The identifier of the transaction in the NPP network. This is an identifier
visible to the receiving bank.
type: string
readOnly: true
sentViaDE:
description: This field is set to true when the payment was sent via the direct entry (DE)
network. When true, this payment may take between 3 and 5 business days to settle.
type: boolean
readOnly: true
fromDateUTC:
type: string
pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
description: The report date in ISO date/time string format in UTC
example: '2021-10-18T02:32:30.693Z'
toDateUTC:
type: string
pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
description: The report date in ISO date/time string format in UTC
example: '2021-10-18T02:32:30.693Z'
securitySchemes:
SecretKey:
description: 'The secret key is used to access restricted functions and should be stored
securely in your system. It is required for operations which may result in
additional charges to you as a merchant. Please protect the key by storing
it encrypted granting access only to a limited set of users and applications
requiring its use.
'
in: header
name: Authorization
type: apiKey
DistributableKey:
description: 'The distributable key has limited access and may be exposed publicly to
your payers.
'
in: header
name: Authorization
type: apiKey