FireHorse Pay/developersDashboard
Guides

Hosted checkout lifecycle

Create a server session, let the payer choose an eligible method, and use server-side evidence to complete the order.

Session and transaction are different#

POST /checkout/sessions returns a capability URL and expiresAt. Keep that URL private to the intended customer and reuse it for that checkout. No API key appears in the URL.

The selected method creates a transaction. A session itself is not a transaction and does not accept merchantReference. Keep the order association on your server; add a deliberate reconciliation step when integrating this flow.

Eligibility belongs on the server#

Checkout shows eligible method/currency options for the amount and payer country. Routing selects the provider using the configured bindings, approvals, capabilities and limits. Customers do not choose a provider code.

An expiring checkout and changed configuration can invalidate earlier choices. Eligibility is checked again at payment time. Amount modification is possible only when the merchant cashier policy enables it.

Return URLs are navigation#

Use a valid absolute HTTP(S) returnTo for the hosted session when needed. Transaction-level return URLs take priority over merchant defaults where supported; hosted checkout can also use the merchant website or built-in return page.

Neither reaching a success page nor closing a provider window proves a terminal payment status. Display a pending state until your server has confirmed the transaction.

Search documentation