Azupay Payment Agreement API

openapi: 3.2.0
info:
  title: Azupay Payment Agreement 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 Agreement
  x-displayName: Payment Agreement
  description: 'This API allows you to request Payments using mandates.

    '
paths:
  /paymentAgreement:
    post:
      security:
      - SecretKey: []
      tags:
      - Payment Agreement
      summary: Create a Payment Agreement
      description: Create a Payment Agreement
      operationId: createPaymentAgreement
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentAgreementObj'
      responses:
        '201':
          description: Payment Agreement Created
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaymentAgreementObj'
                - $ref: '#/components/schemas/PaymentAgreementStatusObj'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayToErrorModel'
              examples:
                contentTypeError:
                  value:
                    message: Content-Type request header must be application/json
                missingPayerDetailsError:
                  value:
                    message: '[object must contain either (["payIDDetails"]) or (["bankAccountDetails"])]

                      '
                extraPayerDetailsError:
                  value:
                    message: '[object must not contain both (["payIDDetails"]) and (["bankAccountDetails"])]

                      '
                missingAgreementDetailsError:
                  value:
                    message: '[object must contain either (["variableAgreementDetails"]) or (["fixedAgreementDetails"]) or  ([balloonAgreementDetails"]) or (["usageBasedAgreementDetails"])

                      '
                extraAgreementDetailsError:
                  value:
                    message: '[object must contain only one of (["variableAgreementDetails"]) or (["fixedAgreementDetails"]) or  ([balloonAgreementDetails"]) or (["usageBasedAgreementDetails"])

                      '
                startDateError:
                  value:
                    message: Start date must be today or future dated
                lastPaymentDateError:
                  value:
                    message: 'Last payment date must be equal to or after start date'': ''End date must be equal to or after start date

                      '
                clientIdMismatchError:
                  value:
                    message: 'ClientId mismatch: Expecting ...'
                invalidRequestBody:
                  value:
                    message: An invalid request body was supplied
                invalidBecsUserId:
                  value:
                    message: The BECS User ID is invalid
                invalidDdrMigrationRequest:
                  value:
                    message: Invalid DDR migration request. Both BECS User ID and PayID have been provided
        '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
      callbacks:
        PaymentAgreementStatusEvent:
          '{$request.body#/PaymentAgreement/paymentAgreementNotification/endpointURL}':
            post:
              summary: PaymentAgreementStatus.status Event
              description: 'If the merchant specifies values for the

                `PaymentAgreement/paymentAgreementNotification` object during the **Create a Payment Agreement**

                invocation, then a notification will be sent to the merchant system when it''s status has changed.


                The event will use `paymentAgreementNotification.endpointURL` as endpoint and

                `paymentAgreementNotification.authorizationHeader` as `Authorization` header.

                We **strongly** recommend to use a different value for `authorizationHeader`

                on each payment request to increase the level of security.


                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.


                The merchant system can correlate the event message using either the

                `PaymentAgreement.clientTransactionId` provided on the original request or the

                `PaymentAgreementStatus.paymentAgreementId` provided in the response of the original request.

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

                  {$request.body#/PaymentAgreement/paymentAgreementNotification/authorizationHeader}

                  '
                schema:
                  type: string
                required: true
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      allOf:
                      - $ref: '#/components/schemas/PaymentAgreementObj'
                      - $ref: '#/components/schemas/PaymentAgreementStatusObj'
              responses:
                '200':
                  description: The merchant's server should return this code
  /paymentAgreement/amendment:
    post:
      security:
      - SecretKey: []
      tags:
      - Payment Agreement
      summary: Amend a Payment Agreement
      description: Amend a Payment Agreement
      operationId: createPaymentAgreementAmendment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentAgreementAmendmentObj'
      responses:
        '201':
          description: Payment Agreement Amendment Submitted Successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaymentAgreementAmendmentObj'
                - $ref: '#/components/schemas/PaymentAgreementAmendmentStatusObj'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayToErrorModel'
              examples:
                contentTypeError:
                  value:
                    message: Content-Type request header must be application/json
                missingPayerDetailsError:
                  value:
                    message: '[object must not contain both (["payIDDetails"]) and (["bankAccountDetails"])]

                      '
                extraPayerDetailsError:
                  value:
                    message: '[object must contain either (["payIDDetails"]) or (["bankAccountDetails"])]

                      '
                missingAgreementDetailsError:
                  value:
                    message: '[object must contain either (["variableAgreementDetails"]) or (["fixedAgreementDetails"]) or  ([balloonAgreementDetails"]) or (["usageBasedAgreementDetails"])

                      '
                extraAgreementDetailsError:
                  value:
                    message: '[object must contain only one of (["variableAgreementDetails"]) or (["fixedAgreementDetails"]) or  ([balloonAgreementDetails"]) or (["usageBasedAgreementDetails"])

                      '
                startDateError:
                  value:
                    message: Start date must be today or future dated
                lastPaymentDateError:
                  value:
                    message: 'Last payment date must be equal to or after start date'': ''End date must be equal to or after start date

                      '
                frequencyError:
                  value:
                    message: '[object has missing required properties (["frequency"])]

                      '
                invalidRequestBody:
                  value:
                    message: An invalid request body was supplied
        '401':
          description: Invalid Authorization header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
              examples:
                invalidStateError:
                  value:
                    message: Payment Agreement must be in an ACTIVE or SUSPENDED state.
                unauthorizedError:
                  value:
                    message: User is not authorized to access this resource with an explicit deny
        '404':
          description: Payment Agreement Not Found
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorModel'
                - properties:
                    message:
                      example: Payment Agreement Not Found
        '409':
          description: Amend Payment Agreement already in progress.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorModel'
                - properties:
                    message:
                      example: Amend Payment Agreement already in progress.
      callbacks:
        PaymentAgreementAmendmentStatusEvent:
          '{$request.body#/PaymentAgreementAmendment/paymentAgreementAmendmentNotification/endpointURL}':
            post:
              summary: PaymentAgreementAmendmentStatus.amendmentStatus Event
              description: 'If the merchant specifies values for the

                `PaymentAgreementAmendment/paymentAgreementAmendmentNotification` object during the

                **Amend a Payment Agreement** invocation,

                then a notification will be sent to the merchant system when it''s status has changed.


                The event will use `paymentAgreementAmendmentNotification.endpointURL` as endpoint and

                `paymentAgreementAmendmentNotification.authorizationHeader` as `Authorization` header.

                We **strongly** recommend to use a different value for `authorizationHeader`

                on each payment request to increase the level of security.


                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.


                The merchant system can correlate the event message using either the

                `PaymentAgreementAmendment.clientTransactionId` provided on the original request or the

                `PaymentAgreementAmendmentStatus.paymentAgreementAmendmentId` provided in the response of the original

                request.

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

                  {$request.body#/PaymentAgreementAmendment/paymentAgreementAmendmentNotification/authorizationHeader}

                  '
                schema:
                  type: string
                required: true
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      allOf:
                      - $ref: '#/components/schemas/PaymentAgreementAmendmentObj'
                      - $ref: '#/components/schemas/PaymentAgreementAmendmentStatusObj'
              responses:
                '200':
                  description: The merchant's server should return this code
  /paymentAgreement/changeStatus:
    post:
      security:
      - SecretKey: []
      tags:
      - Payment Agreement
      summary: Change Status of a Payment Agreement
      description: Change the status of a Payment Agreement
      operationId: changeStatusOfPaymentAgreement
      parameters:
      - in: query
        name: id
        required: true
        description: ID of the payment agreement to change
        schema:
          type: string
      - in: query
        name: status
        required: true
        description: New status of the payment agreement
        schema:
          type: string
          enum:
          - CANCELLED
          - SUSPENDED
          - ACTIVE
      responses:
        '200':
          description: Payment Agreement Status Changed Successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaymentAgreementObj'
                - $ref: '#/components/schemas/PaymentAgreementStatusObj'
        '201':
          description: Payment Agreement Change Status Submitted Successfully
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaymentAgreementObj'
                - $ref: '#/components/schemas/PaymentAgreementStatusObj'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
              examples:
                contentTypeError:
                  value:
                    message: Content-Type request header must be application/json
                requestStatusError:
                  value:
                    message: 'instance value ... not found in enum (possible values: ["CANCELLED","SUSPENDED","ACTIVE"])'
        '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: Payment Agreement Not Found
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorModel'
                - properties:
                    message:
                      example: Payment agreement record does not exist
        '409':
          description: Change Status Already In Progress
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorModel'
                - properties:
                    message:
                      example: Payment Agreement Change Status already in progress.
        '412':
          description: Invalid Status in Change Status Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
              examples:
                suspendedStateError:
                  value:
                    message: Payment agreement must be in a SUSPENDED state
                activeStateError:
                  value:
                    message: Payment agreement must be in an ACTIVE state
                activeOrSuspendedStateError:
                  value:
                    message: Payment agreement must be in an ACTIVE or SUSPENDED state
  /paymentAgreement/search:
    post:
      security:
      - SecretKey: []
      tags:
      - Payment Agreement
      summary: Search for Payment Agreements.
      description: 'Search for Payment Agreements

        '
      operationId: searchPaymentAgreement
      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/PaymentAgreementSearchObj'
      responses:
        '200':
          description: The requested page of payment agreements
          content:
            application/json:
              schema:
                type: object
                required:
                - records
                properties:
                  nextPageId:
                    $ref: '#/components/schemas/nextPageIdResponse'
                  recordCount:
                    $ref: '#/components/schemas/recordCount'
                  records:
                    type: array
                    description: The result from the search
                    items:
                      $ref: '#/components/schemas/PaymentAgreementSearchResponseObj'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
              examples:
                contentTypeError:
                  value:
                    message: Content-Type request header must be application/json
                mixedFieldsError:
                  value:
                    message: '[object can''t include dates - (["toDate"]), (["fromDate"]) and (["paymentAgreementId"]) in the same request]

                      '
                validDateRangeError:
                  value:
                    message: 'fromDate should be before or equal to toDate

                      '
                missingToDateError:
                  value:
                    message: '[object must contain (["toDate"]) if (["fromDate"]) is present]

                      '
                missingFromDateError:
                  value:
                    message: '[object must contain (["fromDate"]) if (["toDate"]) is present]

                      '
                idTooShortError:
                  value:
                    message: '[string "" is too short (length: 0, required minimum: 1)]

                      '
                idTooLongError:
                  value:
                    message: '[string "...more than 40 chars..." is too long (length: 41, maximum allowed: 40)]

                      '
                invalidFromDateError:
                  value:
                    message: '[ECMA 262 regex "^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$" does not match input string "from-date"]

                      '
                invalidToDateError:
                  value:
                    message: '[ECMA 262 regex "^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$" does not match input string "to-date"]

                      '
                extraFieldsError:
                  value:
                    message: '[object instance has properties which are not allowed by the schema: ["..."]]

                      '
        '401':
          description: Invalid Authorization header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
  /paymentAgreement/{paymentAgreementId}/scheduler:
    post:
      security:
      - SecretKey: []
      tags:
      - Payment Agreement
      summary: Create or amend a Payment Scheduler
      description: 'Creates a scheduler against an active payment agreement, or amends the existing one.

        Upsert keyed on paymentAgreementId. Amendments require the current version.

        '
      operationId: createOrUpdatePaymentScheduler
      parameters:
      - name: paymentAgreementId
        in: path
        required: true
        description: The payment agreement the scheduler is attached to
        schema:
          type: string
          minLength: 1
          maxLength: 50
          example: a8c1f2de9b4c47e1bf0a3d5e6f70811a
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentSchedulerRequest'
      responses:
        '200':
          description: Scheduler amended
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentSchedulerResponse'
        '201':
          description: Scheduler created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentSchedulerResponse'
        '400':
          description: Validation failed (see AZP3.x / AZP4.x failure codes).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '401':
          description: Invalid Authorization header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '403':
          description: Caller not authorised, or agreement not in ACTIVE state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '404':
          description: Payment agreement not found for this client.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '409':
          description: Version mismatch — supplied version does not match current scheduler version.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
    get:
      security:
      - SecretKey: []
      tags:
      - Payment Agreement
      summary: Retrieve a Payment Scheduler
      description: 'Returns the scheduler for the given payment agreement, with its current state.

        '
      operationId: getPaymentScheduler
      parameters:
      - name: paymentAgreementId
        in: path
        required: true
        description: The payment agreement the scheduler is attached to
        schema:
          type: string
          minLength: 1
          maxLength: 50
          example: a8c1f2de9b4c47e1bf0a3d5e6f70811a
      responses:
        '200':
          description: Scheduler found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentSchedulerResponse'
        '401':
          description: Invalid Authorization header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '403':
          description: Scheduler does not belong to caller's tenant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
        '404':
          description: No scheduler for that payment agreement.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
components:
  schemas:
    endDate:
      type: string
      description: A date in the calendar year expressed in this format YYYY-MM-DD. This date would be in Australia/Sydney timezone
      pattern: ^(?:[1-9]\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)$
      example: '2022-12-01'
    paymentAgreementIdForSearch:
      type: string
      minLength: 1
      maxLength: 40
      description: ID of the payment agreement being searched.
      example: K+9p4EE0rJnMtomRfWKWE2BnAboHP2KwgIPyEIA=
    PaymentSchedulerResponse:
      type: object
      description: 'Standard scheduler response: the resource plus its server-managed state.'
      required:
      - PaymentScheduler
      - PaymentSchedulerStatus
      additionalProperties: false
      properties:
        PaymentScheduler:
          $ref: '#/components/schemas/PaymentScheduler'
        PaymentSchedulerStatus:
          $ref: '#/components/schemas/PaymentSchedulerStatus'
    PaymentAgreementAmendmentObj:
      type: object
      required:
      - PaymentAgreementAmendment
      properties:
        PaymentAgreementAmendment:
          type: object
          required:
          - paymentAgreementId
          - clientTransactionId
          properties:
            clientTransactionId:
              $ref: '#/components/schemas/ClientTransactionIdObj'
            paymentAgreementId:
              type: string
              description: ID of the payment agreement being amended
              example: K+9p4EE0rJnMtomRfWKWEDRh82BnAboHP2KwgIPyEIA=
            commonDetails:
              type: object
              description: "Details of a Payment Agreement that can be amended without approval from the payer. Cannot be provided at the same time with \n`agreementDetails`. This feature is not enabled by default. Please contact support to allow amendment of these details.\n"
              properties:
                description:
                  $ref: '#/components/schemas/agreementDescription'
                payeeName:
                  $ref: '#/components/schemas/agreementPayeeName'
            agreementDetails:
              type: object
              description: 'Agreement Details that need approval from the payer. Cannot be provided at the same time with `commonDetails`.

                '
              properties:
                usageBasedAgreementDetails:
                  type: object
                  description: Usage Based Agreement Details for Amendment
                  properties:
                    endDate:
                      $ref: '#/components/schemas/endDate'
                    maximumAmount:
                      $ref: '#/components/schemas/maximumAmount'
                    frequency:
                      $ref: '#/components/schemas/frequency'
                variableAgreementDetails:
                  type: object
                  description: Variable Agreement Details for Amendment
                  properties:
                    endDate:
                      $ref: '#/components/schemas/endDate'
                    maximumAmount:
                      $ref: '#/components/schemas/maximumAmount'
                    frequency:
                      $ref: '#/components/schemas/frequency'
                fixedAgreementDetails:
                  type: object
                  description: Fixed Agreement Details for Amendment
                  properties:
                    endDate:
                      $ref: '#/components/schemas/endDate'
                    firstPaymentAmount:
                      $ref: '#/components/schemas/firstPaymentAmount'
                    amount:
                      $ref: '#/components/schemas/amount'
                    frequency:
                      $ref: '#/components/schemas/frequency'
                balloonAgreementDetails:
                  type: object
                  description: Balloon Agreement Details for Amendment
                  properties:
                    lastPaymentDate:
                      $ref: '#/components/schemas/lastPaymentDate'
                    lastPaymentAmount:
                      $ref: '#/components/schemas/lastPaymentAmount'
                    amount:
                      $ref: '#/components/schemas/amount'
                    frequency:
                      $ref: '#/components/schemas/frequency'
            paymentAgreementAmendmentNotification:
              $ref: '#/components/schemas/NotificationObj'
            additionalDetails:
              $ref: '#/components/schemas/AdditionalDetailsObj'
          additionalProperties: false
      additionalProperties: false
    PaymentSchedulerRequest:
      type: object
      description: Create/amend request envelope.
      required:
      - PaymentScheduler
      additionalProperties: false
      properties:
        PaymentScheduler:
          $ref: '#/components/schemas/PaymentScheduler'
    agreementDescription:
      type: string
      minLength: 5
      maxLength: 140
      pattern: ^[ -~]*$
      description: Description of the Payment Agreement visible to the payer.
    PayerDetailsObj:
      type: object
      description: 'Provide either `payIDDetails` or `bankAccountDetails`

        '
      additionalProperties: false
      properties:
        name:
          type: string
          description: The payer's name
          minLength: 1
          maxLength: 100
          example: Jane Smith
          pattern: ^[!-~]+( [!-~]+)*$
        type:
          type: string
          description: Whether payer is a person or organisation. Defaults to 'Person'.
          enum:
          - Person
          - Organisation
        payIDDetails:
          description: PayID Details
          type: object
          required:
          - payID
          - payIDType
          properties:
            payID:
              $ref: '#/components/schemas/PayIDObj'
            payIDType:
              type: string
              example: EMAIL
              description: 'PayID Type. Valid Values:

                - ''PHONE’ Can be a mobile phone number or landline with area code

                - ‘EMAIL’ Email address

                - ‘ABN’ Australian Business Number

                - ‘ORG’ Organisation Name'
              enum:
              - PHONE
              - EMAIL
              - ABN
              - ORG
        bankAccountDetails:
          description: Bank Account Details
          type: object
          additionalProperties: false
          required:
          - bsb
          - accountNumber
          properties:
            bsb:
              $ref: '#/components/schemas/BsbObj'
            accountNumber:
              $ref: '#/components/schemas/AccountNumberObj'
    recordCount:
      type: number
      description: The number of records that were retrieved.
    authorizationHeader:
      type: string
      description: 'The string that Azupay will put into the Authorization request header when calling the Callback url.


        Will be obfuscated (shown as ****) in API responses.

        '
      example: SECRET
    PayToErrorModel:
      type: object
      required:
      - message
      properties:
        message:
          type: string
        details:
          type: object
          description: 'An object containing details of the error

            '
          properties:
            failureCode:
              type: string
       

# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/azupay/refs/heads/main/openapi/azupay-payment-agreement-api-openapi.yml