The Payment Page

Overview

Every payment request generates a hosted payment page at:

https://app.tokencashflow.com/pay/{payment_id}

This page is fully managed by TokenCashFlow — no embedding or custom frontend work required. Simply redirect your customer to the pay_url returned from POST /v1/payments.

The page is:

• Publicly accessible — no login required for the payer
• Mobile-first — designed for smartphones
• Real-time — status updates every 5 seconds

What the payer sees

1. Crypto selector (awaiting_selection)

The payer sees the tokens allowed for this payment, grouped by type (stablecoins vs. other cryptos). For each option the payer sees:

• Token symbol and name
• Logo
• The chain it is paid on
• Approximate crypto amount required at the current live rate (refreshed every 10 seconds)

2. Rate lock (awaiting_payment)

After selecting a token, the payer clicks Continue with {TOKEN} which locks the rate. The exact crypto amount displayed is final for the duration of the chain selection window. A countdown timer starts at this point, tracking selection_expires_at.

3. Payment instructions (awaiting_payment → partially_paid → confirming)

After rate lock the payer sees:

• The payment wallet address with a copy button and QR code (scanning it yields the plain address)
• The exact remaining crypto amount to send, with a copy button and approximate USD remaining
• The expiry countdown timer
• A live status banner updating in real time
• A notice to send funds only from a personal wallet — transfers from exchanges, smart contracts, or gas-sponsored wallets are not supported

The payer must send the exact amount shown including network fees. The displayed amount is what the payment monitor expects on-chain.

Rate locking

The rate is fixed when the payer confirms their token selection. The locked rate is stored in the payment record. The exact crypto amount is calculated at lock time:

required_crypto_amount = gross_usd / locked_rate_usd

where gross_usd = amount_usd × (1 + service_fee_pct + conversion_fee_pct) if fee_payer = payer, otherwise gross_usd = amount_usd (see your account's payment settings).

The rate is valid until the chain selection window expires (selection_expires_at). This window is set per-chain by the platform (chain.payment_expiry_minutes, typically 30–60 minutes). The countdown timer on the payment page tracks this window.

Only the selection window expires. A payer can always return to the payment link and reselect. If the window expires, the payer can reselect a token and get a new rate.

Selection expiry and reselection

When the chain selection window (selection_expires_at) passes:

• If no unconfirmed transaction is in progress → status becomes expired_selection
• The payer can return to the payment page at any time and reselect a token with the current market rate
• A new selection window starts on reselection
• If a transaction is already being confirmed, the expiry is held until the transaction resolves
• If the payment was partially paid, the payer must continue with the same token — switching to a different token after receiving partial funds is not allowed

The banner on the payment page reads:
"Your previous selection expired. Please select a token to continue."

Partial payments

If the payer sends less than the required amount:

1. The page updates automatically to show the received amount, the remaining crypto amount, and the approximate remaining USD
2. The payer can top up the remaining amount to the same wallet address before selection_expires_at
3. The remaining amount in crypto is calculated using the locked rate (not the current market rate)

If the selection window expires while in partially_paid state (and no unconfirmed tx):

• Status transitions to expired_selection
• The payer must reselect to continue — the same token is enforced and anew rate is applied to the remaining amount
• Previously received funds are counted; only the remaining gap is recalculated at the new rate
• The page shows the remaining USD value and notes a new rate applies

Overpayments

If the payer sends more than the required amount:

• The payment proceeds to confirming → completed as normal
• Settlement calculation is based on the payment's amounts; the excess is not settled to your balance
• When completing after an expired_partial settlement, you are credited proportionally to what was actually received

Redirect after completion

When the payment reaches completed:

1. The payer sees a success screen (also shown for completed partially-paid payments once fully received)
2. If you set a redirect_url when creating the payment, a countdown appears: "You will be redirected in 5..."
3. The payer is then redirected to your URL

Your redirect URL receives no extra query parameters from TokenCashFlow by default. Use the webhook payment.completed event to update your system, not the redirect.

Payer support

Payers can open the support dialog on any payment page to submit a support ticket without logging in. They must provide their email address so the admin team can reply. Payer submissions are rate-limited to 3 per payment per hour.

Page states reference

Payment status	Page display
awaiting_selection	Crypto selector; amount; description (no countdown yet)
awaiting_payment	Wallet address; QR code; exact crypto amount; selection_expires_at countdown
partially_paid	Remaining amount (~USD); wallet address; QR code; selection_expires_at countdown
expired_selection	Banner: "Your previous selection expired — please reselect"; token selector (same token enforced if partially paid)
confirming	"Payment received — confirming on blockchain"; progress indicator
completed	Success state; redirect if configured
blacklisted	"Payment cannot be processed" (generic — blacklist reason not revealed)
failed	Generic error message