Pre-funding Flow

## Pre-Funding Flow

The pre-funding model is a method for processing payments where you first load funds into your Lumanu workspace balance. This is similar to topping up a prepaid account. Once the funds have been added and allocated, you can create and approve payables that will draw from this available balance.

This flow is ideal for organizations that want to budget and set aside funds for creator campaigns ahead of time, ensuring a predictable and controlled payment process.

How It Works

The process involves creating a special funding invoice, having it paid, allocating the settled funds to your balance, and then managing your payables.

1. Initiate Funding: Your application starts the process by making an API call to create a funding resource with the type set to invoice. This tells the Lumanu platform to generate a formal invoice for the specified amount.
   • API Call: POST /funding
2. Invoice Payment: The Lumanu platform generates an invoice and sends it to the designated recipient (e.g., your finance department). This recipient pays the invoice, and the funds are transferred to your workspace's wallet account.
3. Allocate Funds: When the funds settle, they must be officially allocated to your workspace's usable balance. This critical step can be done either manually in the Lumanu web app or programmatically via the API by associating the settled funds with the original funding request.
   • Webhook Event: transfer.created fires when the funds enter or leave the wallet account. You will need to verify each of these to determine whether it is the transfer you are expecting.
   • API Call: POST /funding/{id}/link-deposit
   • Balance is available: The funds are now available in the wallet balance
4. Manage Payables: With a funded balance, your application can now create and approve payables for your vendors and creators.
   • API Call: POST /payable to create a new payable.
   • Webhook Event: payable.created
   • API Call: POST /payable/{id}/approve to approve an existing payable.
   • Webhook Event: payable.approved
5. Execute Payouts: The final step of paying an approved payable is performed by a user within the Lumanu web app. They will select the approved payables and initiate the payout, which draws from the pre-funded balance.
   • Webhook Events: payable.paid fires as the final payout is executed.

Interaction Diagram

This diagram illustrates the sequence of events between your client application, the Lumanu API, and the Lumanu web app.

sequenceDiagram
    participant Client App as Client Application
    participant LumanuAPI as Lumanu API
    participant Finance as Finance Department
    participant WebApp as Lumanu Web App

    Client App->>+LumanuAPI: 1. POST /funding (type: 'invoice')
    LumanuAPI-->>-Client App: Funding object created

    LumanuAPI-->>Finance: 2. Sends Funding Invoice
    Finance-->>LumanuAPI: 3. Pays Invoice
    note right of LumanuAPI: Webhook: `transfer.created`

    Client App->>+LumanuAPI: 4. POST /funding/{id}/link-deposit
    LumanuAPI-->>-Client App: Funding allocated

    Client App->>+LumanuAPI: 5. POST /payable
    LumanuAPI-->>-Client App: Payable object created
    note right of LumanuAPI: Webhook: `payable.created`

    Client App->>+LumanuAPI: 6. POST /payable/{id}/approve
    LumanuAPI-->>-Client App: Payable approved
    note right of LumanuAPI: Webhook: `payable.approved`

    WebApp->>+LumanuAPI: 7. User clicks "Pay" for Payable
    LumanuAPI-->>-WebApp: Payout initiated
    note right of LumanuAPI: Webhook: `payable.paid`