Integration flow (no mobile app)

The flow for partners who have no app of their own — employees onboard through the BMONI app via an invite link, while the partner integrates over the API alone, sending invites (with KYC) and reading each employee’s VBA.

LifecycleUserWalletKYCRailFundMove money

Some partners have no mobile app of their own. Their employees still use the BMONI app — the partner simply lends it. “No mobile app” describes the partner, not the employee.

That makes the partner’s integration small and entirely server-side. The partner never builds an app, never generates keys, never signs anything, and never collects KYC documents from the employee in a browser. The partner does exactly two things over the API:

1. Invite each employee — one call that also carries the KYC data the employer already holds.
2. Read each employee’s VBA (and watch webhooks) once they’ve onboarded — to show it on the partner’s own dashboard.

Everything between those two points happens inside the BMONI app, and is already wired there.

The employer-held KYC travels in the invite, so the employee does not re-enter their identity data. At most they take a selfie in-app (liveness can’t be employer-supplied). No employee-side forms, no web wallet provisioning.

---

Prerequisites

• A partner API key — passed as x-api-key: <key> on every request.
• The proxy base URL — origin only, no trailing /v1.
• A webhook endpoint registered with BMONI to receive employee.linked and onboarding.completed.

---

End-to-end flow

The invite call is also the refresh call — re-inviting the same email reissues the same deep link. There is no separate link-generation endpoint.

---

Sequence

---

Step-by-step (partner side)

1. Invite the employee — with KYC

   One call sends the co-branded email (QR + deep link) and carries the KYC the employer already holds.

   POST /v1/partners/employees/invite
   x-api-key: <partner key>
   {
     "name": "Chiamaka Okafor",
     "email": "[e-mail]",
     "kyc": {
       "profile": {
         "personalInfo": { "firstName": "Chiamaka", "lastName": "Okafor", "dateOfBirth": "1990-01-15", "nationality": "MX" },
         "address": { "streetLine1": "Av. Insurgentes Sur 123", "city": "Mexico City", "state": "CDMX", "postalCode": "03100", "countryCode": "MEX" },
         "employment": { "employmentStatus": "employed", "employerName": "Allora HR" },
         "sourceOfFunds": "salary",
         "identificationNumbers": [{ "type": "curp", "number": "OKAC900115MDFXYZ01", "issuingCountryCode": "MEX" }]
       }
     }
   }
   

   Returns { sent, inviteUrl, error? }. kyc.profile is the same shape as PATCH /v1/users/{userId}/kyc; it’s submitted to the employee’s profile the moment they link. Document images and the selfie are handled in-app after linking — they’re never part of this payload.

2. The employee onboards in the BMONI app

   Not your code — this is the app doing its job. The employee taps the deep link, installs the app if needed, creates a BMONI account, and the app consumes the invite context to show a Link your employer modal. They confirm with a work-email OTP; the employer-held KYC is submitted automatically. The only thing the employee may do themselves is a selfie, if the verification provider requires liveness.

3. Receive employee.linked and store the bmoniUserId

   // webhook: employee.linked
   {
     "invitationId": "…",
     "bmoniUserId": "…",
     "companyEmail": "[e-mail]",
     "partnerName": "Allora HR",
     "linkedAt": "2026-01-15T10:00:00Z",
     "kycSubmitted": true
   }
   

   bmoniUserId is the key for every subsequent read.

4. Read the VBA for your dashboard

   The employee picks a USD or MXN wallet in-app; BMONI provisions the VBA and emits onboarding.completed. Read it back with the bmoniUserId:

   Currency	Endpoint
   USD	GET /v1/users/{bmoniUserId}/vba/usd — rich status + account (accountNumber, routingNumber, bankName, SWIFT)
   Any	GET /v1/users/{bmoniUserId}/bank-accounts/deposit-accounts/{currency} — the provisioned deposit account (e.g. MXN CLABE)

   USD status progresses none → provisioning → pending → active; the account object is populated once active.

---

Webhooks the partner receives

Event	Meaning
employee.linked	Employee linked to the employer; carries bmoniUserId.
onboarding.completed	KYC approved / VBA provisioned for a currency.
onboarding.failed	Onboarding could not complete.
kyc.action_required	Something (often a selfie) is needed from the employee.
employee.deposit.* / employee.withdrawal.*	Money movement on a linked employee’s wallet.

---

What the partner does not do

• No app. Employees use the BMONI app; the partner ships nothing to a device.
• No signing, no keys, no wallet provisioning. Wallet creation and its on-device owner-proof signing happen entirely inside the app. The partner has no browser or backend signing step.
• No employee-entered KYC. The employer’s data rides in the invite; the employee re-enters nothing (a selfie is the only possible employee action).

---

Reference implementation

The bmoni-partner-web-demo app shows the partner side end-to-end: paste an API key, browse an employee roster, send invites (POST /v1/partners/employees/invite) with per-row refresh, and surface each linked employee’s VBA from the read endpoints above. It is a partner dashboard — it never provisions wallets or signs.