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