Payment lifecycle

A Payment is the one object you create, track, and reconcile — whatever the method your customer picks, and whichever provider ends up processing it. This page covers the object, the API state machine, and the full acquiring chain underneath it — from created to reconciled.

The Payment object

Create a payment with POST /v1/payments, retrieve it with GET /v1/payments/{id}. The same shape comes back in webhooks, list responses, and settlement lines. Here is the recurring example order — ord_9f21_0716, €49.00 — after it succeeded:

{
  "id": "pay_8Q2mX4nT1cVb",
  "object": "payment",
  "amount": 4900,
  "amount_captured": 4900,
  "currency": "EUR",
  "status": "succeeded",
  "payment_method": "ideal",
  "reference": "ord_9f21_0716",
  "customer": "cus_4T8nQb2Wp1Zr",
  "provider": "prov_eu_acq_01",
  "provider_attempts": [
    { "provider": "prov_eu_acq_01", "outcome": "approved", "latency_ms": 412 }
  ],
  "risk": null,
  "capture_method": "automatic",
  "amount_refunded": 0,
  "refunded": false,
  "partially_refunded": false,
  "next_action": null,
  "created_at": "2026-07-16T09:24:31Z",
  "livemode": false
}

Lifecycle & statuses

Every payment moves through one state machine, regardless of method or provider. Forward-only: a payment never returns to an earlier status.

Refunds never change status. After success, refund state lives in the flags amount_refunded, partially_refunded and refunded — see Refund state.

Payments skip states they don't need. The canonical request below confirms at create time (the default confirm: true), so the payment is born at requires_action — no requires_confirmation stop:

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
}

The full acquiring chain

The status enum is the API's view. Underneath it runs the acquiring chain every card payment travels — nine stages from your create call to money reconciled in your bank. The first five live on the Payment; the last four live on settlement objects:

Stage by stage, mapped to what you can observe in the API:

Non-card rails compress the chain: bank redirects and real-time payments are single-message (authorization and capture are one step, and the bank's own login replaces 3-D Secure), but every method still ends in the same clear → settle → fund → reconcile tail.

Amounts & minor units

amount is always an integer in the currency's minor unit, per ISO 4217. No floats, ever — 49.00 is rejected with an invalid_request_error.

Rule of thumb: amount = display value × 10^exponent. All derived fields — amount_refunded, refund amount, settlement gross/fee/net — use the same unit, so arithmetic across objects is always integer-safe.

Capture now vs. manual capture

By default (capture_method: "automatic") authorization and capture are one step: processing resolves straight to succeeded. For card payments you can split them — authorize now, capture when you ship:

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": "card",
    "capture_method": "manual",
    "reference": "ord_9f21_0716"
  }'

# → status: "requires_capture" once the authorization is approved

Capture the full amount, or less (for example after a partial shipment). Whatever you don't capture is released back to the customer:

curl https://api.finscale.dev/v1/payments/pay_8Q2mX4nT1cVb/capture \
  -H "Authorization: Bearer sk_test_51FinscaleDemo…" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 4900 }'

# → status: "succeeded". Omit "amount" to capture in full.

• Authorizations expire — capture within 7 days, or the hold is released and the payment moves to canceled.
• Void an authorization you no longer need with POST /v1/payments/{id}/cancel. The hold is released immediately, no fee.
• Manual capture is a card feature. Bank redirects, RTP and wallets are single-message rails — they capture on approval.
• The full pre-auth toolkit — raising a hold with increment_authorization, partial and multiple capture, and void vs. refund semantics — is in Authorization flows.

Multi-currency

Charge in the customer's currency by setting currency — the same integration handles EUR, PLN, BRL, SEK and every other currency your account is enabled for. Three things follow from the currency:

• Method availability. Methods are currency-bound: PIX is BRL-only, Blik is PLN-only, Swish is SEK-only. The method catalog lists each method's currencies.
• Routing. Currency is a hard filter in the routing decision — only providers that process the currency are candidates.
• Settlement. You receive one payout per currency. Optional conversion to a single payout currency is applied at settlement, and every conversion is itemized on the report.

Presentment vs. settlement currency — and exactly when FX applies — is covered in Multicurrency.

Refund state

Refunds are their own objects (rf_…) and never rewind the payment's status. A fully refunded payment still reads status: "succeeded" — with refunded: true. Track refund state through the three flags:

How refunds are created, split, and settled — including the local-method caveats — is covered in Refunds.