A transfer is not a business event
PayIn defines an order payment as a request tied to a particular checkout, invoice or business transaction.[8] Its deposit model instead assigns addresses to accounts or entities and can serve account funding rather than a single invoice.[9] A blockchain transfer alone does not tell your business which obligation it satisfies. Before selecting an API, write one sentence describing the business event: paying a specific invoice or increasing a customer's available balance. That sentence determines the records and exceptions you need.
Use an order when there is a payable obligation
An order should carry a merchant reference, amount, asset, network, destination and an explicit expiry policy. PayIn’s concepts document identifies underpayment, overpayment and late payment as integration decisions.[8] Our recommendation is to preserve the original request rather than overwrite it when funds arrive late. Link each observed transfer to the request, then record a separate decision to accept, investigate or refund. Expiration of a checkout screen must not erase the evidence that money arrived.
Use a deposit when you maintain an account ledger
PayIn describes deposits as incoming transfers to addresses assigned to users or accounts, with merchant-side crediting after detection and confirmation.[9] Your ledger therefore needs a durable ownership history for addresses, network and asset identifiers, transfer identity, confirmation state and a reference to the resulting credit. Our recommendation is to avoid silently reassigning long-lived addresses. A customer may use saved instructions after you believe an account has closed. Keep the history needed to resolve that payment rather than guessing from the current address owner.
Define exceptions before the happy path
For either model, document a response to partial payments, multiple transfers, wrong assets, wrong networks, excess amounts and payments after expiry. Do not automatically mark a larger transfer as two separate purchases. Do not credit an account merely because an address looks familiar. PayIn’s reconciliation guide specifically lists late payments, amount mismatches and duplicate webhook processing as cases to plan for.[7] Route ambiguous records to review, preserving the original amount and event rather than changing history to make totals match.
Acceptance exercise and next step
As a suggested sandbox exercise, create one invoice and one account deposit. Deliver the same payment notification twice; both attempts should leave one economic result. Then test a late transfer and a transfer that cannot be matched to a user. A reviewer should be able to explain the state without reading application logs alone. This is a proposed test, not an executed merchant case study. Once ownership and exception rules are explicit, define the confirmation policy and the webhook handling process that will enforce them.
Sources & currency
Continue reading
Hosted or self-hosted: decide who owns the midnight incident →
All field guides →