How Finscale works

You integrate one REST API. Behind it, Finscale screens each payment for risk, routes it to the provider most likely to approve it, fails over when one doesn't, and settles the money back to your bank — with one report to reconcile. This page is the whole system on one screen.

The architecture

Five parts, one direction of flow. Your server talks to the gateway; the gateway talks to providers; providers clear funds into settlement; settlement pays out to your bank.

Providers are always opaque ids (prov_eu_acq_01, …). You never integrate, contract, or hold credentials for one — Smart routing explains why that abstraction holds.

What happens to one payment

Take the recurring example — order ord_9f21_0716, €49.00. From your POST /v1/payments to money in your bank:

1. Create

   Your server creates a Payment: "amount": 4900, "currency": "EUR". Finscale validates the request, applies your Idempotency-Key, and assigns pay_8Q2mX4nT1cVb.

2. Screen

   For card-family payments, the risk engine scores the transaction (0–99) and decides: approved, review, or blocked. Approved payments continue; blocked ones fail before any provider is touched.

3. Authenticate

   If the customer must act — a bank redirect, a 3-D Secure challenge — the payment waits in requires_action and next_action.url tells you where to send them.

4. Route

   The routing engine ranks eligible providers by auth-rate, health, cost, and your rules, then submits the transaction. If the first provider times out or errors, failover retries the next — inside the same API call.

5. Capture

   On approval the payment reaches succeeded (or holds in requires_capture if you chose manual capture). A payment.succeeded webhook tells your server to fulfil.

6. Settle

   The provider clears the funds. Finscale normalizes every provider's files into one settlement report (stl_…) and pays the net out (po_…) to your bank — one payout per currency.

What you build vs. what Finscale runs

The five objects that matter

The API surface is small. Almost everything hangs off the Payment:

One request, end to end

The canonical create call. In test mode the whole chain — routing, webhooks, settlement reports — runs against simulated providers:

curl https://api.finscale.dev/v1/payments \
  -H "Authorization: Bearer sk_test_51FinscaleDemo…" \
  -H "Idempotency-Key: idem_ord_9f21_0716" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4900,
    "currency": "EUR",
    "payment_method": "ideal",
    "reference": "ord_9f21_0716",
    "customer": { "email": "anna@example.com" },
    "return_url": "https://shop.example.com/checkout/return"
  }'

{
  "id": "pay_8Q2mX4nT1cVb",
  "object": "payment",
  "amount": 4900,
  "currency": "EUR",
  "status": "requires_action",
  "payment_method": "ideal",
  "reference": "ord_9f21_0716",
  "provider": "prov_eu_acq_01",
  "next_action": {
    "type": "redirect",
    "url": "https://pay.finscale.dev/r/8Q2mX4nT"
  },
  "created_at": "2026-07-16T09:24:31Z",
  "livemode": false
}

Where to go next

• Quickstart — first payment in five minutes.
• Hosted checkout vs. API integration — pick your integration surface.
• Payment lifecycle — every status, and the full acquiring chain from created to reconciled.
• Smart routing — the decision engine, failover, and provider_attempts.
• Settlement & payouts — how money reaches your bank.