# Your first hosted checkout

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

Canonical: https://docs-firehorsepay.powerwebhub.com/getting-started
Updated: 2026-11-22; API v1

## 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.


- [Request fields and signed examples](https://docs-firehorsepay.powerwebhub.com/api/checkout-sessions)

## 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.


- [Verify and process webhooks](https://docs-firehorsepay.powerwebhub.com/webhooks)
- [Hosted checkout details](https://docs-firehorsepay.powerwebhub.com/guides/hosted-checkout)

## 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.


- [Follow the test checklist](https://docs-firehorsepay.powerwebhub.com/testing)