Partial and Excess Blockchain Payments
Model invoices with multiple transfers, partial payments and excess receipts, while keeping settlement eligibility and refund decisions explicit.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
An invoice can be paid through several transfers, and a single transfer can exceed the requested amount. The payment model should preserve those receipts rather than force a one-invoice-one-transaction assumption.
Allocate receipts under a declared rule
Keep invoice identity separate from chain event identity. Validate asset and recipient before assigning a receipt, then sum only eligible settled quantities. Define expiry, exchange-rate and tolerance policies where relevant. A transfer memo or expected amount can help matching but should not replace technical identity checks.
Worked example: two receipts and an excess
An invoice requests one hundred units. Accepted receipts of sixty and forty-five arrive. The total is 105, with five excess under a straightforward exact-unit policy. Preserve both events and the allocation. Do not automatically send the excess anywhere: a refund is a separate authorised operation with its own destination checks.
Handle reversals and review
Test one receipt becoming non-canonical, a receipt assigned twice and a transfer in the wrong token. Recalculate invoice status from durable eligible allocations. Keep observed, settled and available-for-refund amounts distinct. Where ownership or refund destination is unclear, route the issue to review instead of inferring control from the original sending address.
A practical acceptance test
Allocate settled receipts of sixty and forty-five to a one-hundred-unit invoice. Assert total 105 and excess five while preserving both event IDs. Reverse eligibility for one receipt and recompute status. The excess state must not submit a refund or choose a destination automatically; those require a separately authorised and validated operation.
Questions about the topic
Frequently asked questions
Does the transaction sender always identify a refund destination?
No. Custodial or contract-based payments can complicate that assumption.
Should partial receipts be discarded?
No. Preserve and allocate them according to the invoice policy.
Standards & technical documentation
