# List payment provider candidates

Read provider catalog candidates for a direct integration scope. This list is not final routing eligibility or a provider readiness result.

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

## Request






## Example response






## Integration notes

An empty list means no catalog candidates for this scope. A non-empty list does not certify current routing eligibility, external credentials, FX conversion or provider health.

Call from your server with signed headers. Query parameters are excluded from the HMAC path.

Hosted checkout handles method eligibility separately and routing selects the provider. Do not use the legacy cashier options endpoint as a signed-header-only merchant API.




## Endpoint

GET /api/v1/providers/payment-options

- amount (query, required): Requested major-unit amount.
- currency (query, required): Three-letter currency code.
- paymentMethod (query, required): Internal payment method, for example CARD.
- type (query, required): DEPOSIT or PAYOUT.
- mode (query, optional): Defaults to LIVE. Explicitly send SANDBOX while testing.
- regionId (query, optional): Merchant region ID for regional filtering.

### 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/providers/payment-options?amount=10.00&currency=EUR&paymentMethod=CARD&type=DEPOSIT&mode=SANDBOX';
const method = 'GET';
const body = '';
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'
  }
});
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 (200)

```json
[]
```
