Fortion API documentation

Connect a merchant in five steps

Use one shop for one merchant payment context. The shop owns its routes, integration tokens and webhook secret, so credentials never need to cross company boundaries.

1. 1

   Prepare the shop

   Ask Fortion to activate the company, shop and at least one payment route.

2. 2

   Create server credentials

   In Merchant Admin open the shop → Integration. Add a public HTTPS endpoint, create a webhook secret, then create a server key with “Pay-ins and payouts” permissions.

3. 3

   Create a payment

   Send one server request and redirect the customer to the returned checkoutUrl.

4. 4

   Confirm the result

   Verify the signed webhook. A browser redirect is useful for UX, but is not proof of payment.

5. 5

   Create payout requests

   Send safe recipient references only. Track review and execution status from your server.

Keep both secrets on your server

The integration token authorizes API calls. The webhook secret verifies events sent by Fortion. Both are displayed only once and must remain server-side only.

Authorization: Bearer sdk.sit_xxx.your_secret
Content-Type: application/json

Permissions

Trust signed webhooks, not redirects

Fortion sends JSON events to the shop’s public HTTPS endpoint. Return 2xx only after your system persists the event. Failed deliveries are retried from a durable queue.

Headers

x-fortion-event-id: mwe_123
x-fortion-event-type: payment.completed
x-fortion-signature-timestamp: 2026-07-28T12:00:00.000Z
x-fortion-signature: v1=<hex>

Verify HMAC SHA-256 on the raw body

Build the signed value as ${timestamp}.${rawBody}. Reject timestamps older than five minutes and process every event idempotently by event ID.

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyFortionWebhook({ rawBody, timestamp, signature, secret }) {
  if (!signature?.startsWith("v1=")) return false;

  const age = Math.abs(Date.now() - Date.parse(timestamp));
  if (!Number.isFinite(age) || age > 5 * 60 * 1000) return false;

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`, "utf8")
    .digest("hex");
  const received = signature.slice(3);
  const left = Buffer.from(received, "hex");
  const right = Buffer.from(expected, "hex");

  return left.length === right.length && timingSafeEqual(left, right);
}

Retry with the same merchant identifier

For both pay-ins and payouts, the same identifier and the same payload return the existing resource. The same identifier with a different payload returns 409 Conflict.

Handle errors by HTTP status

Run the reference merchant locally

The repository includes a small merchant site that calls the same pay-in and payout endpoints from its backend. Copy the environment template, add a non-production token, then run:

cd examples/merchant-quickstart
cp .env.example .env
npm start

API reference