FireHorse Pay/developersDashboard
Start here

Your first hosted checkout

A server-created checkout session is the recommended starting point. No payment API key belongs in your frontend.

1. Prepare the Sandbox connection#

  1. Open Connections in the merchant dashboard. Select the intended merchant region and Sandbox provider.
  2. Complete the required credentials and regional binding. An administrator must approve onboarding where required.
  3. Use Test Center readiness for the exact operation, method, currency and amount. Local readiness does not confirm the external account is usable.
  4. Create a merchant API key in Integration → API & Webhooks and store it in your server environment. Configure a merchant webhook endpoint and its separate secret.

2. Create a session on your server#

Read amount and currency from the trusted order record. POST /api/v1/checkout/sessions with mode SANDBOX. Store the returned checkout URL against that order and redirect the authenticated customer with HTTP 303.

This endpoint does not accept merchantReference and is not idempotent. Reuse the stored checkout URL for the same checkout. After an uncertain response, investigate before creating a new session.

3. Confirm the outcome#

The customer chooses an eligible payment method in checkout; routing chooses the provider. Creating a session alone does not create a transaction.

A browser return only controls navigation. Verify merchant webhooks and retrieve the owned transaction on your server. Confirm status SUCCESS and the credited amount/currency before fulfilling the order. Keep an auditable association between your order and the resulting transaction; do not assume a session identifier is a transaction UUID.

4. Exercise failure paths#

Test decline, abandoned checkout, delayed completion, duplicate delivery and unavailable payment methods as well as success. Provider capabilities determine which scenarios can actually run.

Search documentation