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. All steps can be completed programmatically via the REST API without requiring users to log into the web app.

1. Initiate Funding: Your application starts the process by making an API call to create a funding resource with the method set to invoice. This tells the Lumanu platform to generate a formal invoice for the specified amount.
   • API Call: POST /api/rest/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 via the REST 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 /api/rest/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 via the REST API.
   • API Call: POST /api/rest/payable to create a new payable.
   • Webhook Event: payable.created
   • API Call: POST /api/rest/payable/{id}/approve to approve an existing payable.
   • Webhook Event: payable.approved
5. Execute Payouts: The final step is to pay the approved payables by making an API call with the method set to balance and providing the payable_ids. This draws from the pre-funded balance.
   • API Call: POST /api/rest/funding (with method: "balance" and an array of payable_ids)
   • Webhook Events: payable.paid fires as the final payout is executed.

Interaction Diagram

This diagram illustrates the sequence of events, showing how all interactions can be performed via the REST API without requiring users to log into the web app.

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

    Client App->>+LumanuAPI: 1. POST /api/rest/funding (method: '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 /api/rest/funding/{id}/link-deposit
    LumanuAPI-->>-Client App: Funding allocated

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

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

    Client App->>+LumanuAPI: 7. POST /api/rest/funding (method: 'balance', payable_ids)
    LumanuAPI-->>-Client App: Payout initiated
    note right of LumanuAPI: Webhook: `payable.paid`