Preview quotes before checkout
Show indicative pricing before the hosted 0Gate flow while keeping final price and fulfillment tied to trusted backend state.
Use quote preview when your product needs to show an estimate before the user enters the hosted 0Gate flow. A preview helps the customer decide; it is not the same as settlement and it should not replace the hosted session or webhook path.
Preview pages should not become API reference pages
This guide explains when and how to place quote previews in the user journey. Exact request fields, response schemas, generated code samples, and entitlement rules belong in the API reference.
Where preview fits
| Phase | Customer sees | Backend should store |
|---|---|---|
| Estimate | Amount, asset, fees, estimated receive/send amount, expiry or freshness label. | Preview id if returned, input tuple, timestamp, and display values. |
| Acceptance | Clear button to continue to hosted checkout. | Accepted preview snapshot and new session attempt id. |
| Hosted checkout | 0Gate-owned confirmation and payment journey. | 0Gate session id tied to your accepted snapshot. |
| Completion | Processing or terminal status from your app. | Verified event id, terminal state, and reconciliation notes. |
Indicative vs locked
| Quote type | Use for | User copy |
|---|---|---|
| Indicative preview | Early comparison, payment-method choice, checkout preflight. | “Estimated. Final amount is confirmed in 0Gate.” |
| Session-bound quote | Hosted checkout handoff after the customer accepts. | “Continue to 0Gate to confirm.” |
| Locked quote | Approved high-tier/server-side flows only. | Use only when the API reference and entitlement docs explicitly support it. |
Implementation shape
Keep preview calls server-side, sanitize the display result, and create the 0Gate session only after the customer accepts the shown path.
async function previewCheckout(input: QuotePreviewInput) {
const preview = await gateQuotes.preview({
side: input.side,
amount: input.amount,
asset: input.asset,
currency: input.currency,
country: input.country,
});
await quotePreviews.store({
accountId: input.accountId,
previewId: preview.id,
displayedAt: new Date(),
display: preview.displaySafeSummary,
});
return preview.displaySafeSummary;
}async function acceptPreview(input: AcceptPreviewInput) {
const stored = await quotePreviews.getForAccount(input.previewId, input.accountId);
const attempt = await paymentAttempts.createFromPreview(stored);
const session = await gateSessions.createForAttempt({
attemptId: attempt.id,
flow: stored.side,
previewId: stored.previewId,
idempotencyKey: `preview-accept:${attempt.id}`,
});
return { attemptId: attempt.id, clientSecret: session.clientSecret };
}Display rules
| Rule | Reason |
|---|---|
| Show a freshness timestamp or expiry label. | Customers need to know the estimate can move. |
| Keep final confirmation inside 0Gate. | Hosted flow owns customer-facing confirmation and compliance steps. |
| Store the displayed snapshot. | Support can see what the customer accepted before checkout. |
| Do not display provider, venue, spread, or treasury internals. | Public docs and UI should avoid liquidity-sensitive details. |
| Do not fulfill from preview state. | Previews are not terminal settlement. |
Failure behavior
| Failure | Browser action | Backend action |
|---|---|---|
| Preview unavailable | Show an unavailable state or let the user try a different amount/asset. | Store reason category only, not internal provider output. |
| Preview stale | Ask the user to refresh the estimate. | Mark the preview superseded. |
| Hosted session creation fails | Keep the accepted preview snapshot and show retry. | Retry safely with the same logical attempt or create a new attempt. |
| Final hosted state differs | Trust the signed backend event and support record. | Close from terminal state, not the preview. |
Related pages
Build a 0Gate payment flow
Create and reconcile the hosted payment session after preview acceptance.
Lock an on-ramp flow
Use previews before a hosted buy flow.
Build a 0Gate swap flow
Keep swap preview language separate from execution guarantees.
API reference
Put endpoint-level quote details in the API reference.