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 example: AZP5.1 description: 'A failure code for the error response. For the full list, please refer to the [Failure Codes and Failure Reasons](/guide/receiving-recurring-payments.html#failure-codes-and-failure-reasons) page ' failureReason: type: string example: PayID format is incorrect description: 'A reason message for the error response For the full list, please refer to the [Failure Codes and Failure Reasons ](/guide/receiving-recurring-payments.html#failure-codes-and-failure-reasons) page ' PaymentAgreementSearchObj: type: object additionalProperties: false properties: PaymentAgreementSearch: type: object description: Please note `paymentAgreementId`, `contractId` and date fields can't be included in the same request additionalProperties: false properties: fromDate: $ref: '#/components/schemas/fromDateUTC' toDate: $ref: '#/components/schemas/toDateUTC' paymentAgreementId: $ref: '#/components/schemas/paymentAgreementIdForSearch' contractId: $ref: '#/components/schemas/ContractIdObj' countPerPeriod: type: string description: Number of payments within a specified period based on the frequency pattern: ^[1-9][0-9]{0,2}$ example: '5' ContractIdObj: type: string minLength: 1 maxLength: 50 description: "Unique Id for the merchant side contract.\nThis field is used to prevent the creation of duplicated payment agreements in CREATED, SUSPENDED, ACTIVE status. \nPayment agreements in statuses such as CANCELLED, FAILED are not considered duplicates.\n" example: 30597959-a853-44d4-bdab-54332bf7a98e amount: type: string description: Amount in AUD pattern: ^[0-9]+(\.[0-9]{2})$ example: '1001.95' lastPaymentDate: 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-06-01' BsbObj: type: string description: The BSB of the account number minLength: 6 maxLength: 6 pattern: ^\d*$ example: '123456' PayIDObj: type: string minLength: 1 maxLength: 140 example: jane.smith@example.com description: "The payer's PayID. Valid examples are `+61-432123321` (mobile), `+61-312344321` (landline), \n`0432123321` (mobile), `0312344321` (landline), `jane.smith@example.com`\n" maximumAmount: type: string description: Amount in AUD pattern: ^[0-9]+(\.[0-9]{2})$ example: '1001.95' lastPaymentAmount: type: string description: Amount in AUD pattern: ^[0-9]+(\.[0-9]{2})$ example: '1001.95' AccountNumberObj: type: string description: The Account Number (without the BSB) minLength: 4 maxLength: 9 pattern: ^\d*$ example: '123555555' azupayId: type: string description: An identifier generated by Azupay. Used to reference the object in subsequent operations example: K+9p4EE0rJnMtomRfWKWEDRh82BnAboHP2KwgIPyEIA= PaymentAgreementStatusObj: type: object required: - PaymentAgreementStatus properties: PaymentAgreementStatus: type: object required: - paymentAgreementId - status - createdDatetime properties: paymentAgreementId: $ref: '#/components/schemas/azupayId' registrationDatetime: type: string format: date-time description: Timestamp when the payment agreement was registered status: type: string description: Status of the requested payment agreement. enum: - CREATED - ACTIVE - SUSPENDED - CANCELLED - FAILED previousStatus: type: string description: Previous status of the requested payment agreement. enum: - CREATED - ACTIVE - SUSPENDED lastStatusBy: type: string description: The party who last changed the status. enum: - MERCHANT - PAYER - AZUPAY payerBsb: type: string description: The BSB of the payer reasonDescription: type: string example: The account has been closed and the Mandate is no longer valid. description: The reasonCode description (a detailed list is available under the `reasonCode` field). reasonCode: type: string example: NARR description: 'A reason code for a payment agreement that was initially ACTIVE/CREATED then CANCELLED | `reasonCode` | Description | |--------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | AC02 | Account to be debited does not exist within NPP and outside of NPP and cannot be reached by any other payment method. This code is also to be used when a Participant attempts to resolve a Debtor PayID and no account details are returned. | | AC04 | The account has been closed and the Mandate is no longer valid. | | AC05 | The Payer Customer Account number is closed and the Mandate is no longer valid. | | AC06 | Account is temporarily blocked where it can identify that the Account currently exists. | | AC13 | Account to be debited cannot debit funds within NPP where it is able to identify that the Account currently exists. | | AG01 | Account to be debited is unable to be debited where it can identify that the Account currently exists | | AG03 | Where a Mandate has been amended by the Initiating Participant such that payment initiation (the combination of debtor account and creditor account) resolves to an Account type that is not supported for sending or receiving NPP Payments. | | AM03 | Account to be debited cannot draw funds in AUD where it is able to identify that the Account currently exists. | | AM12 | No amount and/or no maximum amount are specified in the Mandate. | | AM14 | The specified Mandate amount (when supplied) exceeds the allowed transaction amount for the account for the specified Mandate. This code is appropriate in instances when account limits change, impacting Mandates referencing that account. | | CTAM | Mandate suspended due to amendment of the contract. | | CTCA | Mandate suspended due to cancellation of the contract, requested by the debtor. | | CTEX | Mandate suspended due to the contract that expired. | | MCFC | Mandate suspended as final collection took place. | | MCOC | Mandate suspended as the once off collection took place. | | MD07 | End customer is deceased. | | MD08 | The Mandate Service is no longer supported by the Agent | | MD09 | The Payer Customer or Payer Customer Account does not support the Mandate or no longer supports Mandate Services. For example, based on the Mandate purpose code, the Payer Customer may be ineligible for the Mandate service requested (e.g.: use of gambling-type Mandates are not permitted where it is identified that a Payer Customer is a minor or a vulnerable customer). | | MD16 | Cancellation/amendment requested by the debtor | | MD17 | Cancellation/amendment requested by the creditor or by the initiating party | | MD20 | Mandate cancellation following validity expiration | | MS02 | Reason has not been specified by end customer | | MS03 | Reason has not been specified by agent. | | MSUC | Mandate suspended after 7 consecutive unsuccessful collections. | | NARR | Technical error encountered | | NOAS | Participant received no response from beneficiary (to authorise or reject a Mandate creation or amendment request). | | RR04 | The Mandate is suspended or cancelled due to regulatory reasons (e.g. Sanctions, AML). | | SL01 | Due to specific service offered by the Debtor Agent | | SL11 | The Mandate is suspended or cancelled due to the Payee or the Initiating Party nominated in the Mandate not being included or being removed from the Payer Customer’s “whitelist”. | | SL12 | The Mandate is suspended or cancelled due to the Payee or the Initiating Party nominated in the Mandate being included on the Payer Customer’s “blacklist”. | ' failureCode: type: string example: AZP2.1 description: "A failure code for a payment agreement that is in `status=FAILED`. The codes are:\n\n| `failureCode` | `failureReason` |\n|---------------|------------------------------------------------------------------------------|\n| AZP2.1 | \tAn error has occurred with this Payment Agreement. Please contact support. |\n| AZP2.2 | \tThe payer account is not eligible for PayTo payments. |\n| AZP2.3 | \tThe payer account is not eligible for NPP payments. |\n| AZP2.4 | \tPayee alias details are invalid. |\n| AZP3.1 | \tLast payment date must be equal to or after start date. |\n| AZP3.2 | \tStart date must be today or future dated. |\n| AZP3.3 | \tEnd date must be equal to or after start date. |\n| AZP4.1 | \tRequest Timed Out. Please Try again. |\n| AZP4.2 | \tPossible NPP outage. Please try again later. |\n| AZP9.9 | \tFatal Error. Please contact support. |\n" failureReason: type: string example: An error has occurred with this Payment Agreement description: A reason message for a payment agreement that is in `status=FAILED`. createdDatetime: type: string format: date-time description: Timestamp when the payment agreement was created cancelledDatetime: type: string format: date-time description: Timestamp when the payment agreement was cancelled bilateralAmendment: type: object properties: inProgress: type: boolean description: True if bilateral amendment of payment agreement is in progress paymentAgreementAmendmentId: type: string description: ID of the last amendment for reference unilateralAmendment: type: object properties: paymentAgreementAmendmentId: type: string description: ID of the last amendment for reference changeStatusAmendment: type: object properties: inProgress: type: boolean description: True if payment agreement change status is in progress paymentAgreementAmendmentId: type: string description: ID of the last amendment for reference nppAgreementId: type: string description: "The npp agreement id. A npp wide identifier used between banks, businesses and payment facilitators \nsuch as Azupay to reference a PayTo agreement. This identifier is made available shortly after the \ninitial creation of an agreement either via webhook or by querying existing agreement objects using \nthe API.\n" endpointURL: type: string format: url description: "An internet accessible url which Azupay will invoke when the status of the transaction has \nchanged. The call will be done using the HTTP POST method. The endpoint exposed by the client \nmust be TLS 1.2 and the server certificate must be issued by a well known commercial certificate \nauthority and that self-signed or internally signed certs are not acceptable.\n" example: https://example.org NotificationObj: type: object description: Merchant Callback Details required: - endpointURL - authorizationHeader properties: endpointURL: $ref: '#/components/schemas/endpointURL' authorizationHeader: $ref: '#/components/schemas/authorizationHeader' frequency: type: string description: Payment Frequency enum: - ADHOC - DAILY - FORTNIGHTLY - INTRADAY - SEMIANNUAL - MONTHLY - QUARTERLY - WEEKLY - ANNUAL agreementPayeeName: type: string maxLength: 140 minLength: 1 pattern: ^[ -~]*$ description: 'Lets you control the Payee description (visible to they payer) on the payment agreement: * If not populated, then your business name will appear i.e. "My business name". * If populated, then your business appears as a facilitator so the description will read something like "My business name on behalf of `payeeName`". ' PaymentSchedulerStatus: type: object description: Server-managed state returned on every GET/POST response. required: - version - createdDatetime additionalProperties: false properties: version: type: integer description: Monotonically incrementing version, updated on each successful mutation. example: 1 lastRunDatetime: type: string format: date-time description: Datetime of the most recent recorded run, if any (ISO 8601 UTC, millisecond precision). createdDatetime: type: string format: date-time description: Scheduler creation timestamp (ISO 8601 UTC). updatedDatetime: type: string format: date-time description: Timestamp of the most recent amendment, if any (ISO 8601 UTC). PaymentAgreementSearchResponseObj: type: object allOf: - $ref: '#/components/schemas/PaymentAgreementObj' - $ref: '#/components/schemas/PaymentAgreementStatusObj' PayToAmountObj: type: string pattern: ^[0-9]+(\.[0-9]{2})$ description: Amount in AUD to be requested from the Payee example: '2101.95' AdditionalDetailsObj: type: object required: - customerNumber - userID - authMethod - channelType description: Additional details for auditing purposes properties: customerNumber: type: string description: 'Uniquely identifies the Customer for whom the request has been initiated for. i.e. the Customer that owns the account. This field should contain the Member Number or Customer Number from the Client''s banking system. ' maxLength: 25 userID: type: string description: 'Uniquely identifies the User that has initiated the request. This could be the Customer or someone authorised to act on behalf of the Customer. ' maxLength: 25 authMethod: type: string description: 'This field allows us to understand how the user has logged in. Over a period we can determine if there is a deviation from normal usage patterns. e.g. Moving from biometric to PIN and linking that with payments we can detect fraud happening but also apply other rules to understand if PayIds are being from a device for malicious intent. ' enum: - 2FACTOR - OTP - BIOMETRIC - PASSWORD - PIN - NONE channelType: type: string description: 'This field allows us to understand, similar to authenticationMethod, which channels are being used to initiate a request. If `BROWSER` or `MOBILE` is selected. `ipAddress` and `deviceFingerprint` will be required fields. ' enum: - BROWSER - MOBILE - BRANCH - IVR - OTHER ipAddress: type: string description: 'IP address of the device or computer from which the user request originated. Required if request originated from a browser or mobile, else do not send. ' fraudScore: type: string description: This is a fraud score you may have calculated. if not, do not send. deviceFingerprint: type: string description: 'The device fingerprint or browser fingerprint. A change in device is a possible indicator of fraud/ID takeover/phone number porting. The device fingerprint, machine fingerprint or browser fingerprint. Required if the request originated from a web browser or mobile device, else do not send. ' notes: type: string description: Free text field up to 2048 characters. maxLength: 2048 geoLocation: type: string description: 'Latitude and Longitude from which the user request originated. For example -33.8708464,151.20732999999998 Only to be provided if GPS is enabled on the device, else do not send. ' maxLength: 50 AgreementExpiryMinutesObj: type: integer description: An integer value representing the total number of minutes before a payment agreement expires. This field has a minimum value of 5 and a max of 7199 minimum: 5 maximum: 7199 example: 5 toDateUTC: type: string pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$ description: The report date in ISO date/time string format in UTC example: '2021-10-18T02:32:30.693Z' ClientTransactionIdObj: description: 'Unique Id for the transaction created by the merchant system 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. ' minLength: 5 maxLength: 100 type: string example: TX5346423452345345 fromDateUTC: type: string pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$ description: The report date in ISO date/time string format in UTC example: '2021-10-18T02:32:30.693Z' ClientIdObj: type: string description: 'Id of the client initiating the transaction. This is supplied by Azupay and only changes between environments. For example, you might be allocated CLIENT1TEST for the UAT environment and CLIENT1 for production. ' minLength: 5 maxLength: 50 example: CLIENT1 firstPaymentAmount: type: string description: Amount in AUD pattern: ^[0-9]+(\.[0-9]{2})$ example: '1001.95' PayeeDetailsObj: type: object description: Payee Details properties: becsUserId: type: string description: 'The BECS user ID related to the migrating Direct Debit Authority (DDR) over to a Payment Agreement. Only populate this field if it is for a migration request. ' minLength: 1 maxLength: 6 pattern: ^[a-zA-Z0-9]*$ example: 123456 payeeName: $ref: '#/components/schemas/agreementPayeeName' PaymentAgreementObj: type: object required: - PaymentAgreement properties: PaymentAgreement: type: object required: - clientId - clientTransactionId - payerDetails - paymentAgreementType - description - agreementDetails properties: clientId: $ref: '#/components/schemas/ClientIdObj' additionalDetails: $ref: '#/components/schemas/AdditionalDetailsObj' contractId: $ref: '#/components/schemas/ContractIdObj' clientTransactionId: $ref: '#/components/schemas/ClientTransactionIdObj' paymentAgreementNotification: $ref: '#/components/schemas/NotificationObj' conditionsOfPayment: type: string pattern: ^[ -~]{1,140}$ minLength: 1 maxLength: 140 agreementExpiryMinutes: $ref: '#/components/schemas/AgreementExpiryMinutesObj' description: Indication of conditions of sale, references to terms and conditions or Product Disclosure Statement as agreed between parties. payerDetails: $ref: '#/components/schemas/PayerDetailsObj' payeeDetails: $ref: '#/components/schemas/PayeeDetailsObj' paymentAgreementType: type: string enum: - MORTGAGE - UTILITY - LOAN - DEPENDANT SUPPORT - GAMBLING - RETAIL - SALARY - PERSONAL - GOVERNMENT - PENSION - TAX - OTHER SERVICE description: $ref: '#/components/schemas/agreementDescription' variant: type: string enum: - API - 1Click agreementDetails: type: object description: Agreement Details properties: fixedAgreementDetails: type: object description: Fixed Agreement Details additionalProperties: false required: - startDate - frequency - amount properties: startDate: $ref: '#/components/schemas/StartDateObj' endDate: $ref: '#/components/schemas/endDate' firstPaymentAmount: $ref: '#/components/schemas/firstPaymentAmount' amount: $ref: '#/components/schemas/amount' frequency: $ref: '#/components/schemas/frequency' countPerPeriod: $ref: '#/components/schemas/countPerPeriod' balloonAgreementDetails: type: object description: Balloon Agreement Details additionalProperties: false required: - startDate - frequency properties: startDate: $ref: '#/components/schemas/StartDateObj' lastPaymentDate: $ref: '#/components/schemas/lastPaymentDate' lastPaymentAmount: $ref: '#/components/schemas/lastPaymentAmount' amount: $ref: '#/components/schemas/amount' frequency: $ref: '#/components/schemas/frequency' countPerPeriod: $ref: '#/components/schemas/countPerPeriod' usageBasedAgreementDetails: type: object additionalProperties: false required: - startDate - frequency properties: maximumAmount: $ref: '#/components/schemas/PayToAmountObj' startDate: $ref: '#/components/schemas/StartDateObj' endDate: $ref: '#/components/schemas/endDate' frequency: $ref: '#/components/schemas/frequency' countPerPeriod: $ref: '#/components/schemas/countPerPeriod' variableAgreementDetails: type: object description: Variable Agreement Details additionalProperties: false required: - startDate - frequency properties: startDate: $ref: '#/components/schemas/StartDateObj' endDate: $ref: '#/components/schemas/endDate' maximumAmount: $ref: '#/components/schemas/maximumAmount' frequency: $ref: '#/components/schemas/frequency' countPerPeriod: $ref: '#/components/schemas/countPerPeriod' additionalProperties: false additionalProperties: false additionalProperties: false PaymentScheduler: type: object description: 'Scheduler attached to an active PayTo payment agreement. On create/amend, status accepts ACTIVE or INACTIVE only; other lifecycle states (PAUSED, CANCELLED, COMPLETED) may appear on read responses. ' required: - status - frequency - startDate - amount - timezone additionalProperties: false properties: paymentAgreementId: type: string description: The payment agreement the scheduler is attached to. minLength: 1 maxLength: 50 example: a8c1f2de9b4c47e1bf0a3d5e6f70811a status: type: string description: Scheduler state. Create/amend accept ACTIVE or INACTIVE only. enum: - ACTIVE - INACTIVE example: ACTIVE frequency: type: string description: Run frequency. Must match the underlying agreement's frequency. enum: - WEEKLY - FORTNIGHTLY - MONTHLY - ANNUAL - ONCE example: MONTHLY amount: type: string description: Run amount in AUD as a string. Must fit inside the agreement's per-payment and per-period caps. pattern: ^\d+\.\d{2}$ example: '89.95' startDate: type: string format: date description: First run date (YYYY-MM-DD). Must be strictly after today in the scheduler's timezone. pattern: ^\d{4}-\d{2}-\d{2}$ example: '2026-06-01' endDate: type: - string - 'null' format: date description: Last permitted run date (YYYY-MM-DD). Omit for an open-ended scheduler; send null to clear on amend. pattern: ^\d{4}-\d{2}-\d{2}$ example: '2027-06-01' timezone: type: string description: IANA timezone name (e.g. Australia/Sydney, Australia/Perth, UTC). No implicit default. pattern: ^([A-Za-z]+/[A-Za-z_]+|UTC)$ example: Australia/Sydney version: type: integer description: Version required when updating this scheduler example: 1 StartDateObj: 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-01-01' PaymentAgreementAmendmentStatusObj: type: object required: - PaymentAgreementAmendmentStatus properties: PaymentAgreementAmendmentStatus: type: object required: - paymentAgreementAmendmentId - amendmentStatus - createdDatetime properties: paymentAgreementAmendmentId: $ref: '#/components/schemas/azupayId' bilateralAmendmentStatus: type: string description: Use `amendmentStatus` instead. deprecated: true enum: - PENDING - COMPLETED - DECLINED - RECALLED - TIMEDOUT amendmentStatus: type: string description: Status of the requested payment agreement amendment. enum: - PENDING - COMPLETED - DECLINED - RECALLED - TIMEDOUT createdDatetime: type: string format: date-time description: Timestamp when the payment agreement amendment was created completedDatetime: type: string format: date-time description: 'Timestamp when the amend payment agreement was completed. Only for `amendmentStatus` different than `PENDING`. ' nextPageIdResponse: type: string description: 'If there are more results you can invoke this search again by providing the nextPageId in the query parameters to retrieve the next set of results. ' ErrorModel: type: object additionalProperties: false required: - message properties: message: type: string details: type: object additionalProperties: false properties: failureCode: type: string failureReason: type: string required: - failureCode - failureReason securitySchemes: SecretKey: description: 'The secret key is used to access restricted functions and should be stored securely in your system. It is required for operations which may result in additional charges to you as a merchant. Please protect the key by storing it encrypted granting access only to a limited set of users and applications requiring its use. ' in: header name: Authorization type: apiKey DistributableKey: description: 'The distributable key has limited access and may be exposed publicly to your payers. ' in: header name: Authorization type: apiKey