Bill Onboarding

Monoova's onboarding API flow is modular and lightweight. It allows you to verify a business and its associated individuals (UBOs) without the need to manage application states or workflows. Simply submit the business, retrieve detected individuals, verify them, and continue through to activation. This guide walks you through verifying your business, provisioning your ledger, and enabling PayID and PayTo.

How It Works

Verify business and individuals via KYB
Create a Ledger
Register a PayID against the Ledger
Create a PayTo Agreement for account funding
Check Agreement Status

Each step can be tested in Monoova’s sandbox environment.

Step 1: Business and Individual Verification with Monoova KYB API

Base URL: https://dev-api.monoova.com

Monoova’s KYB (Know Your Business) API fits seamlessly into your onboarding flow, verifying businesses and individuals without needing to manage application states.

Authenticate and Get Token

Use your API key to retrieve a 24-hour bearer token for all other KYB steps.

Endpoint: POST /kyb/auth/token

Headers:

Accept: application/json Content-Type: application/json apikey: YOUR_API_KEY

Create and Verify Business Entity

Submit the business details to begin KYB verification.

Endpoint: POST /kyb/v1/CreateVerifyEntity

Request Body:

{ "companyName": "Example Pty Ltd", "registrationNumber": "1122334455", "country": "AUS", "sourceKey": "InternalID_123", "externalUserId": ["user123"] }

The response will return an applicantId. This identifier is required for all subsequent KYB steps.

Polling for Verification Completion

Endpoint: POST /kyb/v1/EntityStatus

Request Body:

{ "applicantId": "your_applicant_id" }

Poll every 2–3 minutes until the status is Completed.

Retrieve UBOs

After the entity is verified, retrieve the beneficial owners (UBOs) detected by Monoova.

Endpoint: POST /kyb/v1/RetrieveUbos

Request Body:

{ "applicantId": "your_applicant_id" }

Example Response:

{ "ownershipInsight": { "parentEntity": "1749164367937x165083117408993500", "applicantId": "null", "uboType": "Individual", "name": "ANNETTE JOY KRUGER", "detectedPosition": ["Sole Trader"], "inputtedPosition": "null", "address": "", "registrationNumber": "null", "shares": [], "shareClass": [] } }

Each UBO returned here must be submitted individually for verification in the next step.

Create and Verify Individual(s)

Submit each UBO for identity verification.

Endpoint: POST /kyb/v1/CreateVerifyInd

Request Body:

{ "email": "[email protected]", "phone": "0400000000", "firstName": "ANNETTE", "middleName": "JOY", "lastName": "KRUGER", "dob": "1985-10-27", "idNumber": "1234567A", "sourceCountry": "AUS", "street": "123 EXAMPLE LANE", "city": "BRISBANE", "stateTerritory": "QUEENSLAND", "postCode": "4610", "country": "AUS" }

Poll POST /kyb/v1/IndStatus every 2–3 minutes using the applicantId.

Once all individuals are verified, the applicantId is eligible to provision a ledger and enable payments.

Step 2: Create a Monoova Ledger - Full Docs

Use your verified applicantId to provision a ledger account.

This API uses basic auth using your sandbox API key as username

Endpoint: POST https://api.m-pay.com.au/ledger/v1/create

Request Body:

{ "ledgerUniqueReference": "1749164367937x165083117408993500", "abn": "38210198813", "name": "BOB SMITH", "description": "ABCD Corp Pay", "automatcherDetails": { "bankAccountName": "Business Account" } }

Store the following values for future steps:

ledgerAccountNumber
automatcherDetails.bsb
automatcherDetails.bankAccountNumber

These are used in all Transaction requests as either the payer (payout) or payee (inbound).

Step 3: Register PayID - Full Docs

Enable PayID on the ledger to receive instant payments.

Endpoint: POST https://api.m-pay.com.au/receivables/v1/payid/registerpayid

Request Body:

{ "bankAccountNumber": "714038466", "bsb": "802-985", "payIdName": "John Smith", "payId": "" }

Leave payId blank to auto-generate one like [email protected]. You can provide a custom PayID like @abccorp.com after Monoova enables it.

Store the PayID for displaying to customers.

Step 4: Generate a Bearer Token (PayTo) - Full Docs

Generate a 24-hour bearer token for use with the PayTo API.

This API uses basic auth with your sandbox mAccount as username and sandbox APIKey as password.

Endpoint: POST https://sand-api.monoova.com/au/security/oauth-v1/Token

Authentication:

Username: Your mAccount number from portal
Password: Your API key from portal

Returns a Bearer token for use with PayTo endpoints.

Step 5: Create a PayTo Agreement - Full Docs

Endpoint: POST https://sand-api.monoova.com/au/payto/pam-v1/PaymentAgreement

Request Body:

{ "paymentAgreementUID": "BobsBuilders1", "payeeDetails": { "payeeLinkedBsb": "802-985", "payeeLinkedAccount": "917567642" }, "payerDetails": { "payerType": "ORGN", "linkedBsb": "802950", "linkedAccount": "22090100", "payer": "Bobs Builders", "ultimatePayer": "ABCCORPCo", "payerPartyReference": "Bill payments" }, "paymentTerms": { "numberOfTransactionsPermitted": "50", "frequency": "DAIL", "agreementType": "VARI", "maximumAmount": "1000" }, "paymentDetails": { "automaticRenewal": true, "purpose": "OTHR", "startDate": "2025-06-06", "description": "Bill payment request", "shortDescription": "Pay your Bills" } }

Example Response:

{ "paymentAgreementUID": "BOBSBUILDERS1", "paymentAgreementStatus": "Created", "paymentAgreementStatusDescription": "Pending Payer Approval" }

In sandbox:

Wait ~30 minutes for the agreement to auto-approve
Or share UID with Monoova on Slack to approve manually

Step 6: Check Agreement Status - Full Docs

Endpoint: GET https://sand-api.monoova.com/au/payto/pam-v1/paymentAgreement/{paymentAgreementUID}

Example Response:

{ "pendingActions": [ { "status": "PendingApproval" } ] }

Status Values:

PendingApproval: Waiting for payer approval
Approved: Agreement active and ready
Rejected: Agreement was declined
Expired: Approval expired

You’re Live

Your business is now fully onboarded with Monoova:

KYB and UBOs verified
Ledger provisioned
PayID registered
PayTo agreement created

You’re now ready to send and receive money using Monoova’s infrastructure.

Bill Onboarding

How It Works

Step 1: Business and Individual Verification with Monoova KYB API

Authenticate and Get Token

Create and Verify Business Entity

Retrieve UBOs

Create and Verify Individual(s)

Step 2: Create a Monoova Ledger - Full Docs﻿

Step 3: Register PayID - Full Docs﻿

Step 4: Generate a Bearer Token (PayTo) - Full Docs﻿

Step 5: Create a PayTo Agreement - Full Docs﻿

Step 6: Check Agreement Status - Full Docs﻿

You’re Live

Step 2: Create a Monoova Ledger - Full Docs

Step 3: Register PayID - Full Docs

Step 4: Generate a Bearer Token (PayTo) - Full Docs

Step 5: Create a PayTo Agreement - Full Docs

Step 6: Check Agreement Status - Full Docs