openapi: 3.2.0
info:
  description: "# Introduction\n\n<p> \n  Monoova has developed a powerful payments engine which allows you to receive, manage and pay funds in AUD in Australia automatically.\n  This service is made available to Monoova’s clients through a set of easy-to-use RESTful APIs with JSON payloads described in this document.\n  The central idea is to reduce the cost, risk and effort normally associated with managing complex money movements so that you can focus on growing your business.\n</p> \n<p> \n Our clients can receive and reconcile funds via Realtime transfers (NPP), direct credits/debits, BPAY and cards. \n They can then manage those funds by building virtual account/wallet hierarchies to get bespoke reporting, reconciliation and much more. \n And finally, our clients can pay funds via Realtime transfers (NPP) direct credits and BPAY. \n As new technologies become available (e.g. NPP Mandated payments) we will make additional methods of receiving, managing and paying available.\n</p> \n<p> \n  All information flows are real-time.\n  Moving money between various Monoova accounts is also real time.\n  All money flows in and out of the Engine are as fast as the banking system allows.\n</p>\n<p> \n  The sandbox environment is open to everyone who signs up on our <a href=\"https://sandbox.monoova.com/user/login\" target=\"_blank\">Sandbox Portal</a> at no cost.\n  The sandbox environment allows you to test out the functionality of our API in a consequence free development environment.\n  Access to the live environment is granted once you have (1) gone through our compliance process and (2) had formal sign-off on your sandbox integration.\n</p>\n<p>\n  Monoova regularly releases additive changes to our API, as well as new versions of the API when a breaking change would occur. \n  To ensure your integration does not break due to these additive changes, we recommend not validating the entire schema, or the position of a parameter within the schema.\n</p>\n<br/><br/>\n<p> <strong> Note&#58;</strong> Please note we do not accept TLS 1.0 or 1.1 connections</p>\n\n# Getting started\n>\n  - Sign on to our <a href=\"https://sandbox.monoova.com/user/login\" target=\"_blank\">Sandbox Portal</a>\n  - Get your sandbox API key under **MANAGE > ACCOUNTS** in the Sandbox Portal\n  - [Authenticate](#section/Authentication)\n  - Browse this document to find the functions you need\n  - Begin experimenting with your first API calls by sending HTTP requests to the endpoints described in this document\n  - Use the provided examples in the document as guidance\n\n# Authentication\n  All RESTful APIs in this document use BASIC Authentication (except those in public/v1) in two scenarios either\n  - <strong> API KEY </strong>\n  - <strong> OneShotSecurityToken </strong><br><br>\n\n> **Sandbox Authentication Credentials**\n<table>\n  <tr>\n    <th>Field</th>\n    <th>Value</th>\n  </tr>\n  <tr>\n    <td>Username</td>\n    <td>API Key (obtained from the <a href=\"https://sandbox.monoova.com/user/login\" target=\"_blank\">Sandbox Portal</a>) </td>\n  </tr>\n  <tr>\n    <td>Password</td>\n    <td>leave blank when using API key; Monoova will provide password for OneShotSecurityToken</td>\n  </tr>\n  <tr>\n    <td>Base URL</td>\n    <td>https://api.m-pay.com.au/</td>\n  </tr>\n</table> <br>\n\n> **Live Authentication Credentials**\nThis will be provided by Monoova after a technical review. <br> \n<table>\n  <tr>\n    <th>Field</th>\n    <th>Value</th>\n  </tr>\n  <tr>\n    <td>Username</td>\n    <td>API Key (obtained from the Production Portal; Production credentials will be supplied by Monoova) </td>\n  </tr>\n  <tr>\n    <td>Password</td>\n    <td>leave blank when using API key; Monoova will provide password for OneShotSecurityToken</td>\n  </tr>\n  <tr>\n    <td>Base URL</td>\n    <td>https://api.mpay.com.au/</td>\n  </tr>\n</table> <br>\n\nWhen using the LIVE Engine, your Sign-In Account is given five (5) attempts to authenticate your credentials. \nOn the fifth failure your Sign-In Account is locked for one (1) hour. \nThe returned data will indicate that your account is locked and the time in UTC that the account will be unlocked. \nIf you require the account to be unlocked on the LIVE system you may contact your Monoova representative and at his or her discretion they will unlock the account.\nSee the API routes in Security to manage Passwords and Tokens. <br><br>\n\n<h3> UserName/Password </h3>\nUsing this scenario, you can configure BASIC Authentication with the following <br> <br>\n<li> <strong> UserName </strong> - API Key (obtained from the <a href=\"https://sandbox.monoova.com/user/login\" target=\"_blank\">Sandbox Portal</a>) Production credentials will be supplied by Monoova when you have demonstrated successful implementation of the API on our Sandbox environment.</li>\n<li> <strong> Password </strong> - When using your API Key, no password is required. \nIf the key is compromised, it can be re-rolled via the <a href=\"https://sandbox.monoova.com/user/login\" target=\"_blank\">Sandbox Portal</a>. </li> <br>\n\n# Feedback\n\nWe value your feedback on our API. Please fill out the form <a href=\"https://ncv.microsoft.com/8eaKX3fsiJ\" target=\"_blank\">here</a> to share your feedback.\n"
  version: v5.29
  title: Monoova Payments Security 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.mpay.com.au
  description: Production URL
