# Frame > Developer documentation for Frame, a payments platform. Written for developers integrating Frame into their own products — accepting payments, onboarding accounts, moving money, and handling verification. Each page below is also available as raw Markdown by appending `.md` to its URL. ## Getting started - [Choose an SDK](https://docs.framepayments.com/getting-started/choose-an-sdk): Frame ships a client SDK per platform (web, iOS, Android, React Native) and backend SDKs for your server. This page maps your platform to the right SDK and shows how the two halves pair up. - [Install](https://docs.framepayments.com/getting-started/install): Get API keys, install an SDK if you want one, and make your first authenticated request against the Frame API. - [Quickstart](https://docs.framepayments.com/getting-started/quickstart): Charge a test card from a fresh sandbox account in under five minutes. Four curl commands, one happy path, no setup. - [End-to-end walkthrough](https://docs.framepayments.com/getting-started/walkthrough): A complete merchant integration in four stages — onboard a customer-account, verify their identity, take a payment, and pay them out. Each stage links to its deep guide; this page is the connective tissue showing how the primitives compose. ## Concepts - [Accounts](https://docs.framepayments.com/concepts/accounts/accounts): An account is any party a merchant transacts with on Frame — a buyer who pays, a seller who gets paid, a creator whose identity gets verified. Account is the canonical party model on the platform. - [Capabilities](https://docs.framepayments.com/concepts/accounts/capabilities): A capability is a named permission scoped to an account — what the account is allowed to do on Frame. Card payments, payouts, identity verification, geocompliance — each is its own capability with its own requirements and lifecycle. - [Onboarding](https://docs.framepayments.com/concepts/accounts/onboarding): Onboarding sessions are Frame's hosted UI for collecting the information a capability needs to activate. Create a session, redirect the account holder, and Frame walks them through KYC, identity verification, document upload, and bank account setup. - [Billing credits](https://docs.framepayments.com/concepts/billing/billing-credits): A billing credit is a prepaid balance that decrements as a customer logs usage events. Credits are owned by a customer or account, scoped to a product, and pair with billing meters to model prepaid pricing flows. - [Billing meters](https://docs.framepayments.com/concepts/billing/billing-meters): A billing meter is the definition of how to measure and price one type of customer usage. It carries an event_name (what to track), an aggregation rule (how to combine events), a unit value (how to price), and a status — and serves as the routing target for every BillingMetricEvent your platform logs. - [Metering](https://docs.framepayments.com/concepts/billing/metering): Metering is how Frame measures customer usage of your platform — log events as customers consume something, aggregate them into a metric, then bill against the result. Use it for usage-based pricing, overage billing, and consumption tracking. - [Address Verification](https://docs.framepayments.com/concepts/identity-and-compliance/address-verification): Address verification confirms that the billing address on a payment method matches what the issuer (for cards) or the KYC-verified record (for bank accounts) has on file. Frame runs the check automatically at transaction time. - [Age Verification](https://docs.framepayments.com/concepts/identity-and-compliance/age-verification): Age verification confirms that an account holder meets a minimum age threshold for your platform. It runs against the date of birth collected during KYC — no separate flow, no additional account-holder action. - [Bank Account Verification](https://docs.framepayments.com/concepts/identity-and-compliance/bank-account-verification): Bank account verification confirms that an account holder owns the bank account they're linking, via an instant hosted bank-login flow. No micro-deposits, no multi-day waits — the verification resolves the moment the account holder authenticates with their bank. - [Card Verification](https://docs.framepayments.com/concepts/identity-and-compliance/card-verification): Card verification confirms that a payment card is valid and belongs to the account holder. Frame runs a four-step flow during onboarding — pre-authorization, 3D Secure challenge, code entry, and validation — then voids the auth so the cardholder is never billed. - [Creator Shield](https://docs.framepayments.com/concepts/identity-and-compliance/creator-shield): Creator Shield is a continuous monitoring capability for platforms where creators receive payments. Frame evaluates each inbound payment against adverse media sources and proprietary risk indexes, blocking and restricting accounts that surface as risk before chargebacks or regulatory issues materialize. - [Geocompliance](https://docs.framepayments.com/concepts/identity-and-compliance/geocompliance): Geocompliance enforces geographic restrictions on money movement using spatial geofencing. Frame Sonar captures the account holder's location through the SDK and Frame evaluates it against your platform's geofences at transaction time. - [KYC](https://docs.framepayments.com/concepts/identity-and-compliance/kyc): Know Your Customer (KYC) verifies that an individual account holder is who they say they are. KYC is a capability on an Account — collect the identity fields, hand off to Frame's hosted verification flow, and downstream payment capabilities activate automatically. - [Phone Verification](https://docs.framepayments.com/concepts/identity-and-compliance/phone-verification): Phone verification confirms that an account holder controls the phone number on their account. Frame combines a one-time passcode with passive mobile-identity signals to authenticate without slowing down legitimate users, and anchors the number to the account holder's identity for downstream cross-referencing. - [3D Secure](https://docs.framepayments.com/concepts/money-movement/3d-secure): 3D Secure (3DS) is the network-level authentication protocol that lets card issuers verify the cardholder is present at a charge. Frame triggers it automatically when the rules require, surfaces an authentication UI through frame-js, and stores the resulting cryptogram on the payment method for dispute defense down the line. - [Decline codes](https://docs.framepayments.com/concepts/money-movement/decline-codes): When a card payment fails, Frame attaches a normalized decline code to the failed transfer explaining why. Decline codes split into soft (retryable) and hard (don't retry), and the right merchant response depends on the category — sometimes "ask the customer to try again," sometimes "surface a generic error and don't reveal the underlying reason." - [Disputes](https://docs.framepayments.com/concepts/money-movement/disputes): A dispute is a cardholder-initiated reversal request — they questioned a charge with their issuing bank, and now Frame is in a network-mediated process to either return the funds or defend the original charge with evidence. - [Payment methods](https://docs.framepayments.com/concepts/money-movement/payment-methods): A payment method is the source or destination of funds in a transfer — a card, an ACH bank account, or a wallet credential. One primitive holds every shape, attached to an Account, surfaced through capabilities that determine which flows it can serve. - [Refunds](https://docs.framepayments.com/concepts/money-movement/refunds): A refund returns funds for a previously-successful charge. It's a distinct record on the platform — created against the original transfer or charge intent, settled through the same network the charge ran on, and tracked separately from the parent transaction. - [Sonar](https://docs.framepayments.com/concepts/money-movement/sonar): Sonar is Frame's real-time fraud protection — an AI-powered engine that evaluates every card and bank-account payment for fraud risk before it processes. It runs in the background through frame-js, attaches signals to your charges, and flags or blocks suspicious transactions automatically. - [Transfers](https://docs.framepayments.com/concepts/money-movement/transfers): A transfer is any movement of funds on Frame — money paid in, money paid out, or money moving between accounts. Transfer is the canonical primitive for everything money-related on the platform. - [Events and webhooks](https://docs.framepayments.com/concepts/platform-behavior/events-and-webhooks): Frame emits webhooks when resources change state. Endpoints are managed via the REST API or the dashboard, signed per-endpoint with HMAC-SHA256, delivered with up to 3 retries. This page covers the firing model, signature verification, and reliability patterns. - [Idempotency](https://docs.framepayments.com/concepts/platform-behavior/idempotency): Frame doesn't accept an Idempotency-Key header on its API. Safe retries depend on per-surface patterns — billing events have a dedup key, charges need a query-before-retry shape, and webhook handlers dedupe by event ID. This page covers each pattern. - [Metadata](https://docs.framepayments.com/concepts/platform-behavior/metadata): Most Frame resources accept a metadata field — discrete key/value pairs your platform attaches for internal tracking. Limits are tight (20 entries, 40-char keys, 100-char values) and the storage is record-based, not JSON blob. - [Pagination](https://docs.framepayments.com/concepts/platform-behavior/pagination): Frame's list endpoints use page-based pagination (not cursors). Pass page + per_page query params, read the metadata block on the response, and follow has_more / next to walk through results. - [Coupons](https://docs.framepayments.com/concepts/subscriptions/coupons): A coupon is a reusable discount template — percentage or fixed amount, applied once or repeating across billing cycles. Coupons generate promotion codes that customers redeem at checkout or that platforms apply programmatically to invoices. - [Invoice line items](https://docs.framepayments.com/concepts/subscriptions/invoice-line-items): An invoice line item is a single billable row on an invoice — quantity, unit amount, optional product reference, free-form description. Line items aggregate into the invoice's gross amount before discounts apply. - [Invoices](https://docs.framepayments.com/concepts/subscriptions/invoices): An invoice is a billable document with line items, optional discounts, and a collection method. Invoices are generated automatically by subscriptions on each billing cycle, or created manually for one-off B2B billing flows. - [Product phases](https://docs.framepayments.com/concepts/subscriptions/product-phases): A product phase is a pricing or duration segment attached to a product or subscription. Phases let you model trials, intro pricing, multi-tier ramps, and time-bounded discounts without spawning new products for each variant. - [Products](https://docs.framepayments.com/concepts/subscriptions/products): A Product is the catalog entry for something you sell — either a one-time purchase or a recurring subscription. Products carry pricing, billing cadence, and metadata that downstream primitives (subscriptions, invoices, payment links) reference to compose checkouts. - [Promotion codes](https://docs.framepayments.com/concepts/subscriptions/promotion-codes): A promotion code is the customer-facing redemption handle for a coupon — the string a customer types at checkout or that your platform applies programmatically. Codes wrap coupons with per-customer scoping and redemption limits. - [Subscriptions](https://docs.framepayments.com/concepts/subscriptions/subscriptions): A subscription bills a customer or account on a recurring cadence against a product. Subscriptions carry two state machines (lifecycle + renewal), can be paused and resumed without losing history, capture pricing at creation time, and emit distinct webhooks based on whether they're owned by a customer or an account. ## Guides - [Accept a payment](https://docs.framepayments.com/guides/accepting-payments/accept-a-payment): Charge a customer's card or bank account against a Frame account and route funds to the merchant or a connected account. - [Apply a discount at checkout](https://docs.framepayments.com/guides/accepting-payments/apply-a-discount-at-checkout): Pass promotion codes when you create a charge and Frame validates them, calculates the discount, and reduces the amount charged. Supported on POST /v1/transfers (canonical, charge-backed) and the deprecated POST /v1/charge_intents. - [Build a custom payment page](https://docs.framepayments.com/guides/accepting-payments/build-a-custom-payment-page): Embed frame-js's Card element in your own checkout UI for full control over the layout, copy, styling, and surrounding UX. This guide covers collecting an encrypted card payload on the client and exchanging it server-side for a Frame PaymentMethod your backend can charge. - [Handle 3D Secure](https://docs.framepayments.com/guides/accepting-payments/handle-3d-secure): Run 3D Secure authentication in your checkout flow using frame-js. The SDK handles the issuer's challenge UI automatically; your application just needs to call confirmCardPayment and react to the result. - [Use payment links](https://docs.framepayments.com/guides/accepting-payments/use-payment-links): Create a Frame-hosted checkout URL in the dashboard, share it with customers, and react to completed payments via the transfer.succeeded webhook. Zero integration code. - [Use the payment request button](https://docs.framepayments.com/guides/accepting-payments/use-the-payment-request-button): Add Apple Pay and Google Pay to your checkout in one integration. Frame-js's PaymentRequestButton element detects which wallet the customer's device supports and surfaces the right one — no per-wallet integration required. - [Pay out to an account](https://docs.framepayments.com/guides/accounts/pay-out-to-an-account): Send funds from your platform to an account — a creator, a marketplace seller, a contractor — by activating a payout capability and creating a destination-only transfer. - [Run KYC](https://docs.framepayments.com/guides/accounts/run-kyc): Verify the identity of one of your customers — a buyer, a seller, or any platform user — by adding the kyc capability to their Frame account and routing them through an onboarding session. - [Run onboarding for an account](https://docs.framepayments.com/guides/accounts/run-onboarding): Collect the identity, address, and verification data a Frame account needs by creating an onboarding session and redirecting the account holder to Frame's hosted flow. - [Build postpaid billing](https://docs.framepayments.com/guides/billing/build-postpaid-billing): Customer pays a recurring base fee that includes an allotment of usage; overage events bill on top at the end of each cycle. This guide walks through pairing a subscription with billing meters for the classic "base + overage" billing shape. - [Build prepaid billing](https://docs.framepayments.com/guides/billing/build-prepaid-billing): Customer buys credits upfront, usage decrements the balance, repurchase when depleted. This guide walks through issuing billing credits, attaching meters to products, surfacing the depletion progress, and handling the repurchase flow. - [Build usage-based pricing](https://docs.framepayments.com/guides/billing/build-usage-based-pricing): Charge customers purely on what they consume — no recurring base fee, no included allotment. This guide walks through defining the billing meter, logging events at the right granularity, and turning aggregated usage into an invoice at cycle end. - [Handle declines](https://docs.framepayments.com/guides/risk-and-compliance/handle-declines): When a charge fails, the failure_code tells you why. This guide classifies the common decline codes by what you should do next — retry, surface the error to the customer, require 3DS, or stop trying. - [Handle disputes](https://docs.framepayments.com/guides/risk-and-compliance/handle-disputes): When a cardholder disputes a charge, you have a fixed window to submit evidence proving the transaction was legitimate. This guide covers the API surface — listening for the dispute, gathering the evidence, uploading documents, and submitting your representment. - [Set up Sonar fraud protection](https://docs.framepayments.com/guides/risk-and-compliance/set-up-sonar-fraud-protection): Sonar runs automatically once frame-js is loaded, and forwarding sonar_session_id on each charge is the reliable way to attach the right session. There's no configuration API — this guide covers the integration steps that maximize Sonar's signal quality, plus how to react to fraud-flagged declines. - [Verify a customer's age](https://docs.framepayments.com/guides/risk-and-compliance/verify-a-customers-age): Run identity verification against a customer to confirm they meet your platform's age threshold. Frame collects ID + selfie via the CustomerIdentityVerification API, verifies the DOB against the document, and exposes the result on the customer record. - [Build subscriptions](https://docs.framepayments.com/guides/subscriptions/build-subscriptions): Create a recurring billing flow on Frame — set up a product, attach phases for trial or intro pricing, create the subscription against a customer, and react to renewal webhooks. This guide walks through the end-to-end shape for both B2C and B2B subscription billing. - [Pause and resume a subscription](https://docs.framepayments.com/guides/subscriptions/pause-and-resume-a-subscription): Pause an active subscription to suspend billing without canceling, then resume it manually or on a scheduled date. This guide covers open-ended pauses, scheduled auto-resume via resume_at, finding paused subscriptions, and canceling from the paused state. - [Upgrade or downgrade a subscription](https://docs.framepayments.com/guides/subscriptions/upgrade-or-downgrade-a-subscription): Swap the product on an active subscription via PATCH and let Frame handle the proration. This guide covers the three proration behaviors, when each fits, and how to track the change via webhooks and the subscription change log. ## API reference - [API reference](https://docs.framepayments.com/api-reference/overview): Frame's REST API, organised by resource — plus the cross-cutting conventions (authentication, pagination, errors) that apply across every endpoint. - [3DS Intents](https://docs.framepayments.com/api-reference/endpoints/3ds-intents): Create and poll 3D Secure verification intents. During client-side checkout the SDK creates a 3DS intent for a payment method, redirects the cardholder to the issuer challenge, and polls the intent for completion. Callable with a publishable key. - [Accounts](https://docs.framepayments.com/api-reference/endpoints/accounts): Create and manage connected accounts. Accounts represent the merchants or end users on your platform who send payments, receive payouts, and complete verification flows. Create an account with the capabilities you need, prefill any information you already have, and use hosted onboarding to collect the rest. - [Bank Accounts](https://docs.framepayments.com/api-reference/endpoints/bank-accounts): Create a bank account for a customer or account using a processor token (e.g. from Plaid). - [Billing](https://docs.framepayments.com/api-reference/endpoints/billing): Usage-based billing. Define billing metrics (meters) to track usage events, then generate invoices and reports against accumulated usage. - [Capabilities](https://docs.framepayments.com/api-reference/endpoints/capabilities): Returns all capabilities for the given account. Capabilities are permissions attached to accounts that control what verification flows frameOS runs and what payment methods an account can use. - [Charge Intents](https://docs.framepayments.com/api-reference/endpoints/charge-intents): Create and manage charge intents. A charge intent represents a payment attempt and tracks it through the authorization, capture, and settlement lifecycle. It is the primary object you create to initiate a payment on your platform. - [Charges](https://docs.framepayments.com/api-reference/endpoints/charges): Retrieve charges created from charge intents. A charge is the settled record of a successful payment. - [Coupons](https://docs.framepayments.com/api-reference/endpoints/coupons): Create and manage coupon templates. Coupons define the discount rules — percentage or fixed — that promotion codes are generated from. - [Customer Identity Verifications](https://docs.framepayments.com/api-reference/endpoints/customer-identity-verifications): Initiates a new customer identity verification process by submitting the customer's information. - [Customers](https://docs.framepayments.com/api-reference/endpoints/customers): Create and manage customers. Customers represent the end users or businesses transacting on your platform and are the anchor for payment methods, subscriptions, and invoices. - [Discounts](https://docs.framepayments.com/api-reference/endpoints/discounts): Retrieve and validate discounts. Discounts are applied coupon or promotion code reductions on a charge intent or invoice. - [Disputes](https://docs.framepayments.com/api-reference/endpoints/disputes): Retrieve and respond to disputes. A dispute (chargeback) occurs when a cardholder questions a charge with their bank. Use this API to submit evidence. - [Geo Compliance](https://docs.framepayments.com/api-reference/endpoints/geo-compliance): Evaluates the account's most recent Sonar session and returns the current geocompliance status. Use this endpoint to check whether an account holder is currently in a restricted territory before initiating a transaction. - [Invoices](https://docs.framepayments.com/api-reference/endpoints/invoices): Create and manage invoices. Invoices are statements of amounts owed, generated automatically for subscriptions or created manually for one-time charges. - [KYC Prefill](https://docs.framepayments.com/api-reference/endpoints/kyc-prefill): Confirm KYC prefill data on an account. When you create an account using prefill (Prove live data or sandbox seed data), the account holder must confirm the prefilled identity information before Frame treats it as verified. This endpoint records that confirmation along with the caller's IP and user-agent as evidence of consent, and emits the `frame.account.prefill.completed` event. - [Merchant Balance](https://docs.framepayments.com/api-reference/endpoints/merchant-balance): Returns the current balance for the authenticated merchant, including available funds, reserved amounts, and pending payouts. - [Onboarding Sessions](https://docs.framepayments.com/api-reference/endpoints/onboarding-sessions): Bootstraps the frame-onboarding embedded Web Component from a client_secret. - [Payment Link Sessions](https://docs.framepayments.com/api-reference/endpoints/payment-link-sessions): Create a new payment link session - [Payment Methods](https://docs.framepayments.com/api-reference/endpoints/payment-methods): Create and manage payment methods. Payment methods represent the funding instruments — cards, bank accounts — attached to customers or accounts. - [Payouts](https://docs.framepayments.com/api-reference/endpoints/payouts): Create payouts. Payouts disburse funds from your merchant balance to an external bank account or card. - [Phone Verifications](https://docs.framepayments.com/api-reference/endpoints/phone-verifications): Initiates a phone verification for the given account by sending a one-time passcode (OTP) via SMS to the account's phone number. frameOS evaluates mobile identity signals in the background — including the number's trust score, carrier information, and behavioral characteristics — to determine whether the user presents a risk. - [Products](https://docs.framepayments.com/api-reference/endpoints/products): Create and manage products. Products define the goods or services you offer, along with their pricing, billing interval, and phase schedules. - [Promotion Codes](https://docs.framepayments.com/api-reference/endpoints/promotion-codes): Create and manage promotion codes. Promotion codes are the customer-facing discount codes generated from coupon templates and applied at checkout. - [Refunds](https://docs.framepayments.com/api-reference/endpoints/refunds): Create and retrieve refunds. Refunds return all or part of a charge back to the original payment method. - [Subscriptions](https://docs.framepayments.com/api-reference/endpoints/subscriptions): Create and manage subscriptions. Subscriptions represent recurring billing relationships between your platform and a customer, tied to a product and billing interval. - [Terms Of Service](https://docs.framepayments.com/api-reference/endpoints/terms-of-service): Generate a short-lived terms of service token for the authenticated merchant. Pass this token to the update endpoint once the user has accepted the terms. - [Transfers](https://docs.framepayments.com/api-reference/endpoints/transfers): Create and retrieve transfers. Transfers move funds between your platform and connected accounts. - [Webhooks](https://docs.framepayments.com/api-reference/endpoints/webhooks): Manage webhook endpoints. Frame sends real-time event notifications to your registered endpoints as objects on your account change state. - [Backend SDKs](https://docs.framepayments.com/api-reference/integrations/backend-sdks): Server-side libraries for calling the Frame API from your backend. Install-only landing — full method reference lives in each repo. - [Currencies](https://docs.framepayments.com/api-reference/integrations/currencies): The currencies Frame processes and how to specify them in API requests. Pass a three-letter ISO code (case-insensitive); amounts are always in the smallest unit. - [Mobile SDKs](https://docs.framepayments.com/api-reference/integrations/mobile-sdks): Native and cross-platform SDKs for accepting payments in iOS, Android, and React Native apps. Links to each SDK's repo and documentation. - [Pagination](https://docs.framepayments.com/api-reference/integrations/pagination): Every list endpoint on the Frame API uses the same page + per_page pagination shape. Results come back with a meta object that tells you whether more pages exist. - [Rate limits](https://docs.framepayments.com/api-reference/integrations/rate-limits): Frame caps requests per minute on a per-merchant, per-endpoint basis. Most endpoints allow 160 requests/minute in live mode and 50 in sandbox; high-throughput endpoints carry larger caps. Over-limit requests get HTTP 429. - [Testing](https://docs.framepayments.com/api-reference/integrations/testing): Simulate payments without moving real money. Use test API keys, the test cards on this page, and ACH test account numbers to exercise the happy path, declines, 3D Secure flows, and bank-account flows before going to production. - [Web SDKs](https://docs.framepayments.com/api-reference/integrations/web-sdks): Client-side libraries for accepting payments in the browser. Tokenization, payment requests, onboarding, and Terms of Service — all rendered as iframes for PCI scope minimization. - [Webhooks](https://docs.framepayments.com/api-reference/integrations/webhooks): Register an HTTPS endpoint, subscribe to event codes, verify the X-Frame-Signature header, and process events idempotently. Endpoint management is fully API-driven in V1. - [Frame.js](https://docs.framepayments.com/api-reference/integrations/web-sdks/frame-js): Browser SDK for tokenizing cards, accepting wallet payments, embedding onboarding, and capturing Terms of Service acceptance. Loaded via CDN; integrates with any frontend framework. - [Architecture](https://docs.framepayments.com/api-reference/integrations/web-sdks/frame-js/architecture): Every Frame.js integration involves three actors — your frontend, your backend, and the Frame API. Understanding how they split responsibility is the load-bearing model for everything else in this SDK. - [Card](https://docs.framepayments.com/api-reference/integrations/web-sdks/frame-js/card): The card-collection element. - [Card configurations](https://docs.framepayments.com/api-reference/integrations/web-sdks/frame-js/card-configurations): The Card element collects payment details by default and can be extended in-place to also capture a billing address (Mapbox-powered autocomplete) and identity fields (name, email, phone). Four composition recipes — pick the one that matches your checkout. - [Embed onboarding](https://docs.framepayments.com/api-reference/integrations/web-sdks/frame-js/embed-onboarding): Three server-side steps to prepare a session before opening the embedded onboarding component in the browser. Distinct from the FrameOnboarding component reference — this page covers the backend prep that mints the client_secret. - [Embedded Onboarding](https://docs.framepayments.com/api-reference/integrations/web-sdks/frame-js/embedded-onboarding): Custom element () that hosts Frame's merchant onboarding flow. - [Frame](https://docs.framepayments.com/api-reference/integrations/web-sdks/frame-js/frame): Entry point for the Frame browser SDK. - [Installation](https://docs.framepayments.com/api-reference/integrations/web-sdks/frame-js/installation): Drop the Frame.js script tag into your page, initialize the SDK with your publishable key, and switch between sandbox and production environments. - [Payment Request Button](https://docs.framepayments.com/api-reference/integrations/web-sdks/frame-js/payment-request-button): The Apple Pay / Google Pay button element. - [Terms of Service](https://docs.framepayments.com/api-reference/integrations/web-sdks/frame-js/terms-of-service): Renders Frame's Terms of Service component — a short legal preamble with links to Frame's Privacy Policy, Terms of Service, and Platform Agreement, plus an optional accept button.