openapi: 3.2.0 info: description: "# Introduction\n\n

\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

\n

\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

\n

\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

\n

\n The sandbox environment is open to everyone who signs up on our Sandbox Portal 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

\n

\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

\n

\n

Note: Please note we do not accept TLS 1.0 or 1.1 connections

\n\n# Getting started\n>\n - Sign on to our Sandbox Portal\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 - API KEY \n - OneShotSecurityToken

\n\n> **Sandbox Authentication Credentials**\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
FieldValue
UsernameAPI Key (obtained from the Sandbox Portal)
Passwordleave blank when using API key; Monoova will provide password for OneShotSecurityToken
Base URLhttps://api.m-pay.com.au/

\n\n> **Live Authentication Credentials**\nThis will be provided by Monoova after a technical review.
\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
FieldValue
UsernameAPI Key (obtained from the Production Portal; Production credentials will be supplied by Monoova)
Passwordleave blank when using API key; Monoova will provide password for OneShotSecurityToken
Base URLhttps://api.mpay.com.au/

\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.

\n\n

UserName/Password

\nUsing this scenario, you can configure BASIC Authentication with the following

\n
  • UserName - API Key (obtained from the Sandbox Portal) Production credentials will be supplied by Monoova when you have demonstrated successful implementation of the API on our Sandbox environment.
    • \n
  • Password - When using your API Key, no password is required. \nIf the key is compromised, it can be re-rolled via the Sandbox Portal.

    • \n\n# Feedback\n\nWe value your feedback on our API. Please fill out the form here to share your feedback.\n" version: v5.29 title: Monoova Payments Whitelisting for Automatcher (Bank Account Receivables) 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: Whitelisting for Automatcher (Bank Account Receivables) description:

    Overview

    This feature enables whitelisting of bank accounts when receiving funds in automatcher accounts. Funds received from a non-whitelisted account will be automatically returned. Using this feature, funds received can be limited to pre-approved bank accounts only.

    There are 2 criteria that can be set when whitelisting bank account numbers.

    Inbound transaction will only be accepted from: 

    1. An account that matches a whitelisted account name; AND/OR
    2. An account that matches a whitelisted BSB and account number

    If pre-defined criteria are not met, the transaction will be returned to the sender automatically. If enabled, each automatcher account has its own separate whitelist.

    You have the option to establish a webhook subscription to receive a notification when a payment is declined as a result of whitelist restrictions.

    To subscribe to a webhook use the Subscriptions APIs. Event name:  InboundDirectCreditRejections

    paths: /receivables/v1/whitelisting/create: post: tags: - Whitelisting for Automatcher (Bank Account Receivables) summary: Create Whitelist Source Account description: Use this API to create a new whitelist entry for an automatcher account. Multiple source bank account numbers or bank account names can be whitelisted against each Automatcher number. The system will automatically return payments if the payment details do not match one of the entries.

    Make sure to set the account status to “Enabled” to accept payments for the set of rules defined, the status can always be updated if the rule no longer applies using the update endpoint.
    operationId: ReceivablesCreateWhitelistSourceAccount requestBody: content: application/json: schema: $ref: '#/components/schemas/receivables.createWhiteListingAccount' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/receivablesCreateWhiteListingAccountResponse_V1' '400': description: Bad request '500': description: Internal Server Error /receivables/v1/whitelisting/update: post: tags: - Whitelisting for Automatcher (Bank Account Receivables) summary: Update Whitelist Source Account description: Use this endpoint to change the status of a whitelisted source account. operationId: ReceivablesUpdateWhitelistSourceAccount requestBody: content: application/json: schema: $ref: '#/components/schemas/receivables.updateWhiteListingAccount' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/receivablesUpdateWhiteListingAccountResponse_V1' '400': description: Bad request '500': description: Internal Server Error /receivables/v1/whitelisting/list/{automatcherBankAccountNumber}: get: tags: - Whitelisting for Automatcher (Bank Account Receivables) summary: List Whitelist Source Accounts description: This endpoint will list all whitelisted source account details linked to the queried Automatcher account number. operationId: ReceivablesListWhitelistSourceAccounts parameters: - name: automatcherBankAccountNumber in: path required: true description: Valid receivables bank account number belonging to the Sign-in mAccount. schema: type: string example: '311673871' - name: bsb in: query required: false description: Optional BSB parameter specifying the branch identifier for Australian banks. Accepts either 6 digits or with a hyphen as "XXX-XXX". If not specified, the service will use the MAccount’s configured ‘Default BSB’. If a ‘Default BSB’ has not been configured, then the Monoova ‘Default BSB’ will be used. schema: type: string maxLength: 7 example: 802-985 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/receivablesGetWhiteListingAccountsResponse_V1' '400': description: Bad request '500': description: Internal Server Error /receivables/v2/rejectedTransactions/{startDate}: get: tags: - Whitelisting for Automatcher (Bank Account Receivables) summary: Rejected Transactions Report description: Returns a report of all rejected transactions for the day with associated details, this includes Direct Entry and NPP Receivables. If requested multiple times on the current date (calendar day, AEDT), the report is cumulative.
    ID Batch ID Datetime BSB AccountNumber AccountName PayId PayId Name TransactionCode TransactionType Amount LodgementRef RemitterName Indicator WithholdingTaxAmount (if applicable) EndToEndId NameOfUserSupplyingFile NumberOfUserSupplyingFile DescriptionOfEntriesOnFile Reason Status SourceBsb SourceAccountNumber SourceAccountName ReconciliationRuleReference


    Monoova generated
    Unique ID.
    Max 12 chars.


    		Payment Batch ID.
    Payments come in batches
    throughout the day.
    Max 12 chars. Blank if NPP.     		AEDT, Sydney.
    Max 27 chars.     		Payee BSB.
    Max 7 Chars.     		Payee Bank Account
    Number. Max 34 chars.     		Payer submitted Account
    Name. Max 32 chars.     		Email address for the PayID.
    Max 256 chars.     		Name displayed to the payers
    Max 140 chars.     		Industry standard transaction
    code. “50” for credit.
    Refer to Direct entry standard
    for definitions 51-57.
    Max 5 chars.     		Possible Values:
    'DE' or 'NPP'
    		Payment amount,
    2 decimal places
    for cents. Max 11 chars.     		Payer submitted reference.
    Max 280 chars.     		Remitting Entity.
    Max 140 chars.     		Blank; OR 'W' dividend paid to a
    resident of a country where a double
    tax agreement is in force. 'X' dividend
    paid to a resident of any other country.
    'Y' interest paid to all non-resident.
    Max 1 chars.     		Blank OR Payment amount,
    2 decimal places for cents.
    Max 9 chars.     		Osko End to End identifier
    submitted by Payer.     		Preferred name of the
    User supplying
    the Direct Entry file.     		This is the User Identification
    Number which is assigned by
    APCA and User Financial Institutions.     		Direct Entry file description.
    		Reason for the rejection.
    		Transaction Status.
    		Payer BSB.
    Max 7 Chars.

    		 Payer Bank Account Number.
    Max 34 chars.
    		This field appears for NPP transactions
    only and is the payers bank account name.
    For DE transactions please refer to the
    RemitterName Field. Max 140 Chars.
    		A unique reference used to identify the reconciliation rule.
    Unique to your mAccount.
    string <= 35 characters ^[A-Za-z0-9-_]{1,35}$
    Example. RR22348

    Note:  Source account details do not appear by default, please contact Monoova for further information


    Possible transaction codes

    Code Transaction Description
    13 Externally initiated debit items
    50 Externally initiated credit items with the exception of those bearing Transaction Codes
    51 Australian Government Security Interest
    52 Family Allowance
    53 Pay
    54 Pension
    55 Allotment
    56 Dividend
    57 Debenture/Note Interest

    operationId: ReceivablesRejectedTransactionsReport parameters: - name: startDate in: path required: true description: date format should be 'yyyy-MM-dd' format. schema: type: string example: '2020-03-15' - name: endDate in: query required: false description: End date of the range for the report, format 'yyyy-MM-dd'. If not provided, data for the day specified in Start Date will be returned. schema: type: string example: '2020-03-31' - name: transactionType in: query required: false description: Filter for the transaction type. Possible values are 'DE' or 'NPP'. schema: type: string example: DE - name: pageNumber in: query required: false description: Page number for pagination. Defaults to 1 if not provided. schema: type: integer example: 1 - name: pageSize in: query required: false description: The number of items to return per page. Defaults to 50 if not provided. Maximum allowed is 200. schema: type: integer minimum: 1 maximum: 200 example: 50 responses: '200': description: OK content: text/plain: examples: response: value: 'Id, Batch Id, DateTime, BSB, AccountNumber, AccountName, PayId, PayId Name, TransactionCode, TransactionType, Amount, LodgementRef, RemitterName, Indicator, WithholdingTaxAmount, EndToEndId, NameOfUserSupplyingFile, NumberOfUserSupplyingFile, DescriptionOfEntriesOnFile, Reason, Status, SourceBsb, SourceAccountNumber, SourceAccountName,ReconciliationRuleReference 1,448715,2020-09-18T14:28:07,802-985,212409870,test,,,50,NPP,9.9900,test,test,,0,TEST_NPP_RAP_MTP,,,,Non Whitelisted Source Account,Pending Return,802-985,817371467,test,RR22348 ' '400': description: Bad request '500': description: Internal Server Error components: schemas: receivablesCreateWhiteListingAccountResponse_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. 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 automatcherBankAccountNumber: description: Valid receivables bank account number belonging to the Sign-in mAccount. type: string example: '311673871' sourceAccount: description: Object containing source account details type: object properties: accountName: description: 'This value represents the total time in milliseconds that the Platform took to process the request. ' type: string example: Monoova Source Account Name accountNumber: description: 3 to 9 digits. type: string example: '123456789' accountStatus: description: This is a plain English description of the status. enabled/disabled. type: string example: enabled bsbNumber: description: 6 digits with a '-'. type: string example: 802-985 id: description: identifier for whiteList sourceAccount type: integer example: 107 type: object receivablesUpdateWhiteListingAccountResponse_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. 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 automatcherBankAccountNumber: description: Valid receivables bank account number belonging to the Sign-in mAccount. type: string example: '311673871' sourceAccount: description: Object containing source account details type: object properties: accountName: description: 'This value represents the total time in milliseconds that the Platform took to process the request. ' type: string example: Monoova Source Account Name accountNumber: description: 3 to 9 digits. type: string minLength: 3 maxLength: 9 example: '123456789' accountStatus: description: This is a plain English description of the status. enabled/disabled. type: string example: disabled bsbNumber: description: 6 digits with a '-'. type: string example: 802-985 id: description: identifier type: integer example: 107 type: object receivables.updateWhiteListingAccount: type: object required: - automatcherBankAccountNumber properties: automatcherBankAccountNumber: type: string minLength: 9 maxLength: 9 example: '311673871' description: Valid receivables bank account number belonging to the Sign-in mAccount. automatcherBsb: type: string example: 802-985 description: Optional BSB parameter specifying the branch identifier for Australian banks. Accepts either 6 digits or with a hyphen as "XXX-XXX". If not specified, the service will use the MAccount’s configured ‘Default BSB’. If a ‘Default BSB’ has not been configured, then the Monoova ‘Default BSB’ will be used. sourceAccount: description: This is the sourceAccount type: object required: - id - accountStatus properties: accountName: description: String of max 140 chars. type: string example: Monoova Source Account Name accountNumber: description: 3 to 9 digits. type: string minLength: 3 maxLength: 9 example: '123456789' accountStatus: description: This is a plain English description of the status. enabled/disabled. type: string example: disabled enum: - enabled - disabled bsbNumber: description: 6 digits with a '-'. type: string example: 802-985 id: description: identifier for whiteList sourceAccount type: integer example: 107 receivablesGetWhiteListingAccountsResponseArrayItem2: type: object description: Object containing source account details properties: accountName: description: 'This value represents the total time in milliseconds that the Platform took to process the request. ' type: string example: Monoova Source Account Name accountNumber: description: 3 to 9 digits. type: integer example: 987654321 accountStatus: description: This is a plain English description of the status. enabled/disabled. type: string example: enabled bsbNumber: description: 6 digits with a '-'. type: string example: 802-985 id: description: identifier for whiteList sourceAccount type: integer example: 108 receivablesGetWhiteListingAccountsResponse_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. 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 automatcherBankAccountNumber: description: Valid receivables bank account number belonging to the Sign-in mAccount. type: string example: '311673871' sourceAccount: description: Object containing source account details type: array items: allOf: - $ref: '#/components/schemas/receivablesGetWhiteListingAccountsResponseArrayItem1' - $ref: '#/components/schemas/receivablesGetWhiteListingAccountsResponseArrayItem2' receivablesGetWhiteListingAccountsResponseArrayItem1: type: object description: Object containing source account details properties: accountName: description: 'This value represents the total time in milliseconds that the Platform took to process the request. ' type: string example: Monoova Source Account Name accountNumber: description: 3 to 9 digits. type: integer example: 123456789 accountStatus: description: This is a plain English description of the status. enabled/disabled. type: string example: disabled bsbNumber: description: 6 digits with a '-'. type: string example: 802-985 id: description: identifier for whiteList sourceAccount type: integer example: 107 receivables.createWhiteListingAccount: type: object required: - automatcherBankAccountNumber properties: automatcherBankAccountNumber: type: string minLength: 9 maxLength: 9 example: '311673871' description: Valid receivables bank account number belonging to the Sign-in mAccount. automatcherBsb: type: string example: 802-985 description: Optional BSB parameter specifying the branch identifier for Australian banks. Accepts either 6 digits or with a hyphen as "XXX-XXX". If not specified, the service will use the MAccount’s configured ‘Default BSB’. If a ‘Default BSB’ has not been configured, then the Monoova ‘Default BSB’ will be used. sourceAccount: description: This is the sourceAccount type: object properties: bsbNumber: type: string example: 802-985 description: 6 digits with a '-'.
    `at least one of BSB/AccountNumber or AccountName is required` accountNumber: type: string minLength: 3 maxLength: 9 example: '123456789' description: 3 to 9 digits.
    `at least one of BSB/AccountNumber or AccountName is required` accountName: type: string maxLength: 140 example: Monoova Source Account Name description: String of max 140 chars. Not case sensitive.
    `at least one of BSB/AccountNumber or AccountName is required` accountStatus: type: string enum: - enabled - disabled default: enabled example: enabled description: enabled/disabled. Default to enabled. 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