Business processes
Connect webhook facts to checkout, static deposits, payouts, refunds, and standalone conversions.
Verify each delivery, store it once by event ID, then apply the business operation idempotently. The tables below distinguish an observed payment, a newly accepted payment, and a status-only notification.
Hosted checkout#
| Moment | Event | What to do |
|---|---|---|
| Invoice created | invoice.created | Save the order/invoice relationship; no credit |
| Checkout activated | No event | Address, selected amount, and deadline can be read with GET |
| Transfer observed | invoice.detected | Show detected; do not fulfill or credit an observation |
| Partial payment accepted | invoice.confirming | Update accepted-payment progress |
| Confirmed payment still being processed | No event | Wait; the invoice stays pending or confirming. Do not fulfill or ask the customer to pay again |
| Paid threshold reached | invoice.paid or invoice.overpaid | GET current status and fulfill once per invoice |
| Invoice closes with part accepted | invoice.underpaid | Usually no new credit; reconcile amount_paid from the invoice and apply the incomplete-order policy |
| Unpaid window closes | invoice.expired | Close the unpaid order while retaining late-payment handling |
| Observation dropped/reorged before acceptance | invoice.invalid | No accepted-payment reversal is implied |
| Payment cannot be accepted and nothing was accepted | invoice.rejected | Do not fulfill; the invoice is closed and keeps rejected even if money is accepted later |
| Payment accepted after late detection or while the invoice is closed | invoice.late_payment | Re-read invoice; a paid event may describe the same acceptance |
| Accepted payment reversed | invoice.payment_reversed | Reconcile reduced accepted gross and current status; review fulfilled orders |
amount_paid is cumulative accepted gross. It is not net credit. Acceptance events' gross_amount, fee_total, and net_amount describe one payment effect, and one effect can appear in more than one event type. Do not sum event amounts.
A confirmed payment can take longer to be accepted. The invoice does not expire meanwhile, and the extra time does not make the payment late. When processing ends, you receive invoice.confirming, invoice.paid, or invoice.overpaid when it is accepted; invoice.rejected when it cannot be accepted and nothing else was; invoice.underpaid when it cannot be accepted after a partial acceptance, or when it is the last timely payment and is accepted as the invoice closes short of the amount (then invoice.underpaid is the only event for that acceptance). No reason is published. See payments that take longer.
invoice.late_payment does not carry amount_paid; GET is needed for the cumulative amount. Late detection means first detection on or after the deadline; slow confirmations alone do not make a timely detected payment late. A reversal can recalculate a paid invoice's status. Keep reversal handling distinct from fulfillment.
Static customer deposits#
Create one reusable address, save its ID against the customer, and subscribe to invoice events. Each attributed deposit creates a source: static invoice.
The event does not contain static_address_id. Retrieve the invoice and map that field to your customer. Do not credit from invoice.created or invoice.detected; wait for acceptance and apply your deposit policy once per invoice/payment accounting decision.
Static deposit invoices can expire and later accept a payment. Handle the same late-payment and reversal events as hosted invoices. Address totals do not replace your customer's balance or a deduplication record.
Payouts#
The create response first reports queued and a reserved merchant debit. No payout-created or intermediate-status webhook is sent.
| Event | Meaning | Action |
|---|---|---|
payout.completed | Recipient transfer completed | Close the withdrawal once |
payout.failed | Execution failed and reservation released | Read current state; any replacement is a new deliberate payout |
payout.reversed | Previously completed transfer provably disappeared and funds were restored | Reconcile and decide whether to send a replacement |
Do not sum amount, service fees, and actual network cost to invent a debit. Read target_funding_amount for the payout's obligation and balance_movements for its per-gate effects; actual network cost is separately denominated. A failed or reversed event can arrive after another event: current GET state takes precedence for the next action.
Refunds#
| Event | Meaning | Action |
|---|---|---|
refund.created | Refund created and funds reserved | Save refund/invoice relationship; show pending |
refund.completed | Refund transfer completed | Close this refund once; retain fee currency/network with the measured cost |
refund.failed | Reservation and in-flight refundable amount released | Read the refund; decide whether a new request is appropriate |
refund.reversed | Completed return lost confirmation; terminal effect mirrored and reserve released | Reconcile the original transaction; do not automatically send a replacement |
Closed invoices with accepted funds are eligible for refunds, including underpaid invoices and expired or invalid invoices after late acceptance. A refund is a separate resource, and payout_id does not represent a separate payout row.
Standalone manual conversions#
| Event | Meaning | Action |
|---|---|---|
conversion.completed | Settlement and credit committed | Reconcile credited_target_amount; do not treat target_amount as the credit |
conversion.failed | First failed execution | Read the conversion; source can remain reserved and recovery can follow |
conversion.source_restored | Source returned/released or never reserved | Read source_returned_amount; zero is correct for refusal before debit |
These live-only events cover API and dashboard standalone conversions. Save conversion_id, which equals the conversion API's operation_id, and use Get conversion after a notification. A finance operation has its own ID; see ID reconciliation. Retries preserve the event ID; repeated failed recovery attempts do not produce new failure events. Do not sum amounts across lifecycle events.
Test delivery#
webhook.ping tests HTTPS delivery and signature verification. Save or acknowledge it according to your receiver policy, but do not create an invoice, credit a customer, or fulfill an order from it.