Monoova BPAY API

openapi: 3.2.0
info:
  description: '# Introduction


    Monoova has developed a powerful payments engine which allows you to receive, manage and pay funds in AUD in Australia automatically.'
  version: v5.29
  title: Monoova Payments BPAY 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: BPAY
  description: 'Overview

    The BPAY APIs do not perform any financial transactions and are used to validate BPAY information that is used in the /financial/v2/transaction/execute API.'
paths:
  /bpay/v1/validate/{billerCode}:
    get:
      tags:
      - BPAY
      summary: Validate a BPAY transaction
      description: 'This API validates the BPAY Biller Code and optionally the BPAY Customer Reference Number and Amount. For a complete BPAY validation the BPAY Biller Code, BPAY Customer Reference Number and Amount must be supplied. When fully validated a BPAY financial transaction should be made as soon as practicable as some BPAY combinations are date sensitive. BPAY validation uses the BPAY subsystem error codes.

        Sample URL: https://api.mpay.com.au/bpay/v1/validate/{billerCode}?custRef={CRN}&amount={amount}'
      operationId: BPAYValidate
      parameters:
      - name: billerCode
        in: path
        required: true
        description: This is the BPAY biller code that was requested. billerCode must be numeric
        schema:
          type: string
          example: '857763'
          maxLength: 10
      - name: custRef
        in: query
        required: false
        description: BPAY Customer Reference Number. If this field is empty this denotes that the customerReferenceNumber is variable for each bill and should not be reused.
        schema:
          type: string
          example: '6279059700000505'
          maxLength: 20
      - name: amount
        in: query
        required: false
        description: Bill amount to be validated. <strong> Note if CustRef is not provided, amount will not validate as it is dependent on both the CRN and Biller. </strong> The maximum value of the field is $9999999999.99.
        schema:
          type: number
          example: '100'
          maxLength: 13
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DTO.ValidateBPAYResponse_V1'
        '400':
          description: Bad request
        '500':
          description: Internal Server Error
  /bpay/v1/biller/{billerCode}:
    get:
      tags:
      - BPAY
      summary: Get BPAY biller code details
      description: This API returns extended information for the BPAY biller. Status will be “UnknownBillerCode” if Biller Code is invalid.
      operationId: BPAYGetBiller
      parameters:
      - name: billerCode
        in: path
        required: true
        description: This is the BPAY biller code that was requested. billerCode must be numeric
        schema:
          type: string
          example: '857763'
          maxLength: 10
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DTO.BPAYBillerResponse_V1'
        '400':
          description: Bad request
        '500':
          description: Internal Server Error
  /bpay/v1/receipts:
    post:
      tags:
      - BPAY
      summary: Get BPAY receipts
      description: 'This API returns the list of BPAY receipts.

        Note: Filters - One of the below options should be provided by customer.

        1) uniqueReferenceNumber

        2) billerCode + referenceNumber + date'
      operationId: BPAYGetReceipts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/bpay.receipts'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DTO.BPAYReceiptResponse_V1'
        '400':
          description: Bad request
        '500':
          description: Internal Server Error
  /bpay/v1/billers:
    get:
      tags:
      - BPAY
      summary: Search for BPAY billers
      description: This API returns an array of BPAY billers matched to the case insensitive search string. The system matches on the billerLongName and billerShortName. Use skip and take to page through result set. Skip and take will be changed back to their defaults if they are over-range. Status will be “UnknownBillerCode” if there are no matches.
      operationId: BPAYGetBillers
      parameters:
      - name: search
        in: query
        required: false
        description: The search string
        schema:
          type: string
          example: pty%20ltd
      - name: skip
        in: query
        required: false
        description: The actual number of records skipped.
        schema:
          type: number
          example: '0'
      - name: take
        in: query
        required: false
        description: The number of records that were requested.
        schema:
          type: number
          example: '50'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DTO.BPAYBillersResponse_V1'
        '400':
          description: Bad request
        '500':
          description: Internal Server Error
  /bpay/v1/history/{accountNumber}:
    get:
      tags:
      - BPAY
      summary: Get a wallet's BPAY History
      description: This API returns the mWallets history of BPAY payments. The returned history list is sorted by the count property of the BPAYHistoryItem descending.
      operationId: BPAYGetHistory
      parameters:
      - name: accountNumber
        in: path
        required: true
        description: associated 'mWallet' 16 digit number
        schema:
          type: integer
          example: 6279059700022400
          maxLength: 16
          minLength: 16
      - name: take
        in: query
        required: false
        description: The number of records that were requested.
        schema:
          type: integer
          example: '50'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DTO.BPAYHistoryResponse_V1'
        '400':
          description: Bad request
        '500':
          description: Internal Server Error
  /bpay/v1/bpayInReport/{date}:
    get:
      tags:
      - BPAY
      summary: BPAY Receivables Report
      description: 'Returns a report of all received BPAY transactions for the day with associated details. If requested multiple times on the current date (calendar day, AEDT), the report is cumulative. E.g. if, on the same day, a report is requested at 10am and another one at 1pm, the report at 1pm will contain all the transactions already contained in the 10am report, in addition to any new transactions.


        The report is an application/octet-stream, columns are comma separated. Where a comma(,) or double quote(") is present in any of the below fields, the field will be encased in double quotes and/or escaped as per RFC4180

        Columns are as follows: .tb { table-layout:auto; width:100px;!important } .td { overflow:hidden; white-space:nowrap; text-overflow:ellipsis; !important}


        Transaction Id Batch Id BPAY Settlement Date Payment Accepted DateTime Payment Type Payer Institution Code Payer State Biller Code Customer Reference Number Payment Method Amount Transaction Reference Number


        Monoova generated Unique ID.

        Integer.


        Payment Batch ID.

        Payments come in batches

        throughout the day.

        Integer.

        AEDT, Sydney.

        Max 27 chars. AEDT, Sydney.

        Max 27 chars. Possible values:

        ''Payment'', ''Error Correction'', ''Reversal''. PayerInstitutionCode.

        Max 3 chars. PayerState

        Max 3 chars. BillerCode

        Max 10 chars. CustomerReferenceNumber

        Max 20 chars. PaymentMethod

        Max 3 chars.

        Amount,

        2 decimal places

        for cents. Max 12 chars. TransactionReferenceNumber.

        Max 21 chars.'
      operationId: BPAYReceivablesReport
      parameters:
      - name: date
        in: path
        required: true
        description: Format:&nbsp; 'yyyy-MM-dd'. The date for which Monoova received the BPAY Receivable transactions.
        schema:
          type: string
          example: '2020-11-01'
      - name: skip
        in: query
        required: false
        description: Number of records to skip. 1 is the first record.
        schema:
          type: integer
          example: 1
      - name: take
        in: query
        required: false
        description: Number of records to take.
        schema:
          type: integer
          example: 100
      responses:
        '200':
          description: OK
          content:
            text/plain:
              examples:
                response:
                  value: 'Transaction Id,Batch Id,BPAY Settlement Date,Payment Accepted DateTime,Payment Type,Payer Institution Code,Payer State,Biller Code,Customer Reference Number,Payment Method,Amount,Transaction Reference Number,Receipt Number

                    10557123,57,2020-11-02T00:00:00,2020-11-02T19:58:06,Payment,CBA,NSW,857763,100014080495384,DebitAccount,20000.00,CBA202011020140276714,5678120

                    '
        '400':
          description: Bad request
        '500':
          description: Internal Server Error
components:
  schemas:
    DTO.BPAYHistoryResponse_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
        history:
          type: array
          items:
            $ref: '#/components/schemas/DTO.BPayHistoryItem_V1'
          uniqueItems: false
      type: object
    DTO.BPAYReceiptResponse_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
        receipts:
          type: array
          items:
            $ref: '#/components/schemas/DTO.BPAYReceipt_V1'
          uniqueItems: false
      type: object
    bpay.receipts:
      type: object
      oneOf:
      - required:
        - date
        - billerCode
        - referenceNumber
      - required:
        - uniqueReferenceNumber
      properties:
        uniqueReferenceNumber:
          type: string
          example: 77 106 249 852
          description: This is a unique reference generated by the calling service. This is a nonce. Its use is to determine if a request has already been received by the Engine. We strongly recommend sending a uniqueReference in your execution call to avoid duplicate transactions.
          maxLength: 200
        date:
          type: string
          example: '2020-11-01'
          description: The date for which Monoova received the BPAY Receivable transactions. "yyyy-MM-dd" format.
        billerCode:
          description: This is the BPAY biller code that was requested. billerCode must be numeric.
          type: string
          example: '857763'
        referenceNumber:
          type: integer
          example: '6279059700010918'
          description: Reference Number as shown on the Bill. Must be a valid BPAY Customer Reference Number on token creation.
    DTO.BPAYBillersResponse_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
        search:
          description: Text string to search for
          type: string
          example: pty ltd
          uniqueItems: false
        totalCount:
          description: The total number of BPAYBiller’s that match the search criteria
          type: integer
          format: int32
          example: 4984
          uniqueItems: false
        skip:
          description: The search string
          type: integer
          format: int32
          example: 0
          uniqueItems: false
        take:
          description: The number of records that were requested
          type: integer
          format: int32
          example: 50
          uniqueItems: false
        billers:
          type: array
          items:
            $ref: '#/components/schemas/DTO.BPAYBiller_V1'
          uniqueItems: false
      type: object
    DTO.BPayHistoryItem_V1:
      properties:
        billerCode:
          description: BPAY Biller code
          type: string
          example: '23796'
          uniqueItems: false
        customerReferenceNumber:
          description: BBPAY Customer Reference Number. If this field is empty this denotes that the customerReferenceNumber is variable for each bill and should not be reused
          type: string
          example: '2000046986210'
          uniqueItems: false
        billerName:
          description: Long form of the BPAY Biller Name
          type: string
          example: TELSTRA CORPORATION LTD
          uniqueItems: false
        count:
          description: The number of usages of these detailsthat the mWallet has succeeded in paying previously
          type: integer
          format: int32
          example: '27'
          uniqueItems: false
      type: object
    DTO.ValidateBPAYResponse_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
        validation:
          $ref: '#/components/schemas/DTO.BPAYValidation_V1'
      type: object
      format: DTO.ValidateBPAYResponse_V1
    DTO.BPAYReceipt_V1:
      properties:
        billerCode:
          description: This is the BPAY biller code that was requested. billerCodemust be numeric
          type: string
          example: '123451'
          uniqueItems: false
        billerName:
          description: This is the BPAY biller long name associated with the billerCode
          type: string
          example: PTY LTD
          uniqueItems: false
        receiptNumber:
          description: BBPAY receipt Number.
          type: string
          example: '12334123'
          uniqueItems: false
        referenceNumber:
          description: BBPAY Customer Reference Number. If this field is empty this denotes that the customerReferenceNumber is variable for each bill and should not be reused
          type: string
          example: '1223451324343434'
          uniqueItems: false
        status:
          description: Status of BPAY receipts
          type: string
          example: Paid
          uniqueItems: false
        transactionDateTime:
          description: 'The date time that the transaction was executed on the Platform Servers. Format is ISO8601 - 2015 -09 - 01T19: 19:58'
          type: string
          example: '2022-05-09T13:11:38'
          uniqueItems: false
        voidDateTime:
          description: The date time that the transaction was void on the Platform Servers
          type: string
          example: ''
          uniqueItems: false
      type: object
    DTO.BPAYBiller_V1:
      properties:
        billerCode:
          description: This is the BPAY biller code that was requested. billerCodemust be numeric
          type: string
          example: '857763'
          uniqueItems: false
        billerLongName:
          description: A long description of the billername
          type: string
          example: Monoova FINANCE PTY LTD
          uniqueItems: false
        billerShortName:
          description: A short decription of the billername
          type: string
          example: Monoova
          uniqueItems: false
        acceptedPaymentMethods:
          description: Must be set to “1”. Field reserved for future expansion
          type: string
          example: '1'
          uniqueItems: false
        activationDate:
          description: Date this biller was activated for BPAY. ISO 8601 date format with time set to 00:00:00. Note that Timezone is suppressed.The example Timezone is Sydney local time
          type: string
          example: '2013-05-29T00:00:00'
          uniqueItems: false
        deactivationDate:
          description: Date this biller was deactivated for BPAY. ISO 8601 date format with time set to  00:00:00 or an empty string if not deactivated.Note that Timezone is suppressed.The example Timezone is Sydney local time
          type: string
          example: ''
          uniqueItems: false
        minPaymentAmount:
          description: This is the minimum amount that the BPAY biller associated with the billerCodeaccepts for bill payment
          type: number
          format: decimal
          example: 10
          uniqueItems: false
        maxPaymentAmount:
          description: This is the maximum amount that the BPAY biller associated with the billerCodeaccepts for bill payment
          type: number
          format: decimal
          example: 100000
          uniqueItems: false
        crnValidationRuleName:
          description: For internal use only. Set to an empty string
          type: string
          example: ''
          uniqueItems: false
        checkDigitRuleName:
          description: For internal use only. Set to an empty string
          type: string
          example: ''
          uniqueItems: false
        lengthMask:
          description: A mask in which the position of each ‘Y’ character indicates each valid length that the reference number can take.At least one ‘Y’ character will be present
          type: string
          example: '               Y    '
          uniqueItems: false
        fixedDigits:
          description: This describes which, if any, fixed digits that are standard in the BPAY Customer Reference Number
          type: string
          example: '627905              '
          uniqueItems: false
        isVariableCrn:
          description: 'Indicates whether BPAY Customer Reference Numbers (CRN) for this billerchanges for each individual customer’s bill or do they remain the same.Non variable CRNs can be stored and used later, however they must always be validated as part of paying a bill via the gateway.Variable CRNs should not be stored as they are incorrect for subsequent bills. '
          type: boolean
          example: false
          uniqueItems: false
      type: object
    DTO.BPAYBillerResponse_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
        biller:
          $ref: '#/components/schemas/DTO.BPAYBiller_V1'
      type: object
    DTO.BPAYValidation_V1:
      properties:
        billerCode:
          description: This is the BPAY biller code that was used to validate. billerCode must be numeric
          type: string
          example: '857763'
          uniqueItems: false
        customerReferenceNumber:
          description: This is the BPAY customer reference number that was used to validate. customerReferenceNumber must be numeric
          type: string
          example: '6279059700000505'
          uniqueItems: false
        amount:
          description: This is the amount that was used to validate. The maximum value of the field is $9999999999.99 however BPAY Billers will generally restrict the maximum value accepted for bill payment
          type: string
          example: '100'
          uniqueItems: false
        billerName:
          description: This is the BPAY biller long name associated with the billerCode
          type: string
          example: Monoova FINANCE PTY LTD
          uniqueItems: false
        isVariableCrn:
          description: Indicates whether BPAY Customer Reference Numbers(CRN) for this biller change for each individual customer’s bill or do they remain the same.Non variable CRNs can be stored and used later, however they must always be validated as part of paying a bill via the gateway.Variable CRNs should not be stored as they are incorrect for subsequent bills.
          type: boolean
          example: false
          uniqueItems: false
        minimumPaymentAmount:
          description: This is the minimum amount that the BPAY biller associated with the billerCode accepts for bill payment
          type: number
          format: decimal
          example: 10
          uniqueItems: false
        maximumPaymentAmount:
          description: This is the maximum amount that the BPAY biller associated with the billerCode accepts for bill payment
          type: number
          format: decimal
          example: 100000
          uniqueItems: false
      type: object
  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