# Create a hosted checkout session

Create an expiring checkout URL on your server. The customer chooses an eligible payment method in Firehorse checkout.

Canonical: https://docs-firehorsepay.powerwebhub.com/api/checkout-sessions
Updated: 2026-11-22; API v1

## Request






## Example response






## Integration notes

Creating a session does not create a transaction. A transaction is created when a method is selected.

This endpoint is not idempotent. Store and reuse the returned URL for the same checkout; do not create another session automatically after a timeout.

merchantReference is not accepted by this endpoint. Keep the checkout/order association on your server.

Treat checkoutUrl as a short-lived capability. Do not place an API key in a browser URL.




## Endpoint

POST /api/v1/checkout/sessions

- amount (required): Positive decimal amount in major units. Read it from your trusted order data.
- currency (required): Three-letter currency code.
- mode (optional): SANDBOX or LIVE. The server default is LIVE; always send SANDBOX when testing.
- country (optional): Two-letter payer country when known.
- returnTo (optional): Absolute HTTP(S) return URL.

### Node.js server example

```javascript
// Node.js 18+ · server only. No browser API key.
import { createHash, createHmac, randomUUID } from 'node:crypto';

const key = process.env.FIREHORSE_API_KEY;
if (!key) throw new Error('Set FIREHORSE_API_KEY on the server');
const path = '/api/v1/checkout/sessions';
const method = 'POST';
const body = JSON.stringify({
  "amount": "10.00",
  "currency": "EUR",
  "mode": "SANDBOX",
  "returnTo": "https://merchant.example.com/payment-return"
});
const timestamp = String(Math.floor(Date.now() / 1000));
const nonce = randomUUID();
const hash = createHash('sha256').update(body, 'utf8').digest('hex');
const canonical = [method, path.split('?')[0], timestamp, nonce, hash].join('\n');
const signature = createHmac('sha256', key).update(canonical).digest('hex');
const response = await fetch('https://firehorsepay.powerwebhub.com/transaction' + path, {
  method, redirect: 'error',
  headers: {
    'X-API-KEY': key, 'X-TIMESTAMP': timestamp,
    'X-NONCE': nonce, 'X-SIGNATURE': signature,
    'Content-Type': 'application/json'
  },
  body
});
const result = await response.json();
if (!response.ok) {
  // Reconcile uncertain results and 409; do not blindly create another order.
  throw new Error('Firehorse HTTP ' + response.status);
}
// Store result securely. A 201/CREATED is not a confirmed payment.
```

### Example response (201)

```json
{
  "checkoutUrl": "https://firehorsepay.powerwebhub.com/transaction/api/v1/checkout/page?checkoutSession=EXAMPLE_CAPABILITY_TOKEN",
  "expiresAt": "2026-11-22T12:30:00Z"
}
```
