Invoices

Sivo Advance enables marketplace platforms to offer invoice factoring and cash advances to sellers. This guide provides a high-level overview of implementing Sivo Advance in your platform.

---
config:
  theme: redux
---
sequenceDiagram
    actor B as Buyer
    participant S as Seller
    participant Sivo as Sivo Advance

    B ->> S: Makes a purchase
    S ->> Sivo: Request advance on invoice
    Sivo ->> S: Response with advance amount
    S ->> Sivo: Accept advance terms
    Sivo --) S: Disburse advance funds
    activate S
    Note over S: Wait for payment
    B --) S: Pay Invoice
    deactivate S
    S --) Sivo: Send funds
    opt if needed
        Sivo--) S: Send remaining reserve
    end

Implementation Workflow

1. Create Buyer

Register the buyer that will be invoiced and eventually pay the invoice.

POST /accounts

Important buyer information includes:

• Legal entity information
• Business address
• Contact information
• For underwriting:
  • Shipping address
  • Legal entity ID: DUNS
  • PAYDEX score
  • KYX status
  • Average days to pay
  • Lifetime spend in USD

2. Create Invoice

Create an invoice with necessary details.

POST /sellers/{seller_id}/invoices

The invoice should include:

• Invoice number/identifier
• Invoice date
• Payment terms (e.g., Net 30)
• Total amount due
• Buyer reference

3. Add Invoice Items

Add detailed line items to the invoice to provide transparency about what's being billed.

POST /sellers/{seller_id}/invoices/{invoice_id}/invoiceitems

Each item should specify:

• Description of goods/services
• Quantity
• Unit price
• Total amount

4. Request Terms for Advance

For invoices that require and advance, generate the advance terms.

POST /sellers/{seller_id}/invoices/{id}/terms/generate

The response will include the amount to be advanced, the transfer amount, and the expected payment date.

5. Accept Advance Terms

Submit the acceptance to initiate the advance.

POST /sellers/{seller_id}/invoices/{id}/terms/accept

This step triggers the disbursement of funds

6. Get Advance Balances and Ledgers

GET /sellers/{seller_id}/invoices/{id}/terms/transactions
GET /sellers/{seller_id}/invoices/{id}/terms/balances

To check the status of an advance you can access the balances and ledgers. They include the following:

• Payout transactions: details of advance disbursement from Sivo to your bank.
• Payin transactions: details about expected payments to Sivo, including amount and due date. Received payments will also appear when they are received.
• Reserve transactions: if your advance has a reserve you can verify its balance and associated details.

7. Send Payment to Sivo

Transfer the required amount to Sivo based on the ledger details. Include the sivo invoice id as the payment reference.

8. Receive Reserve (if applicable)

If there is remaining reserve to be returned, Sivo will transfer it to your bank account.

Best Practices

1. Comprehensive Data Collection: Provide as much data as possible when creating buyers to improve underwriting.

2. Accurate Data: Provide complete and correct data to ensure accurate advance calculations.

For detailed API specifications, see the API Reference.