API reference

The Fraction API is served over HTTPS with JSON request and response bodies. All timestamps are Unix seconds in UTC unless noted. Resource identifiers use predictable prefixes so you can spot object types at a glance in logs and support tickets.

Base URL. Production traffic should target https://api.yourfraction.co/v1. Sandbox hosts mirror the same paths under a dedicated sandbox base if your workspace is provisioned for non-production traffic.

Every request must include a secret API key in the Authorization header using the Bearer scheme. Keys are issued from the Fraction dashboard and can be rotated without downtime when you maintain overlapping validity windows.

Format. Authorization: Bearer fr_live_[secret]. Treat secrets like passwords: store them in a vault, never in client-side code, and never in public repositories.

• Use TLS 1.2 or newer end to end.
• Prefer narrow, least-privilege keys per service.
• Retry 429 responses with exponential backoff and jitter.

Creates a payment intent that captures funds from a tokenized source. Amounts are always integer cents in the minor unit of the provided currency. The customer block should contain stable contact details for receipts and risk review.

Required fields. amount, currency, customer, and source (a single-use Fraction token representing the payer instrument).

Optional split payment. Include split_payment with deposit_cents and balance_cents. Both must be positive integers and must sum to amount. When present, Fraction schedules the deposit capture first, then exposes the remaining balance on the same payment object until it is fully satisfied.

Send a unique Idempotency-Key per logical operation so safe retries never double-charge.

Fetches the latest payment object, including lifecycle fields such as status and, when applicable, the current split_payment.phase value so your dashboards can show deposit paid versus fully settled without polling card networks directly.

Replace the path segment with a concrete payment id such as fr_pay_892347c1e4a0b2f9.

Persists a reusable customer record you can attach to future payments, subscriptions, or payout profiles. Email must be unique per workspace. Metadata accepts up to sixteen string keys for your own reconciliation labels.

Responses return an fr_cus_ identifier you should store as the canonical customer key in your systems.

Fraction posts JSON event envelopes to your HTTPS endpoint. Each delivery includes a timestamped signature so you can reject replayed or tampered payloads before you mutate internal ledger state.

Verifying signatures. Concatenate the timestamp, a literal period, and the raw request body, then compute HMAC-SHA256 with your endpoint signing secret (for example fr_whsec_9c21b4e8a0f3). Compare the result in constant time to the hex digest provided in the Fraction-Signature header for the same timestamp.

Event type. Listen for fraction.payment.succeeded to mark orders paid, unlock digital goods, or notify fulfillment. Always fetch the payment by id before trusting nested amounts in the webhook body alone.

• Return 2xx quickly, then process asynchronously.
• Store and ignore duplicate event ids.
• Rotate signing secrets from the dashboard without downtime.