# Create a payment or payout

Validate and persist an operation, route it and enqueue provider initiation. A 201 response confirms creation; the provider result may arrive later.

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

## Request






## Example response






## Integration notes

An initial CREATED response can have no redirectUrl. Poll the owned transaction or handle its webhook until initiation finishes.

If redirectUrl is present, send the payer to the provider checkout. A browser return is not proof of payment.

A duplicate create returns 409 rather than the original 201 body. Recover the original operation using your persisted transaction ID/reference; do not issue another operation with a new key.

Provider selection is normally handled by routing. Only pin providerCode for a deliberate integration/test scope.




## Endpoint

POST /api/v1/transactions

- type (required): DEPOSIT or PAYOUT. Payout requires a supporting provider, capability and recipient fields.
- amount (required): Positive decimal major units; prefer decimal strings.
- currency (required): Three-letter currency code supported in the selected scope.
- paymentMethod (required): Enabled internal method, for example CARD.
- merchantReference (required): Unique reference for this logical order or operation.
- Idempotency-Key (required): UUID header, or idempotencyKey in the request body. Persist it before sending.
- mode (optional): SANDBOX or LIVE; omitted mode defaults to LIVE.
- regionId (optional): Your merchant region ID. It is not a global region ID.
- customerEmail / customerFields (conditional): Valid payer email and fields required by your capability/provider.
- successUrl / failUrl (optional): Absolute return URLs. Valid merchant defaults may be used.
- flow (optional): REDIRECT by default; H2H requires a suitable integration.

### 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/transactions';
const method = 'POST';
const body = JSON.stringify({
  "type": "DEPOSIT",
  "amount": "10.00",
  "currency": "EUR",
  "paymentMethod": "CARD",
  "merchantReference": "order-example-001",
  "mode": "SANDBOX",
  "customerEmail": "sandbox-payer@example.com"
});
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 idempotencyKey = process.env.ORDER_IDEMPOTENCY_KEY;
if (!idempotencyKey) throw new Error('Persist an order UUID before sending');
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', 'Idempotency-Key': idempotencyKey
  },
  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
{
  "id": 100123,
  "uuid": "6f1c0c8e-0d62-4a0f-a913-57c6e45d7c21",
  "type": "DEPOSIT",
  "status": "CREATED",
  "amount": 10,
  "currency": "EUR",
  "merchantReference": "order-example-001",
  "redirectUrl": null
}
```
