---
title: Onboarding API Flow
slug: monoova-onboarding-api/onboarding-api-flow
docTags: 
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

- Create a business entity with associated Ledger
- Verify business and individuals via KYB APIs
- 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



::::WorkflowBlock
:::WorkflowBlockItem
### Authenticate and Get Token

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

:::WorkflowBlockItem
### Create Business entity and  ledger account

Submit the business details to begin KYB verification.

**Endpoint:** POST - Create an entity



The response will return an applicantId. This identifier is required for all subsequent KYB steps. Refer to [Sandbox MCC Code List](docId\:IpFaRv0UVeI0SX4LwawAd) for MCC values.

**Polling for Verification Completion**

**Endpoint:** GET - Get entity status

Poll this endpoint to check the overall status of the application
:::

:::WorkflowBlockItem
###  Retrieve UBOs

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

**Endpoint:** GET - Get UBOs for an entity

Each UBO returned here must be verified in the next step. If the UBO details match with individuals created via the API, the applicants will be merged.
:::

:::WorkflowBlockItem
### Create Individual IDV link(s)

This will send an email containing an IDV link to the address associated with an individual via the Create Individual step.

**Endpoint:** POST - Create an individual IDV link @webhooks

**Polling for Verification Completion**

**Endpoint:** GET - Individual entity status

 Poll this endpoint to check the overall status of the individual
:::

:::WorkflowBlockItem
### Receive webhooks as individuals and entity proceed through verification


:::
::::

***

## Step 2: 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 3: 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 4: 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 5: 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

***