Monoova Token API

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 Token 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: Token
  description: <h3> Overview </h3> <p> Using tokens is a way of increasing the security around sensitive information. A token can be used to obfuscate debit and credit details. The details of a token (its payload) are stored encrypted on the Engine servers. The tokening system has been designed such the generated token has no mathematical or algorithmic connection to the secret data held as the payload. The token is a random number that is manifested as a GUID. Currently two types of payloads can be held within the tokening system </p> <ul> <li> Australian Bank Account </li> <li> BPAY details </li> </ul> <p> Other payload types can be added if required. For example, if you have asked the user to enter their bank-account details on your website you can use the security/v1/createOneShotSecurityToken API to embed an OneShotSecurityToken in your page. Using this OneShotSecurityToken you can call the appropriate token/v1/create API passing the details. This way, the customer’s payload details are never passed through your server. </p>
paths:
  /token/v1/createAustralianBankAccount:
    post:
      tags:
      - Token
      summary: Create bank account token
      description: This API creates a token representing an Australian Bank Account by passing a TokenAustralianBankAccountPayload class in the body.
      operationId: TokenCreateAustralianBankAccount
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/token.createAustralianBankAccount'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DTO.TokenCreateResponse_V1'
        '400':
          description: Bad request
        '500':
          description: Internal Server Error
  /token/v1/createBPAY:
    post:
      tags:
      - Token
      summary: Create BPAY token
      description: This API creates a token representing BPAY details by passing a TokenBPAYPayload class in the body.
      operationId: TokenCreateBPAY
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/token.createBPAY'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DTO.TokenCreateResponse_V1'
        '400':
          description: Bad request
        '500':
          description: Internal Server Error
  /token/v1/delete/{token}:
    delete:
      tags:
      - Token
      summary: Delete token
      description: This API will delete the payload attached to the specified token.
      operationId: TokenDelete
      parameters:
      - name: token
        in: path
        required: true
        description: The text (GUID) that identifies the token.
        schema:
          type: string
          example: 8c4df16a-78f1-4a1a-9500-357deb3310aa
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DTO.TokenDeleteResponse_V1'
        '400':
          description: Bad request
        '500':
          description: Internal Server Error
  /token/v1/get/{token}:
    get:
      tags:
      - Token
      summary: Get token details
      description: This API will return the payload attached to the specified token.
      operationId: TokenGet
      parameters:
      - name: token
        in: path
        required: true
        description: The text (GUID) that identifies the token.
        schema:
          type: string
          example: 8c4df16a-78f1-4a1a-9500-357deb3310aa
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DTO.TokenGetResponse_V1'
        '400':
          description: Bad request
        '500':
          description: Internal Server Error
  /token/v1/list/{accountNumber}:
    get:
      tags:
      - Token
      summary: List tokens by mAccount
      description: This API will return a list of all tokens associated with the provided mWallet or mAccount.
      operationId: TokenList
      parameters:
      - name: accountNumber
        in: path
        required: true
        description: 16-Digit account number that uniquely identifies the mAccount
        schema:
          type: string
          example: '6279059700023123'
          maxLength: 16
          minLength: 16
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DTO.TokenListResponse_V1'
        '400':
          description: Bad request
        '500':
          description: Internal Server Error
  /token/v1/updateAustralianBankAccount:
    post:
      tags:
      - Token
      summary: Update bank account token
      description: This API provides the ability to update the payload associated with an existing token. For this API, the payload to update is a TokenAustralianBankAccount class.
      operationId: TokenUpdateAustralianBankAccount
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/token.updateAustralianBankAccount'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DTO.TokenUpdateResponse_V1'
        '400':
          description: Bad request
        '500':
          description: Internal Server Error
  /token/v1/updateBPAY:
    post:
      tags:
      - Token
      summary: Update BPAY token
      description: This API provides the ability to update the payload associated with an existing token. For this API, the payload to update is a TokenBPAY class.
      operationId: TokenUpdateBPAY
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/token.updateBPAY'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DTO.TokenUpdateResponse_V1'
        '400':
          description: Bad request
        '500':
          description: Internal Server Error
  /token/v1/validate/{token}:
    get:
      tags:
      - Token
      summary: Validate token
      description: This API validates a token by passing a Token in the body.
      operationId: TokenValidate
      parameters:
      - name: token
        in: path
        required: true
        description: The text (GUID) that identifies the token.
        schema:
          type: string
          example: 8c4df16a-78f1-4a1a-9500-357deb3310aa
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DTO.TokenValidateResponse_V1'
        '400':
          description: Bad request
        '500':
          description: Internal Server Error
