Cryptocurrency prices are volatile. Between the moment a customer initiates a payment and when that transaction is confirmed on the blockchain, the fiat value of the crypto can fluctuate. Without any tolerance, a customer who sends the exact amount of crypto to cover a $100 invoice might end up a few cents short by the time the transaction is verified.
The slippage margin solves this by defining a percentage tolerance that determines the minimum acceptable payment. If the slippage margin is set to 2%, a 100invoiceacceptsanypaymentof98.00 or more as paid in full.
Why slippage margin exists
Without slippage margin, businesses face a frustrating cycle:
- Customer owes $100 and sends the equivalent in crypto
- By the time the transaction confirms (minutes to hours later), price fluctuation means the fiat value is now $99.50
- The system marks the invoice as partially paid, even though the customer acted in good faith
- The customer is asked to send another transaction to cover the $0.50 difference
- That second transaction also incurs network fees, which may exceed the shortfall
Slippage margin eliminates this friction by acknowledging that small fluctuations are a normal part of cryptocurrency payments.
Minimum Acceptable Amount = Invoice Amount x (1 - Slippage Margin / 100)
| Invoice amount | Slippage margin | Minimum acceptable | Result |
|---|
| $100.00 | 1% | $99.00 | Payment of $99.50 is accepted as paid in full |
| $100.00 | 2% | $98.00 | Payment of $98.75 is accepted as paid in full |
| $100.00 | 5% | $95.00 | Payment of $96.00 is accepted as paid in full |
| $500.00 | 1% | $495.00 | Payment of $497.00 is accepted as paid in full |
| $500.00 | 0.5% | $497.50 | Payment of $496.00 is NOT accepted as paid in full |
The three-level fallback chain
Slippage margin can be configured at three levels. The system uses a fallback chain to determine which value applies:
Price level ---> Account level ---> System default
(most specific) (least specific)
Level 1: Price-level margin
Each individual price can have its own slippage margin. This is the most specific setting and takes priority over all others when set to a value greater than zero.
When to use: When specific products have different risk profiles. A high-value product might warrant a tighter margin, while a low-value product could tolerate more flexibility.
Level 2: Account-level default
Every account has a default slippage margin that applies to all prices that do not have their own margin set. This provides a single place to control slippage tolerance across all products.
When to use: When you want a consistent margin across your entire catalog without configuring each price individually.
Level 3: System default
If neither the price nor the account has a slippage margin configured (both are zero), the system applies a built-in default. This ensures that every verification has at least some tolerance.
When to use: This is automatic. It acts as a safety net so that new accounts and prices have reasonable behavior out of the box.
Fallback rules
The system evaluates the chain from most specific to least specific:
- If the price has a slippage margin greater than zero, use that value
- Otherwise, if the account has a default slippage margin greater than zero, use that value
- Otherwise, use the system default
A value of zero at any level means “not configured” and triggers the fallback to the next level. Setting a price’s slippage margin to zero does not mean “no tolerance” — it means “use whatever the account or system default is.”
Fallback examples
| Scenario | Price margin | Account default | Effective margin | Reason |
|---|
| Price-level override | 3% | 1% | 3% | Price-level takes priority |
| Account default applies | 0% | 2% | 2% | Falls back to account |
| System default applies | 0% | 0% | System default | Falls back to system |
| Price-level with tight margin | 0.25% | 5% | 0.25% | Price-level takes priority, even if lower |
When slippage is evaluated
Slippage margin is applied at verification time — the moment the system checks whether a crypto payment satisfies an invoice.
This means:
- The slippage value is read from the current configuration when verification runs
- It is not stored on the invoice or locked in at invoice creation time
- It is not retroactively applied to previously completed verifications
Impact of changing slippage margin
Already-paid invoices are not affected
Once an invoice is marked as paid, that status is permanent. Changing the slippage margin has no retroactive effect on invoices that have already been verified and marked as paid.
Example:
- Account has a 1% slippage margin
- A 100invoicereceivesa99.20 crypto payment
- Verification runs and marks the invoice as paid (since 99.20>=99.00)
- Account holder later changes slippage to 0.5%
- The $100 invoice remains paid — it is not re-evaluated
Unpaid invoices use the new value
Invoices in a pending or partially paid state are affected by slippage changes the next time verification runs.
Example:
- Account has a 1% slippage margin
- A 100invoicereceivesa99.20 crypto payment but has not yet been verified
- Account holder changes slippage to 0.5% (minimum acceptable becomes $99.50)
- Verification now runs: 99.20<99.50, so the invoice is not marked as paid
Tightening the slippage margin on an account with pending invoices may cause payments that would have been accepted under the old margin to be rejected. Review pending invoices before making changes.
Tightening slippage on active invoices
Before change:
Account slippage: 1%
Invoice: $200.00 due
Minimum acceptable: $198.00
Crypto received: $198.50
Status: Would be PAID if verified now
After change (slippage reduced to 0.5%):
Account slippage: 0.5%
Invoice: $200.00 due
Minimum acceptable: $199.00
Crypto received: $198.50
Status: NOT paid in full (shortfall of $0.50)
Loosening slippage on active invoices
Before change:
Account slippage: 0.5%
Invoice: $200.00 due
Minimum acceptable: $199.00
Crypto received: $198.50
Status: NOT paid in full
After change (slippage increased to 1%):
Account slippage: 1%
Invoice: $200.00 due
Minimum acceptable: $198.00
Crypto received: $198.50
Status: Would be PAID if verified now
Summary of change impact
| Invoice status | Effect of slippage change |
|---|
| Paid | No effect. Status is permanent. |
| Partially paid | New slippage applies on next verification. May now pass or fail depending on direction of change. |
| Pending | New slippage applies on next verification. |
| Overdue | New slippage applies on next verification. |
Valid slippage values
- Minimum: 0% (triggers fallback to next level in the chain)
- Maximum: 100% (would accept any payment amount, including zero — not recommended)
- Precision: Up to two decimal places (e.g., 1.50%, 0.25%)
Practical recommendations
| Slippage range | Use case |
|---|
| 0.25% - 0.5% | Tight tolerance for stablecoins or low-volatility assets |
| 1% - 2% | Standard tolerance for most cryptocurrency payments |
| 3% - 5% | Higher tolerance for volatile assets or longer confirmation times |
| > 5% | Unusual — consider whether the business can absorb this variance |
Interaction with multiple transactions
When a customer pays an invoice across multiple crypto transactions, the slippage margin applies to the total fiat value of all transactions combined, not to each individual transaction.
Example (2% slippage on a 100invoice,minimumacceptable=98.00):
| Transaction | Crypto amount | Fiat value at time | Running total | Status |
|---|
| Tx 1 | 0.001 BTC | $48.00 | $48.00 | Partially paid |
| Tx 2 | 0.001 BTC | $51.00 | $99.00 | Paid in full |
Slippage margin in webhook payloads
When price events are broadcast via webhooks (price.created, price.updated, price.deleted), the payload includes the slippage_margin_percent value. This is the raw price-level value, not the effective value after fallback. External systems can use this to understand the configured slippage for each price.
Slippage margin in verification results
When a payment is verified with a slippage margin greater than zero, the verification result includes:
slippage_margin_percent — the slippage percentage that was appliedfiat_minimum_acceptable — the calculated minimum amount that would be accepted as paid in full
These fields are only present when slippage is actively applied (greater than zero). When no slippage is configured, these fields are omitted and the verification behaves as a strict exact-amount check.
Related pages
