Monoova Initiate a Payment API

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<style type=\"text/css\">\n.tb { table-layout:auto; width:300px;!important }\n.td { overflow:hidden; white-space:nowrap; text-overflow:ellipsis!important}\n</style>\n<table class=\"tb\">\n  <tr>\n    <th>Account Name</th>\n    <th>BSB</th>\n    <th>Account Number</th>\n    <th>PayID</th>\n  </tr>\n  <tr>\n    <td class=\"td\">Monoova Sample 1</td>\n    <td class=\"td\">802950</td>\n    <td class=\"td\">22090100</td>\n    <td class=\"td\">+61-422020901</td>\n  </tr>\n  <tr>\n    <td class=\"td\">Monoova Sample 2</td>\n    <td class=\"td\">802950</td>\n    <td class=\"td\">22090101</td>\n    <td class=\"td\">sample@monoova.com</td>\n  </tr>\n  <tr>\n    <td class=\"td\">Monoova Sample 3</td>\n    <td class=\"td\">802950</td>\n    <td class=\"td\">22090102</td>\n    <td class=\"td\">38126015228</td>\n  </tr>\n  <tr>\n    <td class=\"td\">Monoova Sample 4</td>\n    <td class=\"td\">802950</td>\n    <td class=\"td\">22090103</td>\n    <td class=\"td\">987654321</td>\n  </tr>\n</table>\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</br></br>\n### Response for Payment Agreements\n\n<style type=\"text/css\">\n.tb { table-layout:auto; width:300px;!important }\n.td { overflow:hidden; white-space:nowrap; text-overflow:ellipsis!important}\n</style>\n<table class=\"tb\">\n  <tr>\n    <th>Response</th>\n    <th>Reason Code</th>\n    <th>Contains Value</th>\n    <th>Example</th>\n    <th>Action</th>\n  </tr>\n  <tr>\n    <td class=\"td\">Agreement Approved</td>\n    <td class=\"td\">-</td>\n    <td class=\"td\">.00</td>\n    <td class=\"td\">$5.00, $10.00, $50.00</td>\n    <td class=\"td\">Approve</td>\n  </tr>\n  <tr>\n    <td class=\"td\">Requested By Customer</td>\n    <td class=\"td\">M019</td>\n    <td class=\"td\">.19</td>\n    <td class=\"td\">$5.19, $10.19, $50.19</td>\n    <td class=\"td\">Decline</td>\n  </tr>\n</table>\n\n### Other Test Cases\n\n<style type=\"text/css\">\n.tb { table-layout:auto; width:300px;!important }\n.td { overflow:hidden; white-space:nowrap; text-overflow:ellipsis!important}\n</style>\n<table class=\"tb\">\n  <tr>\n    <th>Response</th>\n    <th>Reason Code</th>\n    <th>Contains Value</th>\n    <th>Example</th>\n    <th>Action</th>\n  </tr>\n  <tr>\n    <td class=\"td\">Invalid Debtor Account Number</td>\n    <td class=\"td\">M001</td>\n    <td class=\"td\">.01</td>\n    <td class=\"td\">$5.01, $10.01, $50.01</td>\n    <td class=\"td\">Decline</td>\n  </tr>\n  <tr>\n    <td class=\"td\">Closed Debtor Account Number</td>\n    <td class=\"td\">M003</td>\n    <td class=\"td\">.03</td>\n    <td class=\"td\">$5.03, $10.03, $50.03</td>\n    <td class=\"td\">Decline</td>\n  </tr>\n  <tr>\n    <td class=\"td\">Blocked Account</td>\n    <td class=\"td\">M004</td>\n    <td class=\"td\">.04</td>\n    <td class=\"td\">$5.04, $10.04, $50.04</td>\n    <td class=\"td\">Decline</td>\n  </tr>\n  <tr>\n    <td class=\"td\">Invalid Debtor Account Type</td>\n    <td class=\"td\">M005</td>\n    <td class=\"td\">.05</td>\n    <td class=\"td\">$5.05, $10.05, $50.05</td>\n    <td class=\"td\">Decline</td>\n  </tr>\n  <tr>\n    <td class=\"td\">Transaction Forbidden</td>\n    <td class=\"td\">M006</td>\n    <td class=\"td\">.06</td>\n    <td class=\"td\">$5.06, $10.06, $50.06</td>\n    <td class=\"td\">Decline</td>\n  </tr>\n  <tr>\n    <td class=\"td\">Transaction Not Supported</td>\n    <td class=\"td\">M007</td>\n    <td class=\"td\">.07</td>\n    <td class=\"td\">$5.07, $10.07, $50.07</td>\n    <td class=\"td\">Decline</td>\n  </tr>\n  <tr>\n    <td class=\"td\">Not Allowed Currency</td>\n    <td class=\"td\">M008</td>\n    <td class=\"td\">.08</td>\n    <td class=\"td\">$5.08, $10.08, $50.08</td>\n    <td class=\"td\">Decline</td>\n  </tr>\n  <tr>\n    <td class=\"td\">Invalid Amount</td>\n    <td class=\"td\">M009</td>\n    <td class=\"td\">.09</td>\n    <td class=\"td\">$5.09, $10.09, $50.09</td>\n    <td class=\"td\">Decline</td>\n  </tr>\n  <tr>\n    <td class=\"td\">Amount Exceeds Agreed Limit</td>\n    <td class=\"td\">M010</td>\n    <td class=\"td\">.10</td>\n    <td class=\"td\">$5.10, $10.10, $50.10</td>\n    <td class=\"td\">Decline</td>\n  </tr>\n  <tr>\n    <td class=\"td\">No Mandate Service On Customer</td>\n    <td class=\"td\">M018</td>\n    <td class=\"td\">.18</td>\n    <td class=\"td\">$5.18, $10.18, $50.18</td>\n    <td class=\"td\">Decline</td>\n  </tr>\n  <tr>\n    <td class=\"td\">Mandate Cancelled Due To Fraud</td>\n    <td class=\"td\">M022</td>\n    <td class=\"td\">.22</td>\n    <td class=\"td\">$5.22, $10.22, $50.22</td>\n    <td class=\"td\">Decline</td>\n  </tr>\n  <tr>\n    <td class=\"td\">No Answer From Customer</td>\n    <td class=\"td\">M027</td>\n    <td class=\"td\">.27</td>\n    <td class=\"td\">$5.27, $10.27, $50.27</td>\n    <td class=\"td\">Decline</td>\n  </tr>\n  <tr>\n    <td class=\"td\">Regulatory Reason</td>\n    <td class=\"td\">M028</td>\n    <td class=\"td\">.28</td>\n    <td class=\"td\">$5.28, $10.28, $50.28</td>\n    <td class=\"td\">Decline</td>\n  </tr>\n  <tr>\n    <td class=\"td\">Creditor not on Whitelist of Debtor</td>\n    <td class=\"td\">M030</td>\n    <td class=\"td\">.30</td>\n    <td class=\"td\">$5.30, $10.30, $50.30</td>\n    <td class=\"td\">Decline</td>\n  </tr>\n  <tr>\n    <td class=\"td\">Creditor on Blacklist of Debtor</td>\n    <td class=\"td\">M031</td>\n    <td class=\"td\">.31</td>\n    <td class=\"td\">$5.31, $10.31, $50.31</td>\n    <td class=\"td\">Decline</td>\n  </tr>\n  <tr>\n    <td class=\"td\">Unknown end Customer</td>\n    <td class=\"td\">M032</td>\n    <td class=\"td\">.32</td>\n    <td class=\"td\">$5.32, $10.32, $50.32</td>\n    <td class=\"td\">Decline</td>\n  </tr>\n</table>\n\n\n<br/>\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.<br/> 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.</br> Possible Values ORGN - Organization, PERS - Person
          example: ORGN
        payeeLinkedBsb:
          type:
          - string
          - 'null'
          description: BSB number. </br>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. </br>Required if 'payeeLinkedPayId' and 'payeeLinkedPayIdType' are not provided.
          example: 22222222
        payeeLinkedPayId:
          type:
          - string
          - 'null'
          description: PayID. </br> Email, phone number, ABN, ACN or Organisation name. </br>Required if 'payeeLinkedBsb' and 'payeeLinkedAccount' are not provided. <a href="/payTo#tag/PAYID-Format-Validation">See PAYID Format Validation.</a>
          example: ''
        payeeLinkedPayIdType:
          type:
          - string
          - 'null'
          description: PayID Type. Possible values ABN, Email, PhoneNumber, OrganisationId, ACN. </br>Required if 'payeeLinkedBsb' and 'payeeLinkedAccount' are not provided.
          example: ''
        payeeAccountName:
          type:
          - string
          - 'null'
          description: Bank Account Name </br> 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.</br> 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