Azupay PaymentAgreement & Initiation API (AzupayTo / PayTo)

openapi: 3.0.1
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.

    '
- name: Payment Agreement Request
  x-displayName: Payment Agreement Request
  description: "This API generates a link to a one-time UX experience that enables payers to create and\
    \ approve a PayTo Agreement, \nfacilitating the setup of recurring payments through the Payment Initiation\
    \ API or batch processing. \nIt is ideal for subscription-based products, such as monthly fees.\n"
- name: Payment Initiation
  x-displayName: Payment Initiation
  description: 'This API allows you to initiate 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'
  /paymentAgreementRequest:
    post:
      security:
      - SecretKey: []
      tags:
      - Payment Agreement Request
      summary: Create a Payment Agreement Request
      description: Create a Payment Agreement Request
      operationId: createPaymentAgreementRequest
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentAgreementRequestObj'
      responses:
        '201':
          description: Payment Agreement Request Created
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaymentAgreementRequestObj'
                - $ref: '#/components/schemas/PaymentAgreementRequestStatusObj'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayToErrorModel'
              examples:
                contentTypeError:
                  value:
                    message: Content-Type request header must be application/json
                missingTransactionId:
                  value:
                    message: '[object has missing required properties (["clientTransactionId"])]'
                startDateError:
                  value:
                    message: Start date must be today or future dated
                endDateError:
                  value:
                    message: End date must be equal to or after start date
                suggestedPayerPayIDError:
                  value:
                    message: '[suggestedPayerPayID] format is incorrect'
        '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
  /paymentInitiation:
    get:
      operationId: getPaymentInitiation
      security:
      - SecretKey: []
      tags:
      - Payment Initiation
      summary: Get a Payment Initiation
      description: 'Retrieves an existing Payment Initiation (PayTo Transaction).

        '
      parameters:
      - in: query
        name: id
        description: 'ID of Payment Initiation to retrieve.  This is the `paymentInitiationId` returned
          by the **Initiate a Payment** API

          '
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The Payment Initiation object
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaymentInitiationObj'
                - $ref: '#/components/schemas/PaymentInitiationStatusObj'
                - $ref: '#/components/schemas/PaymentAgreementObj'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorModel'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorModel'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorModel'
    post:
      security:
      - SecretKey: []
      tags:
      - Payment Initiation
      summary: Initiate a Payment
      description: Initiate a Payment
      operationId: makePaymentInitiation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentInitiationObj'
      responses:
        '201':
          description: Payment Initiated
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaymentInitiationObj'
                - $ref: '#/components/schemas/PaymentInitiationStatusObj'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayToErrorModel'
              examples:
                contentTypeError:
                  value:
                    message: Content-Type request header must be application/json
                paymentAgreementNotFoundError:
                  value:
                    message: Could not find Payment Agreement
                fixedAgreementFirstPaymentAmountError:
                  value:
                    message: The amount specified does not match the First Payment Amount
                fixedAgreementExceedOutstandingBalanceError:
                  value:
                    message: The amount specified exceeds the Outstanding Balance of this Agreement
                validityNotStartedError:
                  value:
                    message: This Payment Agreement's Validity has not started
                validityPassedError:
                  value:
                    message: This Payment Agreement's Validity End Date has passed
                clientIdMismatchError:
                  value:
                    message: 'ClientId mismatch: Expecting ...'
                invalidStateError:
                  value:
                    message: Invalid Payment Agreement status. Should be ACTIVE
                invalidRequestBodyError:
                  value:
                    message: An invalid request body was supplied
                ddrMigrationInProgressError:
                  value:
                    message: "This payment agreement is still being migrated and payments cannot be initiated\
                      \ in the first 5 \ncalendar days\n"
        '401':
          description: Invalid Authorization header
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorModel'
                - properties:
                    message:
               

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