Partial Payments

A seller agrees to a 50k EUR data contract to be paid in several chunks. Instead of sending 5 separate invoices, they create one invoice with partial payments enabled.

What You'll Learn

• Enable partial payment support on profiles
• Create invoices for instalment payments
• Track payment progress over time

Step 1: Enable Partial Payments on Profile

Update an existing profile to allow partial payments:

import requests

url = "https://api.orvion.com/api/v1/invoicing-profiles/profile_01HXYZ123ABC"
headers = {
  "Authorization": "Bearer your-api-key",
  "Content-Type": "application/json"
}

data = {"supports_partial_payments": True}

response = requests.put(url, json=data, headers=headers)
profile = response.json()
print(f"Partial payments enabled: {profile['supports_partial_payments']}")

Alternative: Create a Dedicated Profile

Create a new profile specifically for large deals:

import requests

url = "https://api.orvion.com/api/v1/invoicing-profiles"
headers = {
  "Authorization": "Bearer your-api-key",
  "Content-Type": "application/json"
}

data = {
  "name": "Large Deals – Base USDC (Partial allowed)",
  "network": "base-mainnet",
  "asset": "USDC",
  "pay_to_address": "0xSELLER_BASE_WALLET",
  "collection_mode": "direct",
  "supports_partial_payments": True,
  "is_default": False
}

response = requests.post(url, json=data, headers=headers)
profile = response.json()
print(f"Profile created: {profile['id']}")

Response:

{
  "id": "profile_01HLARGE_DEALS",
  "name": "Large Deals – Base USDC (Partial allowed)",
  "network": "base-mainnet",
  "asset": "USDC",
  "pay_to_address": "0xSELLER_BASE_WALLET",
  "collection_mode": "direct",
  "supports_partial_payments": true,
  "is_default": false,
  "is_active": true,
  ...
}

Step 2: Create Invoice for Full Amount

Create a single invoice for the full contract value:

import requests

url = "https://api.orvion.com/api/v1/invoices"
headers = {
  "Authorization": "Bearer your-api-key",
  "Content-Type": "application/json"
}

data = {
  "customer_name": "Enterprise Customer",
  "customer_email": "[email protected]",
  "amount": 50000.00,
  "currency": "EUR",
  "description": "Annual data contract – pay in instalments",
  "profile_id": "profile_01HLARGE_DEALS",
  "status": "sent",
  "due_at": "2025-12-31T10:00:00Z"
}

response = requests.post(url, json=data, headers=headers)
invoice = response.json()
print(f"Invoice created: {invoice['number']}")

Response:

{
  "id": "inv_01HINSTALMENT",
  "organization_id": "org_seller",
  "number": "INV-2025-0010",
  "customer_name": "Enterprise Customer",
  "customer_email": "[email protected]",
  "amount": "50000.00",
  "currency": "EUR",
  "status": "sent",
  "issued_at": "2025-01-15T10:00:00Z",
  "due_at": "2025-12-31T10:00:00Z",
  "paid_at": null,
  ...
}

Step 3: Monitor Payment Progress

Get invoice details to check payment status:

import requests

url = "https://api.orvion.com/api/v1/invoices/inv_01HINSTALMENT"
headers = {"Authorization": "Bearer your-api-key"}

response = requests.get(url, headers=headers)
invoice = response.json()
print(f"Status: {invoice['status']}")
print(f"Amount: {invoice['amount']} {invoice['currency']}")

Payment History (Coming Soon)

GET /api/v1/invoices/{invoice_id}/payments

This endpoint will return all individual payments for the invoice:

{
  "payments": [
    {
      "id": "pay_01HFIRST",
      "amount": "10000.00",
      "currency": "USDC",
      "status": "settled",
      "tx_hash": "0x123...",
      "created_at": "2025-01-20T10:00:00Z"
    },
    {
      "id": "pay_01HSECOND",
      "amount": "15000.00",
      "currency": "USDC",
      "status": "settled",
      "tx_hash": "0x456...",
      "created_at": "2025-02-15T10:00:00Z"
    }
  ],
  "total_paid": "25000.00",
  "remaining": "25000.00"
}

Current Workflow:

• View invoice detail page in the dashboard
• See total paid vs remaining balance
• View payment timeline in Money → Collections → Payments

Invoice Status Progression

Partial payment invoices progress through these statuses:

sent → partially_paid → paid

| Status | Description | |--------|-------------| | sent | Invoice sent, no payments received | | partially_paid | Some payments received, balance remaining | | paid | Full amount received |

List Partially Paid Invoices

Filter invoices by status to find ones awaiting more payments:

curl -X GET "https://api.orvion.com/api/v1/invoices?status=partially_paid" \
-H "Authorization: Bearer your-api-key"

Seller Mental Model

With partial payments enabled:

1. One invoice for the total contract value
2. Multiple payments flow in over time
3. Status updates automatically as payments arrive
4. Dashboard shows progress and remaining balance
5. No extra config needed after profile + invoice creation

When to Use Partial Payments

Good use cases:

• Large enterprise contracts (50k+)
• Subscription payments spread over time
• Milestone-based data delivery

Consider alternatives when:

• Fixed monthly subscriptions → Create separate monthly invoices
• One-time small purchases → Standard single-payment invoice

Next Steps

• Analytics & Reporting - Monitor all your invoices
• Direct Payout Setup - Simpler single-payment flows