openapi: 3.0.1
info:
  title: Azupay Reports & Balance 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: Billing and Transaction Reports
  description: 'Fetch transaction, billing and other reports.

    '
- name: Current Balances
  description: 'Obtain current dollar balances for Azupay products

    '
paths:
  /balance:
    get:
      operationId: getBalance
      security:
      - SecretKey: []
      tags:
      - Current Balances
      summary: Get current balance
      description: 'Returns balance of your Azupay account.

        '
      parameters:
      - in: query
        name: timestamp
        required: false
        schema:
          type: string
        description: "An optional parameter can be supplied to retrieve the account balance at a specified\
          \ point in time. \nIn ISO date/time string format in UTC.\n"
        example: '2024-11-04T03:16:53.350Z'
      responses:
        '200':
          description: The balance object
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/BalanceObj'
        '401':
          description: Invalid Authorization header
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorModel'
  /report:
    get:
      operationId: getReport
      security:
      - SecretKey: []
      tags:
      - Billing and Transaction Reports
      summary: Get Reports
      description: "Provides a list of reports that can be passed onto GET /report/download API endpoint.\
        \ You can supply \n`month + timezone` query parameters OR you can supply `fromDate + toDate`.\
        \ The former provides you a list of all \nreports automatically generated by azupay whilst the\
        \ latter provides you with a report for the date range \nspecified.\n\nBecause `fromDate` and\
        \ `toDate` contain special HTML entities (i.e. `:` and `+`), they must be encoded.\nExample: `2022-06-02T12:11:00.999+0530`\
        \ must be supplied as `2022-06-02T12%3A11%3A00.999%2B0530`\n"
      parameters:
      - description: 'Your clientId

          '
        in: query
        name: clientId
        required: true
        schema:
          type: string
      - description: 'The year and month

          '
        in: query
        name: month
        required: false
        schema:
          type: string
          pattern: ^\d{4}-\d{2}$
          example: 2020-01
      - description: 'The fromDate in ISO8601 and encoded.


          e.g. `2022-06-02T12%3A11%3A00.999%2B0530` instead of `2022-06-02T12:11:00.999+0530`

          '
        in: query
        name: fromDate
        required: false
        schema:
          type: string
      - description: 'The toDate in ISO8601 and encoded.


          e.g. `2022-07-02T12%3A11%3A00.999%2B0530` instead of `2022-07-02T12:11:00.999+0530`

          '
        in: query
        name: toDate
        required: false
        schema:
          type: string
      - description: 'The timezone to apply on date/time stamps. Currently only `Australia/Sydney` supported.

          '
        in: query
        name: timezone
        required: false
        schema:
          type: string
          enum:
          - Australia/Sydney
      responses:
        '200':
          description: The list of reports available for the specified clientId and month
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ReportListModel'
        '403':
          description: Not authorised to return reports for given clientId
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorModel'
        '404':
          description: No reports were found for given clientId and month values
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorModel'
  /report/download:
    get:
      operationId: downloadReport
      tags:
      - Billing and Transaction Reports
      summary: Get Report download Url
      description: Gets a time limited link to download the specified report
      parameters:
      - description: 'Your clientId

          '
        in: query
        name: clientId
        required: true
        schema:
          type: string
      - description: 'The reportId returned from the call to `/report` operation

          '
        in: query
        name: reportId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The report link object
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ReportLinkModel'
        '403':
          description: Not authorised to retrieve a link for the specified report
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorModel'
        '404':
          description: The specified reportId was not found
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorModel'
      security:
      - SecretKey: []
components:
  schemas:
    BalanceObj:
      type: object
      properties:
        balance:
          type: number
          description: 'The balance of your Azupay account in AUD.

            '
    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
    ReportLinkModel:
      type: object
      properties:
        reportUrl:
          type: string
      required:
      - reportUrl
    ReportListModel:
      type: object
      properties:
        month:
          type: string
          pattern: ^\d{4}-\d{2}$
          example: 2020-01
        reports:
          type: array
          items:
            type: object
            properties:
              reportId:
                type: string
              type:
                type: string
                enum:
                - MT940
                - Transaction Report
                - Billing Report
              fromDate:
                $ref: '#/components/schemas/fromDateWithTZO'
              toDate:
                $ref: '#/components/schemas/toDateWithTZO'
              clientId:
                type: string
              moreResultsPossible:
                type: boolean
                description: "Optional field. Only applicable if `startDate` and `endDate` are supplied.\n\
                  \n**true** if the provided range (`startDate` - `endDate`) resulted in report's result-set\
                  \ that \nexceed the allowed maximum records (10,000)\n\nWhen it is true, our recommendation\
                  \ is to narrow the range (`startDate` - `endDate`) and retry\n"
            required:
            - reportId
            - type
            - fromDate
            - toDate
            - clientId
    fromDateWithTZO:
      type: string
      pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}[+\-]\d{2}:\d{2}$
      description: The report date in ISO date/time string format with timezone offset
      example: '2020-01-01T00:00:00.004+11:00'
    toDateWithTZO:
      type: string
      pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}[+\-]\d{2}:\d{2}$
      description: The report date in ISO date/time string format with timezone offset
      example: '2020-01-01T00:00:00.004+11:00'
  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