Vendor onboarding

## Vendor Onboarding Flow

Onboarding vendors (or "partners") efficiently is key to managing your payments. A common challenge is that the email address you use to invite a vendor might not be the same one they use for their Lumanu account.

To solve this and prevent duplicate records, we use a Lumanu ID—a unique, immutable identifier for every vendor. The goal of the onboarding flow is to reliably retrieve and store this Lumanu ID for all your partners.

The Recommended Onboarding Flow

We recommend the following asynchronous process using webhooks to ensure you always have the correct Lumanu ID for a vendor, even if they sign up with a different email address.

Check for an Existing Lumanu ID: Before inviting a new vendor, first check your own system to see if you have already stored a Lumanu ID for them. If you have one, you can skip the invitation process entirely and use that ID for all future API calls.
Send the Partner Invite: If you don't have a Lumanu ID, send an invitation using the vendor's email address.
- API Call: POST /workspace/{id}/partner/invite
Store the Invitation ID: The API response will contain a unique invitation_id. You must store this ID and associate it with the pending vendor in your database. This ID is the key to linking the invitation to the vendor who eventually signs up.
Receive the partner-invite.claimed Webhook: When the vendor clicks the invite link and successfully signs up or logs in, the Lumanu platform will send a partner-invite.claimed webhook to your registered endpoint. This webhook payload will contain both the original invitation_id and the vendor's permanent Lumanu ID.
Match and Store the Lumanu ID: Your application should use the invitation_id from the webhook to look up the pending vendor you stored in step 3. Once matched, save the Lumanu ID from the webhook to that vendor's record. You can now use this ID as a reliable, permanent identifier for the vendor.

Interaction Diagram

This diagram illustrates the asynchronous flow of inviting a partner and receiving their permanent Lumanu ID.

sequenceDiagram
    participant Client App as Client Application
    participant LumanuAPI as Lumanu API
    participant Partner as Vendor / Partner

    alt Lumanu ID not found in local DB
        Client App->>+LumanuAPI: 1. POST /workspace/{id}/partner/invite
        LumanuAPI-->>-Client App: 2. Returns { invitation_id }
        Client App->>Client App: 3. Store invitation_id with pending vendor record

        LumanuAPI-->>Partner: 4. Sends email invitation
        Partner-->>LumanuAPI: 5. Clicks link, signs up or logs in
        LumanuAPI-->>Client App: 6. Webhook: `partner-invite.claimed` <br/> (payload includes invitation_id and lumanu_id)

        Client App->>Client App: 7. Match invitation_id, <br/> store permanent lumanu_id
    end