Azupay Payment API

openapi: 3.2.0
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
      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:
    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
    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
    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
    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'
    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
    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