openapi: 3.2.0 info: description: "# Introduction\n\nThe Monoova PayTo API is designed to efficiently handle real time financial transactions, providing a reliable platform for creating payment agreements and initiating payments. It offers a streamlined transaction process, ensuring speed and security for businesses and users with benefits above and beyond a direct debit alternative.\n\nMonoova's PayTo API supports synchronous and asynchronous operations, allowing flexible integration based on varying business needs. The asynchronous API option is particularly beneficial for handling batch operations requiring extended processing time, enhancing overall system performance and reliability. Additionally, Monoova provides webhook subscriptions, enabling users to receive timely updates and notifications about transaction events, which helps maintain transparency and control over financial activities.\n\n## Process\n\nPayTo allows you to debit an enabled domestic bank account in real time. \n\n* First, you create a **payment agreement** between a payer and a payee. The terms of the agreement determine the amount and schedule of allowed debits. When you create a Payment Agreement, the account is validated in real time, so you can ensure the account details are correct.\n\n* Next, the payer authorises the agreement through their banking app.\n\n* Finally, real time **payment initiations** can be triggered. If successful, funds will be credited to the payee account in real time and made available for disbursement. Because recipients can access funds faster than traditional direct debit systems, this is particularly beneficial for businesses or individuals relying on prompt cash flow payments.\n\n* If you would like to modify the terms of the agreement, you can use the amendment API's.\n\n# Getting Started\n\n1. Access the Domestic Payments Portal:\n\n * Sandbox Environment:\n - Register: If you are new, [register](https://sandbox.monoova.com) to gain Sandbox access.\n - Login: If you already have Sandbox credentials, [log in](https://sandbox.monoova.com) to continue your work.\n\n * Production Environment:\n - Login: Login to the [Production portal](https://payments.monoova.com) using the credentials you obtained during onboarding.\n\n2. Activate Your API Key\n\n * Generate API Key:\n - If you do not know your API Key or need to reset it, navigate to Manage > Accounts to generate or regenerate your API Key after logging into the portal.\n\n * Activate API Gateway Access:\n - Go to Manage > API Gateway and enter your API Key to activate API Gateway access for your mAccount.\n\n3. Configure API Access\n\n Please [contact our integration team](https://www.monoova.com/contact) to configure your account settings. This step ensures that your account is allowed to access the service.\n\n4. Explore API Endpoints\n\n Use the API documentation to plan your integration. It provides details and examples of usage.\n\n5. Onboarding and Support\n\n Our integration team will guide you from the initial setup to the final running implementation, providing support throughout the process.\n\n# Sandbox Testing for PayTo Agreements\n\nIn the Sandbox environment, it is possible to test different outcomes for PayTo agreements by altering the values of the agreement. This allows for a comprehensive evaluation of potential scenarios in a controlled setting.\n\n## Use the following payment details when testing in Sandbox:\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
Account NameBSBAccount NumberPayID
Monoova Sample 180295022090100+61-422020901
Monoova Sample 280295022090101sample@monoova.com
Monoova Sample 38029502209010238126015228
Monoova Sample 480295022090103987654321
\n\n## Testing Payment Agreements\n\nPayment agreements are automatically approved or declined in the Sandbox environment, depending on the amount or `maxAmount` included in the agreement request. If both `amount` or `maxAmount` are passed, the `amount` will determine the behavior.\n\nFor basic testing of Payment Agreements, the following test cases are recommended. A more comprehensive list of test cases is available should you wish to examine edge cases.\n

