Payment methods

{
  "amount": 4900,
  "currency": "EUR",
  "payment_method": "ideal",
  "reference": "ord_9f21_0716",
  "customer": { "email": "anna@example.com" },
  "return_url": "https://shop.example.com/checkout/return"
}

No details object needed — the customer picks their bank on the redirect page. You get back next_action.type: "redirect"; send the customer to next_action.url and wait for the webhook. return_url is required for every redirect method.

Buy now, pay later uses the exact same shape: set payment_method to klarna, affirm, or afterpay_clearpay and the customer completes the provider's approval flow behind next_action.url. You are paid up front, in full — the BNPL provider carries the installments and the credit risk.

// 1. Finscale checkout components wrap the device's encrypted
//    payment token into a one-time tok_… — exchange it:
// POST /v1/payment_methods
{ "type": "apple_pay", "token": "tok_8Rc4kY2mVs" }
// → { "id": "pm_3Kd8wQ5rN2Xv", … }

// 2. Charge it — POST /v1/payments
{
  "amount": 4900,
  "currency": "EUR",
  "payment_method": "apple_pay",
  "payment_method_id": "pm_3Kd8wQ5rN2Xv",
  "reference": "ord_9f21_0716"
}

Behind the pm_… sits the device's encrypted payment token — Finscale decrypts it and routes it like a card, so device-wallet payments inherit card routing and failover. App wallets (PayPal, Alipay, WeChat Pay, Cash App Pay, Kakao Pay, MobilePay, Vipps, TWINT, Satispay, GrabPay, GoPay) skip the instrument step entirely and return a redirect next_action that opens or deep-links the wallet app.

// UPI — the hosted page collects the customer's VPA and
// pushes an approval request to their UPI app
{
  "amount": 419900,
  "currency": "INR",
  "payment_method": "upi",
  "reference": "ord_9f21_0716",
  "return_url": "https://shop.example.com/checkout/return"
}
// → next_action: { "type": "redirect", "url": "https://pay.finscale.dev/r/7Nu4pV2r" }

// PIX — the hosted page shows a QR code for the banking app
{
  "amount": 26500,
  "currency": "BRL",
  "payment_method": "pix",
  "reference": "ord_9f21_0716",
  "return_url": "https://shop.example.com/checkout/return"
}
// → next_action: { "type": "redirect", "url": "https://pay.finscale.dev/r/2Xw9cJ6p" }

Every RTP method returns a redirect next_action: the Finscale-hosted page collects the UPI VPA, shows the PIX, PayNow, or PromptPay QR code, collects the 6-digit Blik code, or takes the phone number that MB Way pushes an approval prompt to. RTP payments confirm in seconds; the terminal webhook is the source of truth.

{
  "amount": 89900,
  "currency": "MXN",
  "payment_method": "oxxo",
  "reference": "ord_9f21_0716",
  "customer": { "email": "anna@example.com" },
  "return_url": "https://shop.example.com/checkout/return"
}
// → next_action: { "type": "redirect", "url": "https://pay.finscale.dev/r/6Tb3wM8k" }

The hosted page behind next_action.url issues the cash reference — a barcode for OXXO and Konbini, a numbered slip for Boleto, an entity + reference pair for Multibanco. The customer then pays at a store, bank, or ATM, so the flow is asynchronous: the payment stays requires_action until the scheme reports the cash, then payment.succeeded fires — hours or days later. Unpaid vouchers expire to failed. Fulfill from the webhook, never from the return redirect.

{
  "amount": 4900,
  "currency": "EUR",
  "payment_method": "sepa_debit",
  "payment_method_id": "pm_9Sd4bT7kW2Qn",
  "reference": "ord_9f21_0716",
  "customer": { "email": "anna@example.com" }
}

The pm_… instrument carries the IBAN and the SEPA mandate — hosted checkout collects both and records mandate acceptance, then POST /v1/payment_methods (type: "sepa_debit" + the checkout token) turns them into a reusable instrument. Direct debit is asynchronous: the payment sits in processing for 2–5 business days before payment.succeeded — and can still be returned after that (see chargeback risk).

Every direct-debit method follows the same mandate model, each under its local scheme's rules: ACH carries routing and account numbers under an ACH authorization, Bacs (UK) a Direct Debit Instruction, BECS (Australia/New Zealand) a Direct Debit Request, and ACSS (Canada) a pre-authorized debit agreement. Hosted checkout records the right mandate text per scheme; the instrument is reusable until the mandate is revoked.

{
  "amount": 4900,
  "currency": "EUR",
  "payment_method": "usdc",
  "reference": "ord_9f21_0716",
  "return_url": "https://shop.example.com/checkout/return"
}
// → next_action: { "type": "redirect", "url": "https://pay.finscale.dev/r/9Fc1nS8v" }

You price in fiat; the hosted page behind next_action.url quotes the USDC amount, shows a one-time deposit address, and confirms on-chain receipt. Settlement lands in your normal payout, in fiat or USDC per your account settings. Transfers are irreversible — refunds go back to the sending address as a new transfer.