Hosted checkout

Every payment intent comes with a hosted checkout at checkout_url, served from https://checkout.feitpay.com. The checkout is fast, has no 3D effects and works without animations; it shows the merchant name and logo only from your sanitised store branding, together with domain-verification signals, and it tells the customer plainly who receives the payment.

Checkout sessions exist only for live payment intents, so they are available once your account is activated.

Checkout sessions

A checkout session is an opaque, short-lived capability URL for one payment intent — cs_ followed by 32 random characters. The id itself grants access to a sanitised public view, so:

• never put API keys in the browser — the checkout never needs them;
• treat the URL like a password for that one payment (do not log it publicly);
• create a fresh session for an open intent if the previous one expired.

POST/v1/checkout-sessionslive · after account activation

{ "payment_intent_id": "pi_01J…" }

Sessions are open, complete or expired.

What the customer sees

1. Amount in your currency and the store identity.
2. A plain statement that the customer pays GRYPHEM PAY’s wallet, processed via Bitcart, and that you are credited once the payment is confirmed (live payments are custodial).
3. Payment methods — the checkout opens an invoice in the platform’s Bitcart account and lists, for each accepted asset, the exact amount calculated with Bitcart’s exchange rate, the address and a QR code. Copy buttons give immediate feedback.
4. Live status with a timeline. Server-sent events push changes; the page falls back to polling every 3 seconds.
5. Success, pending, failed and expired pages. After confirmation the customer can return to your return_url.

The checkout never silently swaps the asset, and never auto-settles partial or late payments — those go through the state machine, an operator check for any custodial credit, and your decision.

Note

Crypto payments are not card payments: there are no chargebacks. Refunds are never automatic; the merchant returns funds, for example with a payout to an address the customer provides.

Public endpoints used by the checkout

These live under /v1/public/ and require only the session id:

Endpoint	Purpose
GET /v1/public/checkout-sessions/{id}	Sanitised session: payment status, processor (invoice status and payment methods) and timeline
POST /v1/public/checkout-sessions/{id}/processor-invoice	Opens the invoice in the platform’s Bitcart account and returns its payment methods. Idempotent: later calls return the same invoice
GET /v1/public/checkout-sessions/{id}/events	Server-sent status events
POST /v1/public/checkout-sessions/{id}/select-option	Watch-only processing only (not used for payments on this platform): choose network_id + asset_id, lock a quote and assign an address
POST /v1/public/checkout-sessions/{id}/refresh-quote	Watch-only processing only: new quote after expiry (same network and address)

You can use the same endpoints (or useCheckoutSession from @gryphem-pay/react) to show status on your own order page.

Return and cancel URLs

return_url and cancel_url must be absolute URLs you control. A redirect to return_url is a convenience, not proof of payment — always rely on the signed webhook and fulfillable.

Payment links

A payment link is a reusable URL for a fixed amount — useful for invoices sent by email, donations or simple products. Each visit creates a new payment intent and checkout session, so a link can be paid only once your account is activated. A link belongs to the environment it was created in: create the links you will share once your account is activated.

POST/v1/payment-linkslive · after account activation

{
  "store_id": "store_01J…",
  "title": "Workshop ticket",
  "amount": "120.00",
  "currency": "EUR"
}

The response contains the public url, sessions_count and confirmed_count. Deactivate a link with PATCH /v1/payment-links/{id} and { "active": false }. Do not set allowed_networks on links for live payments: the intents they create would be refused with allowed_networks_unsupported.