Quickstart

Authentication

Every request is authenticated with a secret API key sent in the x-api-key header. Keys are environment-scoped - a ps_test_... key hits sandbox, a ps_live_... key hits live. Create and reveal keys once from your dashboard under API Keys.

API Keys

# every sandbox request carries your key
Authorization is via header:
  x-api-key: ps_test_example_key

Your first charge

Post a single JSON request to the charge endpoint. FlowAcq screens it for fraud, applies the configured live provider path, and returns a normalized result synchronously. Health and cost routing expand as approved providers come online.

Amounts are in the currency's minor units (e.g. 4200 = $42.00). The response returns a transaction id, status, and the provider that handled it.

POST /v1/orchestration/charge
Content-Type: application/json
x-api-key: ps_test_example_key
Idempotency-Key: charge_8f2c1a90

{
  "amount": 4200,
  "currency": "USD",
  "paymentMethod": { "token": "tok_visa" },
  "metadata": { "orderId": "A-10294" }
}

Idempotency

Send an Idempotency-Key header on any state-changing request. Retrying with the same key returns the original result instead of charging twice - safe to retry on timeouts and network blips.

Verifying webhooks

Every event is delivered with an x-paysys-signature header - an HMAC-SHA256 of the raw body, keyed with your endpoint's signing secret. Compute the same HMAC and compare in constant time before trusting the payload.

Deliveries are logged with payload, response, and a one-click replay in the dashboard, so you can re-drive any event while you build.

const expected = crypto
  .createHmac("sha256", endpointSecret)
  .update(rawBody)            // the exact bytes received
  .digest("hex");

const ok = crypto.timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(req.headers["x-paysys-signature"])
);

Sandbox vs live

Sandbox mirrors live exactly - same endpoints, same payloads - using your ps_test_... key, with no money moved. Switch to a ps_live_... key once your business is approved through KYB.