\n### Response for Payment Agreements\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
ResponseReason CodeContains ValueExampleAction
Agreement Approved-.00$5.00, $10.00, $50.00Approve
Requested By CustomerM019.19$5.19, $10.19, $50.19Decline
\n\n### Other Test Cases\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
ResponseReason CodeContains ValueExampleAction
Invalid Debtor Account NumberM001.01$5.01, $10.01, $50.01Decline
Closed Debtor Account NumberM003.03$5.03, $10.03, $50.03Decline
Blocked AccountM004.04$5.04, $10.04, $50.04Decline
Invalid Debtor Account TypeM005.05$5.05, $10.05, $50.05Decline
Transaction ForbiddenM006.06$5.06, $10.06, $50.06Decline
Transaction Not SupportedM007.07$5.07, $10.07, $50.07Decline
Not Allowed CurrencyM008.08$5.08, $10.08, $50.08Decline
Invalid AmountM009.09$5.09, $10.09, $50.09Decline
Amount Exceeds Agreed LimitM010.10$5.10, $10.10, $50.10Decline
No Mandate Service On CustomerM018.18$5.18, $10.18, $50.18Decline
Mandate Cancelled Due To FraudM022.22$5.22, $10.22, $50.22Decline
No Answer From CustomerM027.27$5.27, $10.27, $50.27Decline
Regulatory ReasonM028.28$5.28, $10.28, $50.28Decline
Creditor not on Whitelist of DebtorM030.30$5.30, $10.30, $50.30Decline
Creditor on Blacklist of DebtorM031.31$5.31, $10.31, $50.31Decline
Unknown end CustomerM032.32$5.32, $10.32, $50.32Decline
\n\n\n
\n\nIn addition to a sample request, the scheme for each endpoint and associated data tables are in the appendix at the end of this document.\n\nTo try out our API, you can use a client such as [Postman](https://www.getpostman.com).\n\nYou can download a postman collection of our API by clicking the link below:\n\n[![Run in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/19891519-fccdc471-7f26-4f4c-bba7-4e0dda5ab9e3?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D19891519-fccdc471-7f26-4f4c-bba7-4e0dda5ab9e3%26entityType%3Dcollection%26workspaceId%3D0a304f49-2e6e-4498-8d43-3b68ee26aee6)\n\n**Note:** Please note we do not accept TLS 1.0 or 1.1 connections\n" version: v1 title: Monoova PayTo Initiate a Payment API contact: name: Monoova Support email: support@monoova.com url: https://www.monoova.com x-logo: url: https://movdpwebsiteprodae.blob.core.windows.net/images/Monoova-Primary-Logo-Black-RGB.png altText: Monoova logo servers: - url: https://api.monoova.com description: Production URL# - url: https://sand-api.monoova.com description: Sandbox URL security: - BearerAuth: [] tags: - name: Initiate a Payment description: Once a payment agreement is created you can trigger payments against it paths: /au/payto/pas-v1/paymentInstruction: post: tags: - Initiate a Payment summary: Payment Instruction description: Once a valid payment agreement has approved by the payer this endpoint is used to create a payment initiation, which creates real time pull payments.
You are allowed a maximum of 5 failed initiations in a 24 hour period, if you reach this limit you will need to wait until the next day to retry. operationId: post-paymentinstruction requestBody: content: application/json: schema: $ref: '#/components/schemas/InitiateMandatePaymentDto' example: paymentAgreementUID: BCORP123456 paymentInitiationUID: BCORP00000001 paymentDetails: amount: 1.0 lodgementReference: BCorp PIR 001 responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/InitiateMandatePaymentResponseDto' '202': description: pending content: application/json: example: paymentAgreementUID: '1111222333' paymentInitiationUID: C150D6FAE2044CA9A3ADB470874E8F86 mmsId: ed8569b4fd8614259d13bcb9a2da2bc0 nppInstructionId: MOPYAUS1XXXI20241119004756058205270 paymentInitiationStatus: INPR paymentInitiationStatusDescription: In progress traceId: f3ae20c5-e400-4eab-8fb0-16e03c8481be '422': description: Rejected content: application/json: example: paymentAgreementUID: '1111222333' paymentInitiationUID: C150D6FAE2044CA9A3ADB470874E8F86 mmsId: ed8469b4fd8616259d15b4b9a2da2bc0 paymentInitiationStatus: RJCT paymentInitiationStatusDescription: Rejected statusReasonCode: R999 statusReasonDescription: Payment initiation rejected by banking institution. Please contact Monoova traceId: f3ae20c5-e400-4eab-8fb0-16e03c8481be '400': description: Error content: application/json: example: traceId: f1a7fbd7-ca39-4b98-b247-f4e0e004f152 errors: - errorCode: string errorMessage: string '403': description: Error content: application/json: example: traceId: f1a7fbd7-ca39-4b98-b247-f4e0e004f152 errors: - errorCode: string errorMessage: string '404': description: Error content: application/json: example: traceId: f1a7fbd7-ca39-4b98-b247-f4e0e004f152 errors: - errorCode: string errorMessage: string '500': description: Error content: application/json: example: traceId: f1a7fbd7-ca39-4b98-b247-f4e0e004f152 errors: - errorCode: string errorMessage: string '502': description: Error content: application/json: example: traceId: f1a7fbd7-ca39-4b98-b247-f4e0e004f152 errors: - errorCode: string errorMessage: string '504': description: Error content: application/json: example: traceId: f1a7fbd7-ca39-4b98-b247-f4e0e004f152 errors: - errorCode: string errorMessage: string components: schemas: PaymentInitiationDetailsDto: type: object required: - amount properties: amount: type: string description: Amount to be transferred. Amount should be >=0.01 maxLength: 34 isLastPayment: type: - boolean - 'null' description: Set to true to indicate this is the last payment initiation request associated with the mandate. Possible values - True, False. lodgementReference: type: - string - 'null' description: Unique reference, as assigned by the creditor, to unambiguously refer to the payment transaction. maxLength: 280 additionalProperties: false InitiateMandatePaymentResponseDto: type: object properties: traceId: type: string example: f3ae20c5-e400-4eab-8fb0-16e03c8481be paymentAgreementUID: type: string description: Id to uniquely Identify a payment agreement. maxLength: 35 pattern: ^[A-Z0-9_-] example: MOA1222333 paymentInitiationUID: type: string description: Id to uniquely Identify a payment initiation. maxLength: 35 pattern: ^[A-Z0-9_-] example: C150D6FAE2044CA9A3ADB470874E8F86 nppInstructionId: type: string description: Unique identifier for the NPP instruction. maxLength: 35 example: MOPYAUS1XXXI20241119004756058205270 paymentInitiationStatus: type: string description: This is the status of the payment agreement. example: ACSC paymentInitiationStatusDescription: type: string description: This describes the status. For example, a status of ‘created’ will have a description of ‘Pending Payer Approval’ example: Accepted & Settled mmsId: type: string description: This is the unique ID that identifies this payment agreement. example: ed8569b5fd8616259d15b5b9a2d52bc0 additionalProperties: false PayeeDetailsDto: required: - payeeType oneOf: - required: - payeeLinkedBsb - payeeLinkedAccount - required: - payeeLinkedPayId - payeeLinkedPayIdType - payeeAccountName type: object properties: payeeType: type: - string - 'null' description: Identifies the type of a party.
Possible Values ORGN - Organization, PERS - Person example: ORGN payeeLinkedBsb: type: - string - 'null' description: BSB number.
Required if 'payeeLinkedPayId' and 'payeeLinkedPayIdType' are not provided. e.g. '999-999 or 999999' example: 999-999 payeeLinkedAccount: type: - string - 'null' maxLength: 28 description: Bank Account Number.
Required if 'payeeLinkedPayId' and 'payeeLinkedPayIdType' are not provided. example: 22222222 payeeLinkedPayId: type: - string - 'null' description: PayID.
Email, phone number, ABN, ACN or Organisation name.
Required if 'payeeLinkedBsb' and 'payeeLinkedAccount' are not provided. See PAYID Format Validation. example: '' payeeLinkedPayIdType: type: - string - 'null' description: PayID Type. Possible values ABN, Email, PhoneNumber, OrganisationId, ACN.
Required if 'payeeLinkedBsb' and 'payeeLinkedAccount' are not provided. example: '' payeeAccountName: type: - string - 'null' description: Bank Account Name
Can only provide payeeAccountName in the payload if crediting an external BSB. Mandatory if crediting a PayID. maxLength: 140 example: ABCORP ultimatePayee: type: - string - 'null' example: ABCORP description: Name by which the party is known, and which is usually used to identify that party.
Can only provide ultimatePayee in the payload if crediting an external BSB. additionalProperties: false InitiateMandatePaymentDto: type: object required: - paymentAgreementUID - paymentInitiationUID - paymentDetails properties: paymentAgreementUID: type: - string - 'null' maxLength: 35 description: Id to uniquely Identify a payment agreement. paymentInitiationUID: type: - string - 'null' maxLength: 35 description: Id to uniquely identify payment payeeDetails: $ref: '#/components/schemas/PayeeDetailsDto' paymentDetails: $ref: '#/components/schemas/PaymentInitiationDetailsDto' additionalProperties: false securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT BasicAuth: type: http scheme: basic x-tagGroups: - name: '' tags: - Generate a Bearer Token - Manage Payment Agreements - PayTo Async API - Initiate a Payment - Reporting - Webhooks - Notification Management - PAYID Format Validation - Client Error Responses - Monoova Error Codes - Mandate Status Reason Codes - Payment Initiation Status - Payment Agreement Status - Payment Initiation Reject Reason Codes