Collections Overview

Collections is the money in layer of Meshpay. It covers how we collect payments for invoices, track payment history, and automate collection workflows.

What is Collections?

Collections answers the question:

"Given invoice X with remaining amount R, how do we let a buyer pay it, and how do we track that?"

Collections includes:

Invoice Payments: Individual payment transactions toward invoices
SDK & APIs: Tools for agents and applications to discover and pay invoices
x402 Protocol: Machine-readable payment requirements
Collection Automations: Optional workflows for dunning, retries, reminders

Collections Flow

Basic Collection Path (No Automation Required)

Fetch invoice summary
- GET /v1/invoices/{id}/balance returns remaining amount and partial payment support
Get x402 payment requirements
- GET /v1/invoices/{id}/x402-requirements returns payment instructions (network, asset, pay_to, amount)
Execute payment
- Buyer's wallet sends on-chain transaction according to x402 requirements
Meshpay verifies & records
- Facilitator confirms transaction
- Invoice payment is created and invoice balance updates

Partial Payments

Collections supports partial payments:

Multiple payments per invoice
Accurate balance tracking (total_amount, total_paid, remaining_amount)
x402 requirements reflect remaining balance
Guardrails prevent overpayment

Invoice Payments

Each payment toward an invoice is tracked as an Invoice Payment:

Amount: Payment amount
Status: pending, settled, failed, cancelled
Network & Asset: Blockchain network and token used
Transaction Hash: On-chain transaction identifier
External Reference: Links to invoice and x402 transactions

Collection Automations

Collection automations are optional workflows built with flows (type: collection):

Dunning: Automatic reminders for overdue invoices
Retry Logic: Scheduled collection attempts
Escalation: Multi-step workflows for difficult collections

Basic collection (SDK + x402) works without automations. Automations add advanced orchestration on top.