- url: https://api.m-pay.com.au
  description: Sandbox URL
security:
- BasicAuth: []
tags:
- name: Security
  description: <h3>  Overview </h3> <p> The security/v1 APIs allows you to manage security tokens. This gives you an alternative to using signIn API KEY for BASIC authentication for each API call. Security tokens come in two forms </p> <ul> <li> <strong> OneShotSecurityToken </strong> </li> <li> <strong> SecurityToken </strong> </li> </ul> <p> The two security tokens operate in exactly the same way. The token is used to replace your UserName when configuring BASIC Authentication. Should you provide a password anyway, it will be ignored. Each token type has an expiry time between 1 and 15 minutes. The expiry time cannot be extended. </p> <p> As the name implies, a OneShotSecurityToken can only be used once. The token is deleted on its first use or when it expires, whatever is sooner. </p> <p> A SecurityToken can be used multiple times until it expires. The expiry time of a SecurityToken can be extended. </p> <p> Please note that security tokens discussed in this section have nothing in common with the token/v1 APIs described elsewhere in this document. Security tokens provide secure sign-in from a web page; token/v1 APIs tokenize sensitive information. </p>
paths:
  /security/v1/createOneShotSecurityToken/{timeOutMin}:
    get:
      tags:
      - Security
      summary: Create OneShot security Token
      description: "This API returns a security token that can be used only once or until it expires. \nThe purpose of this token is that it can be embedded in a web form to enable you to make a single call to the Engine without exposing your Sign-In Account credentials.\nWhen setting your security credentials to call any of the APIs in this document (except for security/v1/createOneShotSecurityToken), \nset the Username to the returned OneShotSecurityToken and set the password to anything as it will be ignored.\n"
      operationId: SecurityCreateOneShotSecurityToken
      parameters:
      - name: timeOutMin
        in: path
        required: true
        description: Each token has an expiry time between 1 and 15 minutes
        schema:
          type: number
          example: 5
      - name: Claims
        in: query
        required: false
        description: This is Optional. Passing a 'Token' in parameter to generate restricted Token which only allows user to create Token. Currently Available parameters are 'Admin', 'Reporting' and 'Token'
        schema:
          type: string
          example: Token
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DTO.GenericPayment.CreateOneShotSecurityTokenResponse_V1'
        '400':
          description: Bad request
        '500':
          description: Internal Server Error
  /security/v1/signInAccountSettings:
    get:
      tags:
      - Security
      summary: Get Sign-in account fees & permissions
      description: This API returns the fees and permissions that have been given to the Sign-In Account.
      operationId: SecuritySignInAccountSettings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DTO.GenericPayment.SettingsResponse_V1'
        '400':
          description: Bad request
        '500':
          description: Internal Server Error
