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.
Illustrative examples · merchant-scoped · API key and HMAC required
Request#
| Field | Use | Description |
|---|---|---|
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 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#
{
"id": 100123,
"uuid": "6f1c0c8e-0d62-4a0f-a913-57c6e45d7c21",
"type": "DEPOSIT",
"status": "CREATED",
"amount": 10,
"currency": "EUR",
"merchantReference": "order-example-001",
"redirectUrl": null
}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.
