Azupay
Azupay Clients & API Key Management API

Manage the platform configuration for an Azupay integration. Create, replace, and disable sub-clients; provision, retrieve, and update API keys for sub merchants; enable and read OAuth 2.0 configuration; and manage low-balance alert thresholds and recipients. Several operations are enabled per client by Azupay.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.1
info:
  title: Azupay Configuration 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: API Keys
  description: 'Manage API keys for your clients.

    '
- name: Clients
  description: 'Would let you manage clients

    '
paths:
  /client/{clientId}/apiKeys:
    post:
      security:
      - SecretKey: []
      tags:
      - API Keys
      summary: Create API keys for Sub Merchants
      description: Create API keys
      operationId: apiKeysProvision
      parameters:
      - name: clientId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/SubClientIdObj'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/apiKeysProvisionObj'
      responses:
        '201':
          description: API key creation
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/apiKeysProvisionResponseObj'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '401':
          description: Invalid Authorization header
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorModel'
                - properties:
                    message:
                      example: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorModel'
                - properties:
                    message:
                      example: User is not authorized to access this resource with an explicit deny
        '404':
          description: Client ID not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
    get:
      parameters:
      - name: clientId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/SubClientIdObj'
      security:
      - SecretKey: []
      tags:
      - API Keys
      summary: Get API keys for Sub Merchants
      description: Get API keys
      operationId: getApiKeys
      responses:
        '200':
          description: API keys record
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/GetApiKeysResponseObj'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '401':
          description: Invalid Authorization header
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorModel'
                - properties:
                    message:
                      example: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorModel'
                - properties:
                    message:
                      example: User is not authorized to access this resource with an explicit deny
        '404':
          description: Client ID not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
  /client/{clientId}/apiKeys/{apiKeyId}:
    get:
      parameters:
      - name: clientId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/SubClientIdObj'
      - name: apiKeyId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ApiKeyIdObj'
      security:
      - SecretKey: []
      tags:
      - API Keys
      summary: Gets an API key based on the API key ID.
      description: Get API key
      operationId: getApiKey
      responses:
        '200':
          description: API key record
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/GetApiKeyResponseObj'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '401':
          description: Invalid Authorization header
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorModel'
                - properties:
                    message:
                      example: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorModel'
                - properties:
                    message:
                      example: User is not authorized to access this resource with an explicit deny
        '404':
          description: Client ID not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
    patch:
      security:
      - SecretKey: []
      tags:
      - API Keys
      parameters:
      - name: clientId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/SubClientIdObj'
      - name: apiKeyId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ApiKeyIdObj'
      summary: Update API keys for Sub Merchants
      description: Update API keys
      operationId: updateApiKeys
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeyUpdateObj'
      responses:
        '204':
          description: API key updated
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '401':
          description: Invalid Authorization header
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorModel'
                - properties:
                    message:
                      example: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorModel'
                - properties:
                    message:
                      example: User is not authorized to access this resource with an explicit deny
        '404':
          description: Client ID not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
  /client/{clientId}/oauth2:
    post:
      security:
      - SecretKey: []
      tags:
      - API Keys
      summary: Enable OAuth2 for a client
      description: Enable OAuth2 for a client
      operationId: enableClientOAuth2
      parameters:
      - name: clientId
        in: path
        required: true
        description: The Azupay sub-client ID whose OAuth2 configuration is being retrieved.
        schema:
          $ref: '#/components/schemas/SubClientIdObj'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              description: Optional configuration when enabling OAuth2. Currently has no fields.
      responses:
        '201':
          description: OAuth2 has been enabled and credentials issued.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/EnableOAuth2ResponseObj'
        '400':
          description: Invalid request. The most common cause is that the client is not on the enterprise
            plan or clientId path parameter is not matching the Authorization header and is therefore
            not allowed to enable OAuth2.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorModel'
                - properties:
                    message:
                      example: User is not authorized to access this resource with an explicit deny
    get:
      security:
      - SecretKey: []
      tags:
      - API Keys
      summary: Get OAuth2 configuration for a client
      description: Get OAuth2 configuration for a client
      operationId: getClientOAuth2
      parameters:
      - name: clientId
        in: path
        required: true
        description: The Azupay sub-client ID whose OAuth2 configuration is being retrieved.
        schema:
          $ref: '#/components/schemas/SubClientIdObj'
      responses:
        '200':
          description: The OAuth2 configuration for the client.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/GetOAuth2ResponseObj'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorModel'
                - properties:
                    message:
                      example: User is not authorized to access this resource with an explicit deny
        '404':
          description: OAuth2 is not enabled for this client, or the client does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
  /clients:
    post:
      operationId: createClient
      callbacks:
        SweepRequestEvent:
          '{client.sweepNotification.url}':
            post:
              summary: SweepRequest Status Event
              description: 'If the merchant specifies values for the

                `client.sweepNotification.url` object during the createClient invocation, then a notification

                will be sent to the merchant system when the funds have settled.


                The event will use `sweepNotification.url` as endpoint and

                `sweepNotification.authorizationHeader` as `Authorization` header.


                This 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 is
                implemented with

                idempotent behaviour always returning a `200 OK` response even after subsequent calls.


                If the target endpoint does not return HTTP `200`, azupay will retry the webhook call
                45 times with a 20 second delay.

                '
              parameters:
              - in: header
                name: Authorization
                description: 'The value will be what was specified in

                  {client/sweepNotification/authorizationHeader}

                  '
                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
        ClientEnabledEvent:
          '{client.clientManagementNotification.url}':
            post:
              summary: Client Enabled Status Event
              description: 'If the merchant specifies values for the

                `client.clientManagementNotification.url` object during the createClient invocation, then
                a notification

                will be sent to the merchant system when the created sub-merchant is enabled.


                The event will use `clientManagementNotification.url` as endpoint and

                `clientManagementNotification.authorizationHeader` as `Authorization` header.


                This 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 is
                implemented with

                idempotent behaviour always returning a `200 OK` response even after subsequent calls.


                If the target endpoint does not return HTTP `200`, azupay will retry the webhook call
                45 times with a 20 second delay.

                '
              parameters:
              - in: header
                name: Authorization
                description: 'The value will be what was specified in

                  {client/sweepNotification/authorizationHeader}

                  '
                schema:
                  type: string
                required: true
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      allOf:
                      - $ref: '#/components/schemas/ClientWebhookResponseObj'
              responses:
                '200':
                  description: The merchant's server should return this code
      tags:
      - Clients
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientObj'
      summary: Create or replace a client
      security:
      - SecretKey: []
      description: 'Create new sub-clients. Sub-clients are children of your own client (master-client).


        Duplicates can be prevented by using the same value in `clientTransactionId` in the request. It
        would also

        replace an existing client if the same `clientTransactionId` is provided in the request.


        This API is only available to some Azupay customers. Please contact us for more information.

        '
      responses:
        '201':
          description: The new Client has been created
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ClientObj'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorModel'
        '403':
          description: Not authorised
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorModel'
  /clients/{clientId}:
    delete:
      operationId: deleteClient
      tags:
      - Clients
      summary: Disable a sub-client
      description: 'Disable a sub-client. Sub-client is a child of your own client (master-client).


        This API is only available to some Azupay customers. Please contact us for more information.

        '
      security:
      - SecretKey: []
      parameters:
      - description: Client ID of sub-client to disable
        in: path
        name: clientId
        required: true
        schema:
          type: string
          example: e6828fe0-7ca0-46a1-9261-04f0f30deabd
      responses:
        '204':
          description: The sub-client was successfully disabled
        '400':
          description: Invalid Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
              examples:
                alreadyDisabledError:
                  value:
                    message: The sub-client already disabled
                    details:
                      failureCode: ERR0.01
                      failureReason: The sub-client already disabled
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
              examples:
                notAuthorizedError:
                  value:
                    message: User is not authorized to access this resource
                    details:
                      failureCode: ERR0.01
                      failureReason: User is not authorized to access this resource
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
              examples:
                notFoundError:
                  value:
                    message: The client can not be found
                    details:
                      failureCode: ERR0.01
                      failureReason: The client can not be found
  /clients/{clientId}/lowBalanceAlert/emailAddresses:
    get:
      operationId: getClientLowBalanceAlertEmailAddresses
      tags:
      - Clients
      security:
      - SecretKey: []
      parameters:
      - description: Client ID to get the email addresses
        in: path
        name: clientId
        required: true
        schema:
          type: string
          example: e6828fe0-7ca0-46a1-9261-04f0f30deabd
      responses:
        '200':
          description: The client configuration
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/LowBalanceEmailAddresses'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
              examples:
                notAuthorizedError:
                  value:
                    message: User is not authorized to access this resource
                    details:
                      failureCode: ERR0.01
                      failureReason: User is not authorized to access this resource
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
              examples:
                notFoundError:
                  value:
                    message: The client can not be found
                    details:
                      failureCode: ERR0.01
                      failureReason: The client can not be found
    put:
      operationId: updateClientLowBalanceAlertEmailAddresses
      tags:
      - Clients
      summary: Set email addresses to send the low balance alerts
      description: 'Set the email addresses to send the alerts when the balance goes lower than the specified
        limit.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetLowBalanceEmailAddresses'
      security:
      - SecretKey: []
      parameters:
      - description: Client ID to set the email addresses
        in: path
        name: clientId
        required: true
        schema:
          type: string
          example: e6828fe0-7ca0-46a1-9261-04f0f30deabd
      responses:
        '204':
          description: The email addresses were successfully updated
        '400':
          description: Invalid Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
              examples:
                alreadyDisabledError:
                  value:
                    message: Bad request
                    details:
                      failureCode: ERR0.01
                      failureReason: Wrong email addresses format
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
              examples:
                notAuthorizedError:
                  value:
                    message: User is not authorized to access this resource
                    details:
                      failureCode: ERR0.01
                      failureReason: User is not authorized to access this resource
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
              examples:
                notFoundError:
                  value:
                    message: The client can not be found
                    details:
                      failureCode: ERR0.01
                      failureReason: The client can not be found
  /clients/{clientId}/lowBalanceAlert/threshold:
    get:
      operationId: getClientLowBalanceAlertThreshold
      tags:
      - Clients
      security:
      - SecretKey: []
      parameters:
      - description: Client ID to get the balance threshold
        in: path
        name: clientId
        required: true
        schema:
          type: string
          example: e6828fe0-7ca0-46a1-9261-04f0f30deabd
      responses:
        '200':
          description: The client configuration
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/LowBalanceThreshold'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
              examples:
                notAuthorizedError:
                  value:
                    message: User is not authorized to access this resource
                    details:
                      failureCode: ERR0.01
                      failureReason: User is not authorized to access this resource
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
              examples:
                notFoundError:
                  value:
                    message: The client can not be found
                    details:
                      failureCode: ERR0.01
                      failureReason: The client can not be found
    put:
      operationId: updateClientLowBalanceAlertThreshold
      tags:
      - Clients
      summary: Set low balance threshold to trigger alerts
      description: 'Set low balance threshold to trigger alerts when the balance goes lower than the specified
        limit.

        When this happens, an email is sent to the specified recipients.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetLowBalanceThreshold'
      security:
      - SecretKey: []
      parameters:
      - description: Client ID to set the balance threshold
        in: path
        name: clientId
        required: true
        schema:
          type: string
          example: e6828fe0-7ca0-46a1-9261-04f0f30deabd
      responses:
        '204':
          description: The threshold was successfully updated
        '400':
          description: Invalid Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
              examples:
                alreadyDisabledError:
                  value:
                    message: Bad request
                    details:
                      failureCode: ERR0.01
                      failureReason: Wrong threshold format
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
              examples:
                notAuthorizedError:
                  value:
                    message: User is not authorized to access this resource
                    details:
                      failureCode: ERR0.01
                      failureReason: User is not authorized to access this resource
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
              examples:
                notFoundError:
                  value:
                    message: The client can not be found
                    details:
                      failureCode: ERR0.01
                      failureReason: The client can not be found
