---
title: Bill Onboarding
slug: poc-onboarding
createdAt: 2025-06-06T05:00:49.607Z
---

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.

:::::WorkflowBlock
::::WorkflowBlockItem
### 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:**

:::BlockQuote
Accept: application/json
Content-Type: application/json
apikey: YOUR\_API\_KEY
:::
::::

::::WorkflowBlockItem
### Create and Verify Business Entity

Submit the business details to begin KYB verification.

**Endpoint:** POST /kyb/v1/CreateVerifyEntity

**Request Body:**

:::BlockQuote
\{
  "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:**

:::BlockQuote
\{
  "applicantId": "your\_applicant\_id"
}
:::

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

::::WorkflowBlockItem
### Retrieve UBOs

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

**Endpoint:** POST /kyb/v1/RetrieveUbos

**Request Body:**

:::BlockQuote
\{
  "applicantId": "your\_applicant\_id"
}
:::

**Example Response:**

:::BlockQuote
\{
  "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.
::::

::::WorkflowBlockItem
###  Create and Verify Individual(s)

Submit each UBO for identity verification.

**Endpoint:** POST /kyb/v1/CreateVerifyInd

**Request Body:**

:::BlockQuote
\{
  "email": "example\@monoova.com",
  "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](https://api-docs.monoova.com/payments#tag/Ledger-Account/operation/LedgerCreate)

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:**

:::BlockQuote
\{
  "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](https://api-docs.monoova.com/payments#tag/PayID/operation/ReceivablesRegisterPayID)

Enable PayID on the ledger to receive instant payments.

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

**Request Body:**

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

Leave payId blank to auto-generate one like abc123\@monoova.me. 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](https://api-docs.monoova.com/payTo#tag/Subscriptions/operation/SubscriptionsReport)

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](https://api-docs.monoova.com/payTo#tag/Manage-Payment-Agreements/operation/post-paymentagreement)

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

**Request Body:**

:::BlockQuote
\{
  "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:**

:::BlockQuote
\{
  "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](https://api-docs.monoova.com/payTo#tag/Reporting/operation/get-paymentagreement-id)

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

**Example Response:**

:::BlockQuote
\{
  "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.