components:
  schemas:
    DTO.GenericPayment.loadFee_V1:
      properties:
        method:
          description: 'The type of Disbursement: mAccount, mWallet, DirectCredit, BPAY, Charity, Sign-In mAccount'
          type: string
          example: BPAY
          uniqueItems: false
        cardType:
          description: 'Type of credit card. Null if method is not CreditCard: Mastercard, Visa, Diners, Amex'
          type: string
          example: Amex
          uniqueItems: false
        debitFromMAccount:
          description: ' Contains the 16-Digit if the fee is associated to a specific mAccount, otherwise null'
          type: string
          example: 'null'
          uniqueItems: false
        feePercentageExGst:
          description: The percentage of the amountto be taken as a fee Excluding GST
          type: number
          format: decimal
          example: '3'
          uniqueItems: false
        feeFixedExGst:
          description: The fixed amount to be taken as a fee Excluding GST
          type: number
          format: decimal
          example: '0.25'
          uniqueItems: false
      type: object
    DTO.GenericPayment.CreateOneShotSecurityTokenResponse_V1:
      properties:
        durationMs:
          description: 'This value represents the total time in milliseconds that the Platform took to process the request. '
          type: integer
          format: int64
          example: 20
        status:
          description: This is the status of executing the request.&nbsp;A code of ‘Ok’ indicates no errors
          type: string
          example: Ok
        statusDescription:
          description: This is a plain English description of the status.
          type: string
          example: Operation completed successfully
        oneShotSecurityToken:
          description: The token to use instead of UserName
          type: string
          example: 2215125a-b80b-41aa-af58-740d21b303ed
      type: object
      format: DTO.GenericPayment.CreateOneShotSecurityTokenResponse_V1
    DTO.GenericPayment.disbursementFee_V1:
      properties:
        method:
          description: 'The type of Disbursement: mAccount, mWallet, DirectCredit, BPAY, Charity, Sign-In mAccount'
          type: string
          example: BPay
          uniqueItems: false
        feePercentageExGst:
          description: The percentage of the amountto be taken as a fee Excluding GST
          type: number
          format: decimal
          example: '0'
          uniqueItems: false
        feeFixedExGst:
          description: The fixed amount to be taken as a fee Excluding GST
          type: number
          format: decimal
          example: '0.4546'
          uniqueItems: false
      type: object
      format: DTO.GenericPayment.disbursementFee_V1
    DTO.GenericPayment.SettingsResponse_V1:
      properties:
        durationMs:
          description: 'This value represents the total time in milliseconds that the Platform took to process the request. '
          type: integer
          format: int64
          example: 20
        status:
          description: This is the status of executing the request.&nbsp;A code of ‘Ok’ indicates no errors
          type: string
          example: Ok
        statusDescription:
          description: This is a plain English description of the status.
          type: string
          example: Operation completed successfully
        disbursementFees:
          description: An array of DisbursementFeeDetail
          type: array
          items:
            $ref: '#/components/schemas/DTO.GenericPayment.disbursementFee_V1'
        loadFees:
          description: An array of LoadFeeDetai
          type: array
          items:
            $ref: '#/components/schemas/DTO.GenericPayment.loadFee_V1'
        canDebitCreditCards:
          description: True if the Sign-In Account has permission to debit/Refund credit cards
          type: boolean
          example: true
        canPayBpay:
          description: True if the Sign-In Account has permission to make PBAY payments
          type: boolean
          example: true
        canImpersonate:
          description: True if the Sign-In Account has permission to use the security/v1/createImpersonationTokenAsIssuer
          type: boolean
          example: true
        canDirectDebit:
          description: True if the Sign-In Account has permission to Direct Debit an ABA
          type: boolean
          example: true
        canDirectCredit:
          description: True if the Sign-In Account has permission to Direct Credit an ABA
          type: boolean
          example: true
        canCreateMAccounts:
          description: True if the Sign-In Account has permission to create mAccounts
          type: boolean
          example: true
        canCreateMWallets:
          description: True if the Sign-In Account has permission to create mWallets
          type: boolean
          example: true
        canAccessUserDatabase:
          description: True if the Sign-In Account has permission to access the User Database
          type: boolean
          example: true
        isIssuer:
          description: True if the Sign-In Account is an issuer
          type: boolean
          example: true
        issuerMAccountNumber:
          description: 16-digit Account number of Issuer.
          type: string
          example: '0000000000000000'
        monthlyFeeExGst:
          description: The monthly fee(ExGst) for the Sign-In Account
          type: number
          format: decimal
          example: '25'
        clearingMAccountNumber:
          description: 16-digit Account number of Sign-In Clearing Account
          type: string
          example: '6279059705699616'
        feeMAccountNumber:
          description: 16-Digit Account number of Fee Account if there is one
          type: string
          example: '6279059710265874'
        feeMAccountMonthlyFeeExGst:
          description: Monthly fee (ExGST) of the Sign-In Fee Account
          type: number
          format: decimal
          example: '2'
        childMAccountSetUpFeeExGst:
          description: Set-up fee (ExGST) for each mAccount created via mAccount/v1/create
          type: number
          format: decimal
          example: '0'
        childMAccountMonthlyFeeExGst:
          description: Monthly fee (ExGST) for each mAccount created vian mAccount/v1/create
          type: number
          format: decimal
          example: '5'
        requiresClearedFundsOnly:
          description: if 'true', acccount has set up as ClearedFunds
          type: boolean
          example: true
      type: object
      format: DTO.GenericPayment.SettingsResponse_V1
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
x-tagGroups:
- name: Receive and Pay
  tags:
  - Financial
  - Verify
  - Automatcher (Bank Account Receivables)
  - Whitelisting for Automatcher (Bank Account Receivables)
  - Ledger Account
  - Reconciliation Rules
  - PayID
  - Tools
- name: BPAY
  tags:
  - BPAY
  - mWallet
- name: Manage
  tags:
  - Subscriptions
  - Webhooks
  - mAccount
  - Reports
  - Security
  - Token
- name: Public Endpoints
  tags:
  - Public Endpoints