components:
  schemas:
    AdditionalTradingNamesObj:
      type: array
      minItems: 1
      maxItems: 20
      items:
        type: string
        maxLength: 140
        minLength: 1
        pattern: ^[a-zA-Z0-9\-_ ]*$
      example:
      - Trading Name
      - Trading Name Pty Ltd
      description: Additional trading names
    ApiKeyIdObj:
      type: string
      example: SECR
      description: The ID provided when the API Key was generated via the API or from the dashboard.
    ApiKeyUpdateObj:
      type: object
      description: 'Object used to update API key state (Active / Disabled).

        '
      additionalProperties: false
      minProperties: 1
      required:
      - enabled
      properties:
        enabled:
          type: boolean
          description: 'Indicates whether the API key is currently active. Set to `true` to enable the
            key, or `false` to disable it.

            '
          example: true
    ClientObj:
      type: object
      additionalProperties: false
      required:
      - client
      properties:
        client:
          type: object
          description: The client
          additionalProperties: false
          required:
          - clientTransactionId
          - legalName
          - defaultPaymentExpiryDuration
          - payIDDomains
          - abn
          - settlementAccountFullLegalName
          properties:
            id:
              type: string
              example: 731c04075258428730c3152a7904dda4
              readOnly: true
              description: 'The unique id for the new client. This client is created using the `clientTransactionId`
                so the client

                will be replaced if the same value is sent which will return the same value for `id`.


                It is recommended to record this id for later use.

                '
            clientTransactionId:
              type: string
              maxLength: 36
              example: 30597959-a853-44d4-bdab-54332bf7a98e
              description: 'This field is used to prevent the creation of duplicated clients in case of
                a message retry. It is

                recommended that a unique id (like uuid) is used for each client. If the same value is
                used a second time

                the client will be replaced.

                '
            legalName:
              type: string
              maxLength: 50
              minLength: 1
              example: Legal name
              description: 'The client legal name.

                '
            tradingName:
              type: string
              maxLength: 50
              minLength: 1
              pattern: ^[a-zA-Z0-9\-_ ]*$
              example: Legal name
              description: 'The client trading name.

                '
            additionalTradingNames:
              $ref: '#/components/schemas/AdditionalTradingNamesObj'
            defaultPaymentExpiryDuration:
              type: number
              minimum: 60
              example: 3600
              description: 'The default expiry duration of a `PaymentRequest` in **minutes**.

                '
            payIDDomains:
              $ref: '#/components/schemas/PayIDDomainsObj'
            abn:
              type: string
              minLength: 11
              maxLength: 11
              pattern: ^\d*$
              example: '12345678901'
              description: 'The Australian Business Number for the client.

                '
            settlementAccountBSB:
              type: string
              minLength: 6
              maxLength: 6
              pattern: ^\d*$
              example: '123456'
              description: 'The BSB of the account used to sweep collected funds for this client.


                It has to be provided if `settlementAccountNumber` is provided.

                '
            settlementAccountNumber:
              type: string
              minLength: 5
              maxLength: 9
              pattern: ^\d*$
              example: '123555555'
              description: 'The Account Number (without the BSB) used to sweep collected funds for this
                client. By default funds

                will be swept every day.


                It has to be provided if `settlementAccountBSB` is provided.

                '
            settlementPayID:
              type: string
              format: email
              example: myaccount@example.com
              description: 'Fill if the client funds are to be swept to a PayID instead of a BSB and Account
                Number. If provided both

                `settlementAccountBSB` and `settlementAccountNumber` will be ignored and this will be
                used.

                '
            settlementAccountFullLegalName:
              type: string
              maxLength: 50
              minLength: 1
              example: Account legal name
              description: 'The legal name that is attached to the client''s account.

                '
            sweepNotification:
              type: object
              additionalProperties: false
              description: 'Populate this object if you would like Azupay to send a sweep notification
                webhook when Azupay settles

                to your account.

                '
              required:
              - authorizationHeader
              - url
              properties:
                url:
                  type: string
                  pattern: ^https://
                  description: 'Provide a https endpoint accessible over the internet

                    '
                authorizationHeader:
                  type: string
                  description: 'The value you want populated in the Authorization request header when
                    Azupay calls the endpoint specified in the `url` field.

                    '
            clientManagementNotification:
              type: object
              description: 'Populate this object if you would like Azupay to send a notification webhook
                when the sub-merchant account is enabled.

                '
              additionalProperties: false
              required:
              - url
              - authorizationHeader
              properties:
                url:
                  type: string
                  pattern: ^https://
                  description: 'Provide a https endpoint accessible over the internet

                    '
                authorizationHeader:
                  type: string
                  description: 'The value you want populated in the Authorization request header when
                    Azupay calls the endpoint specified in the `url` field.

                    '
            topUpPayId:
              type: string
              format: email
              example: topup1234@example.com
              description: 'The payID that can be used to topup the balance for the newly created client.
                This 

# --- truncated at 32 KB (61 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/azupay/refs/heads/main/openapi/azupay-configuration.yml
Azupay Clients & API Key Management API

Documentation

Specifications

Other Resources

OpenAPI Specification
