Checkout / Subscription Webhooks
Checkout / Subscription Webhooks
Webhooks may be sent more than once—add deduplication logic to prevent duplicate events.
✅ Event Types
Stablecoin pay-ins fire a separate set of webhook events — see the Advanced: Stablecoin Payment Events section below.
Sample Webhook Payloads
Below are example webhook events that your system can listen to. Each tab represents a different event type, organized by payment method. These events are sent to your configured webhook endpoint and follow a consistent data structure. You can opt in to receive any combination of these events based on your integration needs.
For each event, you’ll see:
eventType– the type of event triggered (e.g., Settled, Card Payment Declined)category– the type of transaction, such as Purchasecreated– the UTC datetime event was sentdata– the details of the transaction, including amounts, fees, customer information, and metadata
Total & Fee Breakdown Currencies
Every payment event carries two complete breakdowns, so you never have to infer which currency an amount is in:
presentmentTotals– the breakdown in the currency you priced the payment in, i.e. whatever you passed assubtotal.currencyat checkout.settlementTotals– the breakdown in USD, the currency you are settled in.
Both objects use the same field names as the top-level breakdown (subtotal,
fees, gasFees, chargebackProtectionFees, fxFees, networkFees,
payInFees, total, rebate, the merchantPaid* fields and the invoiced*
fields), and each amount states its own currency. For a payment priced in USD
the two objects are identical.
The top-level breakdown fields — subtotal, fees, total and the rest,
which sit beside the two objects above — do not all use the same currency for
non-USD payments. Which currency you get depends on the event and on when it
fired:
Card Payment Declinedreports them in your presentment currency when the card is declined during checkout, and in USD when the payment had already been recorded before the failure.Payment Pending Reviewreports them in USD.Card Payment Authorized,Settled,Card Payment Voidedand the chargeback events report them in USD.
This is permanent, supported behavior: these fields will keep working exactly
as they do today, and there is no plan to change or remove them. Existing
integrations need no changes. If you price payments in a currency other than
USD and want one currency across every event type, read presentmentTotals
and settlementTotals.
presentmentTotals carries every fee leg on events that fire during checkout
(Card Payment Declined, Payment Pending Review). On events raised from a
stored payment (Card Payment Authorized, Settled, Card Payment Voided,
the chargeback events) its payInFees and reserve are always absent,
because the stored presentment record does not keep those two legs. Both are
always present on settlementTotals. Read either as optional.
Credit / Debit Card, Apple / Google Pay Events
refundId uniquely identifies the refund itself, while paymentId identifies the payment being
refunded. A payment can have several partial refunds, so use refundId to tell them apart and to
process refund webhooks idempotently. It matches the id returned by the
View Refund Information for Payment
endpoint. The same field is present on the Refund Complete, Refund Failure, and
Refund Returned events.
Advanced: Disbursement Events
Coinflow decouples disbursement (sending the funds to the merchant on-chain) from settlement. The Disbursed Funds event fires as soon as a USDC or Credits disbursement transaction succeeds and a transaction signature is available — which may be before or independent of the Settled event.
Use Disbursed Funds when you need the on-chain transaction signature for every disbursement. Unlike Settled, this event always includes the signature.
The fields in the data object are:
The example values above (such as signature, id, and merchantId) are illustrative only and do not reflect real production values.
Chargeback Events
See our guide: How to Test Chargeback Events to learn how to force chargeback events on sandbox.
ACH Events
PayPal / Venmo Events
paymentMethodToken is the vaulted payment method token for the payment. It is present on the PayPal Payment Authorized, Venmo Payment Authorized, and Settled events when a token exists on the payment.
payerName, payerFirstName, and payerLastName identify the PayPal/Venmo account holder. They are present on the PayPal Payment Authorized, Venmo Payment Authorized, and Settled events when the payer identity was captured on the payment.
payerId is the payer’s stable account id at the payment provider. It is present on the PayPal Payment Authorized, Venmo Payment Authorized, and Settled events when the provider returned one.
payerId is optional. Both PayPal and Venmo pay-ins can carry it — they share the same PayPal application and pay-in webhook — but the provider only returns it on some approvals, and when it is missing the field is omitted from the payload rather than sent empty. Always treat it as optional and fall back to payerName or the payer’s email.
Availability on a payout destination is narrower and follows a different rule: see the Payout Account Linked event in Withdraw Webhooks. All example values on this page, payerId included, are placeholders rather than real identifiers.
PIX Events
Subscription Events
SEPA/ UK Faster Payin Events
Unknown Wire Payment Events
An Unknown Wire Payment Received event fires exactly once when an incoming wire cannot be matched to a pending payment (token, memo, and fuzzy match all fail) and is recorded as an unknown wire on your account. The payload includes enough detail for you to look up the wire in your own systems and initiate reconciliation or a return.
The fields in the data object are:
The example values above are illustrative only and do not reflect real production values.
Advanced: Stablecoin Payment Events
These events fire only for stablecoin pay-ins. If you’re integrating cards, ACH, PIX, or SEPA, you can skip this section.
The paymentId, sessionId, and amount values shown above are examples only and are not reflective of real production values.