components:
  schemas:
    DTO.TokenDetails:
      properties:
        token:
          description: The text (GUID) that identifies the token
          type: string
          example: 0a4fe0d3-43c7-47ec-b089-4977cead9451
          uniqueItems: false
        hint:
          description: Text that gives sufficient information to allow the tokento be selected but does not compromise security
          type: string
          example: 'Bank: CBA Account: 12345678'
          uniqueItems: false
        payloadType:
          description: BPAY or AustralianBankAccount
          type: string
          example: BPAY
          uniqueItems: false
        description:
          description: Text supplied when the tokenwas created
          type: string
          example: Everyday use bank
          uniqueItems: false
      type: object
      format: DTO.TokenDetails
    DTO.TokenDeleteResponse_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
          uniqueItems: false
        status:
          description: This is the status of executing the request.&nbsp;A code of ‘Ok’ indicates no errors
          type: string
          example: Ok
          uniqueItems: false
        statusDescription:
          description: This is a plain English description of the status.
          type: string
          example: Operation completed successfully
          uniqueItems: false
      type: object
      format: DTO.TokenDeleteResponse_V1
    token.updateBPAY:
      type: object
      required:
      - accountNumber
      - tokenToUpdate
      - billerCode
      - customerReferenceNumber
      - amount
      properties:
        accountNumber:
          type: string
          uniqueItems: false
          example: '6279059700010827'
          description: The mWallet or mAccount 16-Digit number that owns the payload.
        tokenToUpdate:
          type: string
          uniqueItems: false
          example: 20c3a494-7010-4f22-babe-34d643e5e64f
          description: The text (GUID) that identifies the token.
        description:
          type: string
          uniqueItems: false
          example: Monthly Electricity Bill BPAY
          description: A simple text description that is associated with the token. For example “Monthly Electricity Bill BPAY”.
        billerCode:
          type: integer
          uniqueItems: false
          example: '857763'
          description: Biller Code as shown on the Bill. Must be a valid BPAY Biller on token creation.
        customerReferenceNumber:
          type: integer
          uniqueItems: false
          example: '6279059700010918'
          description: Customer Reference Number as shown on the Bill. Must be a valid BPAY Customer Reference Number on token creation
        amount:
          type: number
          format: decimal
          example: 100.0
          description: Amount as shown on the Bill. Must be a valid amount on token creation.
    DTO.TokenUpdateResponse_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
          uniqueItems: false
        status:
          description: This is the status of executing the request.&nbsp;A code of ‘Ok’ indicates no errors
          type: string
          example: Ok
          uniqueItems: false
        statusDescription:
          description: This is a plain English description of the status.
          type: string
          example: Operation completed successfully
          uniqueItems: false
        token:
          description: Token updated in the form of a GUID
          type: string
          example: 9395ddef-69cb-4f38-8836-3c6502c72182
          uniqueItems: false
        hint:
          description: Updated Text that gives sufficient information to allow the tokento be selected but does not compromise security
          type: string
          example: 'Bank: ANZ Account: 123456789'
          uniqueItems: false
      type: object
      format: DTO.TokenUpdateResponse_V1
    DTO.TokenValidateResponse_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
          uniqueItems: false
        status:
          description: This is the status of executing the request.&nbsp;A code of ‘Ok’ indicates no errors
          type: string
          example: Ok
          uniqueItems: false
        statusDescription:
          description: This is a plain English description of the status.
          type: string
          example: Operation completed successfully
          uniqueItems: false
      type: object
      format: DTO.TokenValidateResponse_V1
    DTO.TokenListResponse_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
          uniqueItems: false
        status:
          description: This is the status of executing the request.&nbsp;A code of ‘Ok’ indicates no errors
          type: string
          example: Ok
          uniqueItems: false
        statusDescription:
          description: This is a plain English description of the status.
          type: string
          example: Operation completed successfully
          uniqueItems: false
        tokens:
          description: An array of TokenDetails
          type: array
          items:
            $ref: '#/components/schemas/DTO.TokenDetails'
          uniqueItems: false
      type: object
      format: DTO.TokenListResponse_V1
    DTO.TokenCreateResponse_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
          uniqueItems: false
        status:
          description: This is the status of executing the request.&nbsp;A code of ‘Ok’ indicates no errors
          type: string
          example: Ok
          uniqueItems: false
        statusDescription:
          description: This is a plain English description of the status.
          type: string
          example: Operation completed successfully
          uniqueItems: false
        token:
          description: New token in the form of a GUID
          type: string
          example: 9395ddef-69cb-4f38-8836-3c6502c72182
          uniqueItems: false
        hint:
          description: Text that gives sufficient information to allow the token to be selected but does not compromise security
          type: string
          example: 'Bank: ANZ Account: 123456789'
          uniqueItems: false
      type: object
      format: DTO.TokenCreateResponse_V1
    DTO.TokenGetResponse_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
          uniqueItems: false
        status:
          description: This is the status of executing the request.&nbsp;A code of ‘Ok’ indicates no errors
          type: string
          example: Ok
          uniqueItems: false
        statusDescription:
          description: This is a plain English description of the status.
          type: string
          example: Operation completed successfully
          uniqueItems: false
        token:
          description: The text (GUID) that identifies the token
          type: string
          example: 0a4fe0d3-43c7-47ec-b089-4977cead9451
          uniqueItems: false
        hint:
          description: Text that gives sufficient information to allow the tokento be selected but does not compromise security
          type: string
          example: 'Bank: CBA Account: 1234567'
          uniqueItems: false
        payloadType:
          description: BPAY or AustralianBankAccount
          type: string
          example: BPAY
          uniqueItems: false
        description:
          description: Text supplied when the tokenwas created
          type: string
          example: mPayments Bank Account
          uniqueItems: false
      type: object
      format: DTO.TokenGetResponse_V1
    token.updateAustralianBankAccount:
      type: object
      required:
      - accountNumber
      - tokenToUpdate
      - bankAccountName
      - bankAccountNumber
      - bsb
      properties:
        accountNumber:
          type: string
          uniqueItems: false
          example: '6279059700010827'
          description: The mWallet or mAccount 16-Digit number that owns the payload.
        tokenToUpdate:
          type: string
          uniqueItems: false
          example: 9395ddef-69cb-4f38-8836-3c6502c72182
          description: The text (GUID) that identifies the token.
        description:
          type: string
          uniqueItems: false
          example: Savings Account
          description: A simple text description that is associated with the token. For example “Savings Account”.
        bankAccountName:
          type: string
          uniqueItems: false
          example: Monoova Bank Account
          minLength: 2
          description: Name associated with the bank account.
        bankAccountNumber:
          type: string
          example: '123456789'
          description: This is the bank account number.
        bsb:
          type: string
          uniqueItems: false
          example: 012-366
          description: Bank-State-Branch number. Format is 3-3 digits. (Eg.'000-000')
    token.createBPAY:
      type: object
      required:
      - accountNumber
      - billerCode
      - customerReferenceNumber
      - amount
      properties:
        accountNumber:
          type: string
          uniqueItems: false
          example: '6279059700010827'
          description: The mWallet or mAccount 16-Digit number that owns the payload.
        description:
          type: string
          uniqueItems: false
          example: Monthly Electricity Bill BPAY
          description: A simple text description that is associated with the token. For example “Monthly Electricity Bill BPAY”.
        billerCode:
          type: integer
          uniqueItems: false
          example: '857763'
          description: Biller Code as shown on the Bill. Must be a valid BPAY Biller on token creation.
        customerReferenceNumber:
          type: integer
          example: '6279059700010918'
          description: Customer Reference Number as shown on the Bill. Must be a valid BPAY Customer Reference Number on token creation.
        amount:
          type: number
          format: decimal
          example: 100.0
          description: Amount as shown on the Bill. Must be a valid amount on token creation.
    token.createAustralianBankAccount:
      type: object
      required:
      - accountNumber
      - bankAccountName
      - bankAccountNumber
      - bsb
      properties:
        accountNumber:
          type: string
          example: '6279059700010827'
          minLength: 16
          maxLength: 16
          description: The mWallet or mAccount 16-Digit number that owns the payload.
        description:
          type: string
          maxLength: 256
          uniqueItems: false
          example: Savings Account
          description: A simple text description that is associated with the token. For example “Savings Account”.
        bankAccountName:
          type: string
          uniqueItems: false
          minLength: 2
          example: Monoova Bank Account
          description: Name associated with the bank account. Minimum length is 2.
        bankAccountNumber:
          type: integer
          example: 123456789
          minimum: 1
          maximum: 999999999
          description: This is the bank account number. Range of '1' to '999999999'.
        bsb:
          type: string
          uniqueItems: false
          example: 012-366
          description: Bank-State-Branch number. Format is 3-3 digits. (Eg. '000-000')
  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