# Payrails Docs > Developer and operator documentation for Payrails, the payment operating system for global enterprises: payment orchestration across providers, PCI-compliant tokenization, analytics and reporting, Chargebacks, and the Payrails REST API. ## Agent Instructions Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code. Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it. Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code. Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation. Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent. Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format. Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code. Append `.md` to any documentation URL to fetch its Markdown source. Every page is listed in https://docs.payrails.com/sitemap.xml, and the full text of the core guides is at https://docs.payrails.com/llms-full.txt ## Start here Entry points into the Payrails documentation. - [Start here: Guides and API reference](https://docs.payrails.com/index.md): Guides, SDKs, and API reference for Payrails: enable payment methods, connect PSPs, and launch checkout on web, iOS, Android, and React Native. ## Getting Started What Payrails is, and the account, workspace, credential and authentication setup that every integration starts with. - [Getting Started: Explore Payrails](https://docs.payrails.com/docs/explore-payrails.md): Browse the Payrails product suite, from payment orchestration and checkout SDKs to Token Vault, chargebacks, and analytics. - [Core concepts: How Payrails works](https://docs.payrails.com/docs/overview.md): Learn what the Payrails modules cover, from orchestration and routing to the PCI vault, and the five steps from account setup to going live. - [Core concepts: Workflows](https://docs.payrails.com/docs/overview/workflows.md): Learn how workflows, executions, and actions fit together in Payrails, with example use cases from payment acceptance to payouts. - [Core concepts: Checkout](https://docs.payrails.com/docs/overview/checkout.md): Choose an SDK or API integration for checkout, set up payment options and routing, handle notifications, and capture or refund payments. - [Core concepts: Dynamic Routing](https://docs.payrails.com/docs/overview/routing.md): Learn how Payrails dynamic routing sends payments to different PSPs and fraud providers to lower fees, prevent fraud, and cut failures. - [Core concepts: Payment Options](https://docs.payrails.com/docs/overview/payment-options.md): Control which payment methods and saved instruments each customer sees at checkout, and look them up through the drop-in or the API. - [Core concepts: Token Vault](https://docs.payrails.com/docs/overview/vault.md): Tokenize any sensitive data, store in a PCI-certified environment and used stored tokens, as a standalone module or within your orchestration workflows. - [Account setup: Set up your Payrails account and environment](https://docs.payrails.com/docs/account-setup.md): Set up the account foundations every Payrails module shares: API credentials and mTLS, users and roles, and workspaces. - [Account setup: API Credentials](https://docs.payrails.com/docs/account-setup/api-credentials.md): Create and manage the client ID and client secret that authenticate your Payrails API calls, scoped per environment and workspace. - [Account setup: mTLS Configuration](https://docs.payrails.com/docs/account-setup/mtls-configuration.md): Request, download, rotate, and revoke mTLS client certificates in the Payrails Portal, then test them with curl or Postman. - [User Management](https://docs.payrails.com/docs/account-setup/user-management.md): Learn how role-based access control works in the Payrails Portal and get guidance on strong passwords and account security. - [User Management: Authentication](https://docs.payrails.com/docs/account-setup/user-management/authentication.md): Compare SSO and non-SSO sign-in for the Payrails Portal, including how each user type gets its role and how to request SSO activation. - [User Management: Roles & Permissions](https://docs.payrails.com/docs/account-setup/user-management/roles-permissions.md): Check which actions each organization and workspace role can perform, with a permissions matrix for every Payrails service and Portal area. - [User Management: Frequently Asked Questions](https://docs.payrails.com/docs/account-setup/user-management/frequently-asked-questions.md): Find answers to common questions about Payrails Portal roles, permissions, passwords, unauthorized access, and 405 errors when using SSO. - [User Management: Single Sign-On](https://docs.payrails.com/docs/account-setup/user-management/single-sign-on.md): Configure SAML single sign-on for the Payrails Portal with Okta or another identity provider, then test and troubleshoot it. - [Account setup: Organization](https://docs.payrails.com/docs/account-setup/organization.md): See how the organization context groups your Payrails workspaces, with organization and workspace roles, invitations, and global insights. - [Account setup: Workspaces](https://docs.payrails.com/docs/account-setup/workspaces.md): Learn how to split your Payrails account into workspaces by country, region, or business line, create them, and link executions to them. - [Account setup: Idempotent Requests](https://docs.payrails.com/docs/account-setup/idempotent-requests.md): Use the X-Idempotency-Key header to retry a Payrails API request safely, without creating duplicate records or repeating an update. ## Payment Orchestration Accept payments across providers: the payment lifecycle (authorize, capture, cancel, refund, 3DS, notifications), Autopilot routing, Workflow Studio, in-person payments and payment links. - [Payment Orchestration](https://docs.payrails.com/docs/orchestration.md): Start with Payment Orchestration: choose between the Drop-in, Elements, Secure Fields and API-only integration paths, then connect your providers. - [Payment Orchestration: Accept payments via API](https://docs.payrails.com/docs/orchestration/accept-payments-via-api.md): Build your own checkout on the Payrails API, using Secure Fields or client-side encryption to tokenize card data. - [Meta fields](https://docs.payrails.com/docs/orchestration/meta-fields.md): Send meta fields with your executions so Payrails maps them to each provider's fields, and check which ones your setup requires. - [Meta fields: Order costs](https://docs.payrails.com/docs/orchestration/meta-fields/order-costs.md): Send an order's shipping, discounts and taxes in the order meta field, as order-level totals or per line, with a worked example. - [Payment Acceptance: Create a workflow execution](https://docs.payrails.com/docs/orchestration/payment-acceptance/create-a-workflow-execution.md): Create an execution of the payment-acceptance workflow through the Payrails API, the first call in every payment. - [Payment Acceptance: Lookup payment options](https://docs.payrails.com/docs/orchestration/payment-acceptance/lookup-payment-options.md): Call the lookup endpoint to resolve which payment methods and instruments to present, from the rules you set in the Payrails Portal. - [Payment Acceptance: Authorize a payment](https://docs.payrails.com/docs/orchestration/payment-acceptance/authorize-a-payment.md): Authorize a payment on an existing workflow execution, and receive the outcome through a notification or by polling the execution. - [Payment Acceptance: Capture a payment](https://docs.payrails.com/docs/orchestration/payment-acceptance/capture-a-payment.md): Capture an authorized payment through the Payrails API or Portal, in full or in part, or set a delay instead of automatic capture. - [Payment Acceptance: Capture and cancel modes](https://docs.payrails.com/docs/orchestration/payment-acceptance/capture-and-cancel-modes.md): Choose between one-step and two-step authorization in Payrails, and set the Instant, Manual or Delayed capture mode for each workflow. - [Payment Acceptance: Cancel a payment](https://docs.payrails.com/docs/orchestration/payment-acceptance/cancel-a-payment.md): Cancel a payment with one call: Payrails voids an uncaptured authorization, or refunds the amount after a capture. - [Payment Acceptance: Refund a payment](https://docs.payrails.com/docs/orchestration/payment-acceptance/refund-a-payment.md): Refund a captured payment in full or in part through the Payrails API or the Portal, including several partial refunds on the same payment. - [Payment Acceptance: Test payments](https://docs.payrails.com/docs/orchestration/payment-acceptance/test-payments.md): Simulate payments in the Payrails Portal to verify provider configurations, dynamic payment options, and notification handling. - [Payment Acceptance: Receive notifications](https://docs.payrails.com/docs/orchestration/payment-acceptance/receive-notifications.md): Set up webhook endpoints to receive the outcome of asynchronous Payrails actions such as authorize, capture, cancel, and refund. - [Payment Acceptance: 3D Secure](https://docs.payrails.com/docs/orchestration/payment-acceptance/3d-secure.md): Handle a 3D Secure challenge inside a Payrails authorization: the two redirect patterns, the threeDS response object, and the result. - [Payment Orchestration: Autopilot](https://docs.payrails.com/docs/orchestration/autopilot.md): Route each payment to the provider most likely to approve it and retry declines on the next one, with a machine-learning-powered node in Workflow Studio. - [Workflow Studio](https://docs.payrails.com/docs/orchestration/workflow-studio.md): How Workflow Studio models a payment process as a visual workflow, and what triggers, actions, outcomes, and conditions do on the canvas. - [Workflow Studio: Quick Start Guide](https://docs.payrails.com/docs/orchestration/workflow-studio/quick-start.md): Build your first authorization workflow in Workflow Studio, from trigger to notification, handling every outcome it produces. - [Workflow Studio: Triggers](https://docs.payrails.com/docs/orchestration/workflow-studio/triggers.md): Compare the API triggers and event triggers that start a workflow, and see what data each one makes available to later steps. - [Workflow Studio: Actions](https://docs.payrails.com/docs/orchestration/workflow-studio/actions.md): See which Workflow Studio action maps to each payment operation, and how the outcomes of an action branch the canvas. - [Workflow Studio: Conditions and Branching](https://docs.payrails.com/docs/orchestration/workflow-studio/conditions.md): Route a workflow down different paths with condition steps, define the rules on each branch, and handle the case where none match. - [Workflow Studio: Monitoring Workflow Executions](https://docs.payrails.com/docs/orchestration/workflow-studio/monitoring.md): Track workflow runs in the Workflow Studio execution monitor: find an execution, inspect its steps, and debug a failure. - [Workflow Examples](https://docs.payrails.com/docs/orchestration/workflow-studio/examples.md): Ready-to-use workflow configurations for common payment scenarios, each with build instructions and a trigger-to-notify diagram. - [Condition Operators Reference](https://docs.payrails.com/docs/orchestration/workflow-studio/conditions/operators.md): Every operator available in a Workflow Studio condition rule, grouped by category, with the comparison it performs and a sample use case. - [Status Codes Reference](https://docs.payrails.com/docs/orchestration/workflow-studio/monitoring/status-codes.md): Reference for all 29 workflow execution status codes, grouped by severity, with the state each one represents. - [Reference: Glossary](https://docs.payrails.com/docs/orchestration/workflow-studio/glossary.md): Definitions of the Workflow Studio terms used across these guides: workflow, trigger, action, outcome, condition, and execution. - [Payment Orchestration: In-person payments](https://docs.payrails.com/docs/orchestration/in-person.md): Turn an Android point-of-sale device into a contactless terminal for cards, Apple Pay, Google Pay, and AliPay QR through one integration. - [Payment Links](https://docs.payrails.com/docs/orchestration/payment-links.md): Collect payments outside your checkout with a shareable link to a Payrails-hosted page, and see when to use it instead of the Payrails SDKs. - [Payment Links: Create a payment link](https://docs.payrails.com/docs/orchestration/payment-links/create-a-payment-link.md): Create, list, fetch, and delete Payment Links through the drop-in links API, or create a test link from the Payrails Portal without code. - [Payment Links: How it works](https://docs.payrails.com/docs/orchestration/payment-links/how-it-works.md): Follow a Payment Link from creation to close, and learn how links map to executions and payments, what each status means, and who owns what. - [Payment Links: Payment modes](https://docs.payrails.com/docs/orchestration/payment-links/payment-modes.md): Choose single or partial payments for a link, calculate the outstanding balance, and see how refunds, chargebacks, and expiry affect it. - [Payment Links: Share the link](https://docs.payrails.com/docs/orchestration/payment-links/share-the-link.md): Share a Payment Link by email, SMS, or chat, and see what the payer sees on the hosted page, which details it collects, and how it looks. - [Payment Links: Track and reconcile](https://docs.payrails.com/docs/orchestration/payment-links/track-and-reconcile.md): Use webhooks to confirm Payment Link outcomes, persist the right fields, monitor failures, reconcile in bulk, and track links in the Portal. - Worked workflow examples (8 examples): 8 end-to-end workflow configurations covering authorization, fraud screening, 3DS, capture, refunds and provider routing. ## Merchant of Record Payrails as the legal seller: the product catalog, the order data on the client session, the drop-in checkout, and tax calculation and invoicing. - [Merchant of Record](https://docs.payrails.com/docs/merchant-of-record.md): Accept payments with Payrails as the legal seller — tax calculation, invoicing, and a compliant checkout surface rendered by the drop-in. ## Token Vault PCI-compliant tokenization as a standalone module or inside orchestration: proxies, card tokenization and display SDKs, network tokens, and migration from other vaults. - [Token Vault](https://docs.payrails.com/docs/token-vault.md): In this section, you will learn how to use Vault as a standalone module, about our proxies, tokenization and detokenization methods. - [Token Vault: Records, Aliases and Instruments](https://docs.payrails.com/docs/token-vault/tokenize-records.md): Learn how the Payrails vault stores sensitive data as records, aliases, and instruments, and how retention policies apply to security codes. - [Token Vault: Direct Vault API](https://docs.payrails.com/docs/token-vault/direct-vault-api.md): Store card and network token data in the Payrails Vault and read it back in clear text from your backend with a Vault access token. - [Tokenize Cards via SDK](https://docs.payrails.com/docs/token-vault/tokenize-payment-instruments.md): Compare the Payrails tokenization methods, Secure Fields, client-side encryption, and API-only, by PCI DSS scope and effort. - [Tokenize cards via SDK: Tokenize cards with Secure Fields](https://docs.payrails.com/docs/token-vault/tokenize-payment-instruments/tokenize-cards-with-secure-fields.md): Collect card data in Payrails-hosted iframe fields and exchange it for a token, keeping cardholder data out of your own front end. - [Tokenize cards via SDK: Tokenize cards with Client-side Encryption](https://docs.payrails.com/docs/token-vault/tokenize-payment-instruments/tokenize-cards-with-client-side-encryption.md): Encrypt card details in your own checkout form and send them to Payrails to create a payment instrument token. - [Tokenize cards via SDK: Tokenize cards with API-only](https://docs.payrails.com/docs/token-vault/tokenize-payment-instruments/tokenize-cards-with-api-only.md): Send raw card details to the Payrails vault over the API for full control of card collection, at the widest PCI DSS scope. - [Display Cards via SDK](https://docs.payrails.com/docs/token-vault/display-sdk.md): Display tokenized card data securely in your frontend — with a customizable, easy to integrate, and fully compliant SDK. - [Display cards via SDK: Dynamic Styling Based on BIN](https://docs.payrails.com/docs/token-vault/display-sdk/dynamic-styling-based-on-bin.md): Detect a card's network from its number, the BIN lookup API, or instrument details, then style Display SDK elements and card data to match it. - [Vault Proxy](https://docs.payrails.com/docs/token-vault/vault-proxy.md): Compare Instant Proxy and Configurable Proxy to choose how you send or receive sensitive data through the PCI-compliant Payrails vault. - [Instant Proxy](https://docs.payrails.com/docs/token-vault/vault-proxy/proxy-payment-instruments.md): Forward tokenized payment instruments to payment providers through Instant Proxy with no setup, using variable placeholders in requests. - [Instant Proxy: Cards via Proxy](https://docs.payrails.com/docs/token-vault/vault-proxy/proxy-payment-instruments/cards-via-proxy.md): Send a stored card to a payment provider such as Adyen through Instant Proxy, with variable substitution, content types, and pre-processors. - [Instant Proxy: Apple Pay via Proxy](https://docs.payrails.com/docs/token-vault/vault-proxy/proxy-payment-instruments/apple-pay-via-proxy.md): Tokenize Apple Pay instruments with the button element SDK or server-to-server, then forward them to a payment provider with Instant Proxy. - [Instant Proxy: Google Pay via Proxy](https://docs.payrails.com/docs/token-vault/vault-proxy/proxy-payment-instruments/google-pay-via-proxy.md): Tokenize Google Pay instruments server-to-server or with the Elements SDK, then forward card or network token data through Instant Proxy. - [Configurable Proxy](https://docs.payrails.com/docs/token-vault/vault-proxy/proxy-connections.md): Learn how Configurable Proxy uses inbound and outbound connections to tokenize or detokenize sensitive data exchanged with any third party. - [Configurable Proxy: Managing Connections](https://docs.payrails.com/docs/token-vault/vault-proxy/proxy-connections/managing-connections.md): Create, configure, and activate proxy connections in the Portal or API, including proxy rules, regex field parsing, and trusted hosts. - [Configurable Proxy: Invoking Connections](https://docs.payrails.com/docs/token-vault/vault-proxy/proxy-connections/invoking-connections.md): Call inbound and outbound proxy connections to tokenize or detokenize sensitive data, with request examples for single and multiple records. - [Network Tokens](https://docs.payrails.com/docs/token-vault/network-tokens.md): Learn the benefits of network tokenization with Payrails, such as higher authorization rates and lower interchange fees, and how to implement it. - [Network tokens: Onboarding to Networks](https://docs.payrails.com/docs/token-vault/network-tokens/onboarding-to-networks.md): Find the legal entity and business details Payrails needs to onboard you as a token requestor with Visa and Mastercard for network tokens. - [Provision Network Tokens](https://docs.payrails.com/docs/token-vault/network-tokens/provision-network-tokens.md): Provision network tokens by automatic rules on network, BIN, issuing country, or card type, or by API for new or existing instruments. - [Transacting with Network Tokens](https://docs.payrails.com/docs/token-vault/network-tokens/transacting-with-network-tokens.md): Pay with network tokens, either through Payrails orchestration or by generating a cryptogram and sending it in a Vault Proxy request. - [Network tokens: Automatic Lifecycle Updates](https://docs.payrails.com/docs/token-vault/network-tokens/automatic-lifecycle-updates.md): See how Payrails updates network tokens in the vault when a cardholder or issuer changes a card, and what card and token data changes. - [Token Migration](https://docs.payrails.com/docs/token-vault/token-migration.md): Import card tokens from another vault provider into Payrails, or export your payment data from Payrails, with PCI DSS compliance at every step. - [Token migration: Self-served migration of card data from PSPs](https://docs.payrails.com/docs/token-vault/token-migration/self-serve-migration.md): Migrate stored cards from Stripe, Adyen, Checkout.com, or another PSP into the Payrails vault yourself, using the PSP's forwarding requests. - [Token Vault: Frequently Asked Questions](https://docs.payrails.com/docs/token-vault/frequently-asked-questions.md): Find answers to common questions about how Payrails Vault helps you securely store, manage, and use sensitive payment data. ## Analytics & Reporting Analytics on your payment data, and reports on payments, settlements, transactions and disputes, through the Portal or the API. - [Analytics & Reporting](https://docs.payrails.com/docs/analytics-and-reporting.md): Configure data ingestion for each supported payment provider and data source so you can start using analytics and reporting in Payrails. - [Upload files](https://docs.payrails.com/docs/analytics-and-reporting/upload-files.md): Send your own files to Payrails through the file upload API or the Portal, to extend the analytics data set and feed reconciliation. - [Upload files: Orders Report](https://docs.payrails.com/docs/analytics-and-reporting/upload-files/orders-report.md): The CSV format for an orders file upload, with the required and optional fields, their types, and an example value for each column. - [Reports](https://docs.payrails.com/docs/analytics-and-reporting/reports.md): Export payments, transactions, settlements, and disputes reports from Payrails as CSV files, either in the Portal or through the API. - [Reports: Payments report](https://docs.payrails.com/docs/analytics-and-reporting/reports/payments.md): A standardized view of authorization health across providers, covering success rates, failure reasons, 3D Secure status, and tokens. - [Reports: Settlements report](https://docs.payrails.com/docs/analytics-and-reporting/reports/settlements.md): A unified view of the transaction lifecycle and fees across providers, covering settlement amount, FX rate, and fee type. - [Reports: Transactions report](https://docs.payrails.com/docs/analytics-and-reporting/reports/transactions.md): A transaction-level report for reconciling individual payments, with a downloadable CSV sample and a definition of every column. - [Reports: Disputes report](https://docs.payrails.com/docs/analytics-and-reporting/reports/disputes.md): Details on all customer-disputed transactions, including chargeback status, reason codes, and the linked original transaction. - [Analytics & Reporting: Unified Analytics](https://docs.payrails.com/docs/analytics-and-reporting/unified-analytics.md): The Payrails analytics dashboards centralize payment data from every provider into one view of authorization rates and cost. - [Analytics & Reporting: Dashboards](https://docs.payrails.com/docs/analytics-and-reporting/dashboards.md): Filter a Payrails analytics dashboard, save the filter state as a custom view, and set a default view for each time you open it. ## Fraud Management Fraud screening inside the authorization flow. - [Fraud Management: Fraud Score](https://docs.payrails.com/docs/fraud-management/fraud-score.md): Learn how a fraud score check runs within your authorization workflow and how to read the Allow, Challenge, and Prevent notifications. ## Chargebacks Dispute and chargeback handling. - [Chargebacks](https://docs.payrails.com/docs/chargebacks.md): How Payrails abstracts provider-specific dispute logic into one chargeback lifecycle that works the same across every integration. ## Monitoring Alerting on payment performance. - [Monitoring: Alerts](https://docs.payrails.com/docs/monitoring/configure-alerts.md): Create email alerts that fire when authorization rate or failure results cross a threshold, and manage alert configurations and events. ## Resources Reference data: payment statuses, operation types and results, executions, holders, instruments, notification payloads, error codes and currency codes. - [Payments](https://docs.payrails.com/docs/resources/payments.md): Learn how Payrails models a payment as a series of operations, with reference sections on providers, operation types, results, and statuses. - [Payments: Payment Status](https://docs.payrails.com/docs/resources/payments/payment-status.md): Look up each payment status from Created to ChargebackReversed and how operation results move a payment through the status state machine. - [Payments: Operation Types](https://docs.payrails.com/docs/resources/payments/operation-types.md): Look up each payment operation type Payrails uses, from authorize, capture, and refund to provider notifications, tokenization, and 3DS. - [Payments: Operation Results](https://docs.payrails.com/docs/resources/payments/operation-results.md): Look up the result codes and categories Payrails maps from each PSP's responses to see why a payment operation succeeded or failed. - [Payments: Authorization flags](https://docs.payrails.com/docs/resources/payments/authorization-flags.md): Set the payment processing type and future usage flags on authorize requests to mark one-off, stored card, and subscription payments. - [Resources: Executions](https://docs.payrails.com/docs/resources/executions.md): Use the Executions list and detail pages in the Payrails Portal to monitor workflow executions and review their payments and events. - [Notifications](https://docs.payrails.com/docs/resources/notifications.md): Reference the envelope, event types, and details fields of notifications Payrails sends to your server, with success and failure examples. - [Action updated notifications](https://docs.payrails.com/docs/resources/notifications/action-updated-notifications.md): Handle executionActionUpdated notifications, sent when an authorize, capture, cancel or refund changes after its first result, like a late PSP result. - [Dispute notifications](https://docs.payrails.com/docs/resources/notifications/dispute-notifications.md): Read the fields of a dispute notification payload, the dispute statuses Payrails maps from PSP statuses, and which PSPs send them. - [Dispute alert notifications](https://docs.payrails.com/docs/resources/notifications/dispute-alert-notifications.md): Read dispute alert notification payloads, sent when an Ethoca, CDRN or RDR alert arrives, nears expiry and resolves, before it becomes a chargeback. - [Resources: Holders](https://docs.payrails.com/docs/resources/holder.md): Learn what a holder is in Payrails and how holders relate to payment instruments, tokens, accounts, executions, payments, and transfers. - [Resources: Payment Instruments and Tokens](https://docs.payrails.com/docs/resources/manage-instruments.md): Review, disable, or delete payment instruments and their vault, PSP, and network tokens through the Payrails API or Portal. - [Resources: Error codes](https://docs.payrails.com/docs/resources/error-codes.md): Look up the HTTP status codes and Payrails error codes the API returns, how an error response is structured, and how to resolve each one. - [Resources: Currency codes](https://docs.payrails.com/docs/resources/currency-codes.md): Look up the ISO 4217 currency codes Payrails supports and how many decimal places to use for each currency's amounts in API requests. ## Use Cases Reference architectures for common integration shapes. - [Use Cases: Billing](https://docs.payrails.com/docs/use-cases/billing-use-cases.md): Use Payrails to collect and charge payment methods while your billing engine owns subscriptions, invoices, and dunning. - [Use Cases: Server-to-server Integration](https://docs.payrails.com/docs/use-cases/server-to-server-integration-reference-architecture.md): Build a backend-driven Payrails integration that tokenizes on the frontend and your server controls the authorization steps, and webhook-first reconciliation. ## Integrations The catalog of every provider Payrails connects to, with a setup guide for each one. - [Integrations](https://docs.payrails.com/docs/integrations.md): Find the setup guide for each provider Payrails connects to: payment providers, payment methods, fraud tools, dispute providers and data sources. ## Payment providers and methods Setup guides for each payment service provider, and every payment method with the PSPs and countries that support it. - [Payment providers and methods: Payment providers](https://docs.payrails.com/docs/integrations/payment-providers.md): Connect at least one payment service provider to Payrails before you accept payments, and find the setup guide for each supported provider. - [Payment providers: Adyen](https://docs.payrails.com/docs/integrations/payment-providers/adyen.md): Connect an Adyen account to Payrails: create the integration, configure API credentials and webhooks, and enable raw card data processing. - [Payment providers: Braintree (PayPal)](https://docs.payrails.com/docs/integrations/payment-providers/braintree.md): Connect a Braintree account to Payrails: create the integration, configure credentials and webhooks, and enable raw card data processing. - [Payment providers: Checkout.com](https://docs.payrails.com/docs/integrations/payment-providers/checkout-com.md): Connect a Checkout.com account to Payrails: create the integration, configure API keys and webhooks, and enable raw card data processing. - [Payment providers: PayPal](https://docs.payrails.com/docs/integrations/payment-providers/paypal.md): Connect a PayPal account to Payrails by authorizing Payrails as a third-party app in PayPal, then scope the integration to workspaces. - [Payment providers: Stripe](https://docs.payrails.com/docs/integrations/payment-providers/stripe.md): Connect a Stripe account to Payrails with one-click onboarding, then configure statement descriptors and embedded SEPA Direct Debit. - [Payment methods: All supported methods](https://docs.payrails.com/docs/integrations/payment-methods.md): Find and filter payment methods supported by Payrails, and learn how to integrate them into your checkout flow. - [Set up payment methods](https://docs.payrails.com/docs/integrations/payment-methods/set-up-payment-methods.md): Learn which payment method types Payrails supports, how PSP and direct integrations differ, and how to enable methods in the Portal. - [Payment methods: Cards](https://docs.payrails.com/docs/integrations/payment-methods/cards.md): What you need in place to accept card payments through Payrails, from provider configuration to the integration that collects card data. - [Co-branded cards](https://docs.payrails.com/docs/integrations/payment-methods/cards/co-branded-cards.md): How Payrails detects a co-branded card from its BIN, shows both networks with equal weight, and routes over the one the cardholder picks. - [Payment methods: Apple Pay](https://docs.payrails.com/docs/integrations/payment-methods/apple-pay.md): Set up Apple Pay on web and mobile with Payrails, and accept it through Drop-in, Elements, server-to-server, or self-decrypted integration. - [Payment methods: Boleto](https://docs.payrails.com/docs/integrations/payment-methods/boleto.md): Accept Boleto cash and online banking payments from customers in Brazil, and check the PSPs that process Boleto through Payrails. - [Payment methods: Google Pay](https://docs.payrails.com/docs/integrations/payment-methods/google-pay.md): Set up Google Pay on Android and the web with Payrails through Stripe, Checkout.com, or Adyen, using the Payrails SDK or server-to-server. - [Payment methods: iDEAL](https://docs.payrails.com/docs/integrations/payment-methods/ideal.md): Accept iDEAL bank payments from customers in the Netherlands, and check the PSPs that process iDEAL through Payrails. - [Payment methods: Klarna](https://docs.payrails.com/docs/integrations/payment-methods/klarna.md): Accept Klarna buy now, pay later payments, where customers pay now, pay later or spread the cost on a Klarna page after a redirect from your checkout. - [Payment methods: PayPal](https://docs.payrails.com/docs/integrations/payment-methods/paypal.md): Accept PayPal via the direct Payrails integration, handle the required redirect action, and create billing agreements for recurring charges. - [Payment methods: Pix](https://docs.payrails.com/docs/integrations/payment-methods/pix.md): Accept Pix instant payments in Brazil, where customers scan a QR code or copy a Pix code and confirm the payment in their banking app. - Local and alternative payment methods (230 more): Guides for 230 further local payment methods — wallets, bank transfers, cash and voucher schemes, BNPL and QR payments across LATAM, APAC, EMEA and Africa. Each is published under /docs/integrations/payment-methods/ and listed in sitemap.xml. - Further provider integrations (55 more): Configuration guides for 55 further payment providers, published under /docs/integrations/payment-providers/. ## Fraud prevention providers Setup guides for fraud prevention providers that screen payments in your workflow. - [Fraud prevention providers](https://docs.payrails.com/docs/integrations/fraud-prevention-providers.md): Connect a fraud prevention provider to Payrails, screen payments in your workflow and keep the provider updated on each order. - [Fraud prevention providers: Cybersource Decision Manager](https://docs.payrails.com/docs/integrations/fraud-prevention-providers/cybersource.md): Screen payments with Cybersource Decision Manager in your Payrails workflow, receive review decisions and see the fields Payrails sends. - [Fraud prevention providers: Forter](https://docs.payrails.com/docs/integrations/fraud-prevention-providers/forter.md): Screen card payments with Forter in your Payrails workflow, and see the Portal setup, decisions and request fields Forter requires. - [Fraud prevention providers: Ravelin](https://docs.payrails.com/docs/integrations/fraud-prevention-providers/ravelin.md): Screen payments with Ravelin in your Payrails workflow, report disputes, and see the request fields Ravelin requires. - [Fraud prevention providers: Riskified](https://docs.payrails.com/docs/integrations/fraud-prevention-providers/riskified.md): Screen orders with Riskified before and after authorization in Payrails, and see the request fields Riskified requires. - [Fraud prevention providers: Signifyd](https://docs.payrails.com/docs/integrations/fraud-prevention-providers/signifyd.md): Screen orders with Signifyd in Payrails, report fulfilment, returns and chargebacks, and see the request fields Signifyd requires. ## Dispute providers Setup guides for dispute service providers that send chargebacks to Payrails. - [Dispute providers](https://docs.payrails.com/docs/integrations/dispute-providers.md): Connect dispute service providers to Payrails to process chargebacks, and find the setup guide for each supported dispute integration. - Further provider integrations (5 providers): Dispute integration setup for 5 individual providers. ## Data sources Setup guides for connecting payment providers as data sources for analytics and reporting. - [Connect your data sources](https://docs.payrails.com/docs/integrations/data-sources.md): Add your payment providers as data sources in the Payrails Portal to power analytics, reporting, and fee monitoring. - Provider-specific data source setup (16 providers): Instructions for connecting 16 individual payment providers as reporting data sources. ## SDK overview Every Payrails SDK at a glance, and the Drop-in, Elements and Secure Fields integration levels. - [SDK overview: SDKs](https://docs.payrails.com/docs/sdks.md): Find the Payrails SDK for each job: checkout SDKs for web, iOS, Android and React Native, the web fraud SDK, and the card tokenization and display SDKs. - [SDK overview: Checkout SDKs](https://docs.payrails.com/docs/sdks/checkout-sdks.md): Compare the three Payrails SDK integration levels, Drop-in, Elements, and Secure Fields, across web, iOS, Android, and React Native. ## Web SDK Install, customize and migrate the Payrails web SDK. - [Web SDK quick start](https://docs.payrails.com/docs/sdks/web.md): Install the Payrails web SDK, initialize a client from your server's init payload, and mount a working checkout on your page. - [Guides: Customize the web SDK checkout's appearance](https://docs.payrails.com/docs/sdks/web/guides/customize-the-checkouts-appearance.md): Style the card form, payment buttons, drop-in, and collect elements with the appearance option, and load custom fonts. - [Guides: Accept card payments with the web SDK](https://docs.payrails.com/docs/sdks/web/guides/accept-card-payments.md): Mount a PCI-compliant card form with the Payrails web SDK, wire it to a payment button, and handle the authorization result. - [Guides: Collect tax IDs for card payments in the web SDK](https://docs.payrails.com/docs/sdks/web/guides/collect-tax-ids-for-card-payments.md): Collect the cardholder's tax ID in the web SDK card form when the card's issuer requires one, for Argentina, Brazil, Chile, and Mexico. - [Guides: Add Apple Pay and Google Pay to the web SDK](https://docs.payrails.com/docs/sdks/web/guides/add-apple-pay-and-google-pay.md): Check wallet availability, mount the Apple Pay and Google Pay buttons, and handle payment results and express-checkout address changes. - [Guides: Accept APMs without a redirect in the web SDK](https://docs.payrails.com/docs/sdks/web/guides/accept-alternative-payment-methods-without-a-redirect.md): Collect alternative payment method details in a form on your checkout page with the Payrails web SDK, and handle each result. - [Guides: Collect card data with Secure Fields in the web SDK](https://docs.payrails.com/docs/sdks/web/guides/collect-card-data-with-secure-fields-collect-container.md): Build your own card form field by field with a collect container, validate the secure inputs, and collect an encrypted payload. - [Guides: Handle the actionRequired event in the web SDK](https://docs.payrails.com/docs/sdks/web/guides/action-required-event.md): Intercept the actionRequired event to control how your app presents a 3D Secure challenge or a payment-method redirect. - [Web SDK v6 migration guide](https://docs.payrails.com/docs/sdks/web/v6-migration/v6-migration-guide.md): Upgrade the Payrails web SDK from 5.x to 6.x, with every breaking change, before-and-after code for each one, and how to verify the result. - [v6 Migration Guide: Web SDK v6 migration runbook for AI agents](https://docs.payrails.com/docs/sdks/web/v6-migration/agent-runbook-v6-migration.md): A runbook for an AI coding agent migrating a codebase from Payrails web SDK 5.x to 6.x: detect, route, execute, and verify. - [Web SDK v5 (5 pages, legacy)](https://docs.payrails.com/docs/sdks/web-v5-legacy/secure-fields.md): (Legacy) Documentation for the previous generation of the web SDK. Do not use for new integrations — use Web SDK v6 and the v6 migration guide. ## iOS SDK Install, style and troubleshoot the Payrails iOS SDK. - [iOS SDK quick start](https://docs.payrails.com/docs/sdks/ios.md): Install the Payrails iOS SDK with Swift Package Manager, create a session, and render a working card payment screen. - [iOS SDK concepts](https://docs.payrails.com/docs/sdks/ios/sdk-concepts.md): This page explains the mental model behind the Payrails iOS SDK so you can reason about integration decisions confidently. - [iOS SDK styling guide](https://docs.payrails.com/docs/sdks/ios/styling-guide.md): Style the iOS SDK card form, inputs, labels, error text, and payment buttons, including field variants and layout presets. - [iOS SDK troubleshooting](https://docs.payrails.com/docs/sdks/ios/troubleshooting.md): Fix common iOS SDK installation, card form, Apple Pay, PayPal, payment, and pre-authorization gate issues, and turn on SDK debug logs. ## Android SDK Install, style and extend the Payrails Android SDK in a Jetpack Compose app. - [Android SDK quick start](https://docs.payrails.com/docs/sdks/android.md): Add the Payrails Android SDK to a Jetpack Compose app, create a session from an init payload your backend fetches, and build a card payment form. - [Android SDK concepts](https://docs.payrails.com/docs/sdks/android/sdk-concepts.md): Understand how the Android SDK works, from sessions and the payment flow to 3DS, the pre-authorization gate, security, and element lifecycle. - [Guides: Support co-branded cards](https://docs.payrails.com/docs/sdks/android/co-branded-cards.md): Let shoppers choose which network processes a co-branded card in the Android SDK, and submit that choice with the payment. - [Guides: Build your own pay button](https://docs.payrails.com/docs/sdks/android/custom-pay-button.md): Drive checkout from your own Android button while the SDK handles the Google Pay sheet, the 3D Secure and redirect tabs, and polling. - [Guides: Gate payment authorization](https://docs.payrails.com/docs/sdks/android/gate-payment-authorization.md): Register an onRequestStart handler in the Android SDK so your backend can approve or refuse a payment before Payrails authorizes it. - [Guides: Run headless payments](https://docs.payrails.com/docs/sdks/android/execute-payment-headless.md): Run a payment from your own Android UI with PayrailsPaymentLauncher, without rendering a prebuilt SDK button component. - [Guides: Accept PayPal payments](https://docs.payrails.com/docs/sdks/android/accept-paypal-payments.md): Accept PayPal in your Android app with PayPalButton, refresh expired sessions, and store PayPal accounts to charge them in later payments. - [Guides: Query session data](https://docs.payrails.com/docs/sdks/android/query-session-data-at-runtime.md): Read the execution ID, amount, payment method configuration, and other values from an Android SDK Session with session.query(). - [Guides: Accept redirect payments](https://docs.payrails.com/docs/sdks/android/accept-redirect-payments.md): Accept payments through redirect-based payment methods (iDEAL, Bancontact, Sofort, etc.) using the Payrails SDK. - [Guides: Tokenize a card without charging it](https://docs.payrails.com/docs/sdks/android/tokenize-card.md): Save a card or Google Pay token to the Payrails vault with the Android SDK without charging it, then reuse the returned instrument ID. - [Guides: Update the checkout amount](https://docs.payrails.com/docs/sdks/android/update-checkout-amount.md): Change the checkout amount and currency at runtime in the Android SDK, for a tip, a discount code, or shipping added after address entry. - [Android SDK styling guide](https://docs.payrails.com/docs/sdks/android/styling-guide.md): Customize the Android SDK card form, pay button, card brand selector, layout, and translations with Compose-native style classes. - [Android SDK troubleshooting](https://docs.payrails.com/docs/sdks/android/troubleshooting.md): Fix common Android SDK build, card form, Google Pay, 3DS, pre-authorization gate, and lifecycle issues, and turn on SDK debug logs. ## React Native SDK Install and use the Payrails React Native SDK. - [React Native SDK quick start](https://docs.payrails.com/docs/sdks/react-native.md): Install and initialize the Payrails React Native SDK with PayrailsProvider to add pre-built payment components to your mobile app. - [Integrate the React Native SDK](https://docs.payrails.com/docs/sdks/react-native/integrate.md): Mount the React Native Drop-in or use Elements for stored and new cards, Apple Pay, Google Pay, PayPal, redirect methods, and Lean. - [React Native SDK concepts](https://docs.payrails.com/docs/sdks/react-native/sdk-concepts.md): How the Payrails React Native Drop-in works, and which parts of an integration run on your server, in your app, and over webhooks. ## Fraud SDK The Payrails web fraud SDK, which collects device signals for your fraud providers. - [Payrails Web Fraud SDK](https://docs.payrails.com/docs/sdks/fraud-sdk.md): Initialize the Payrails fraud SDK to collect device signals from several fraud providers behind one interface, for the web SDK. ## API reference The Payrails REST API, and the API references of the web, iOS, Android and React Native SDKs. - [API reference](https://docs.payrails.com/reference/index.md): Overview of the Payrails API reference: every API area, grouped by domain as in the sidebar, with a link to its main endpoint, plus the SDK references. - [Schemas: Meta](https://docs.payrails.com/reference/meta.md): Every field of the meta object: the order, customer, vendor, client context and risk data you attach to executions and drop-in links. - [Schemas: Funds Transfer](https://docs.payrails.com/reference/fundstransfer.md): Every field of the meta order's fundsTransfer for an Account Funding Transaction: the transfer type and purpose, and the sender and recipient details. - [Workflow Schemas: Create Execution Response](https://docs.payrails.com/reference/createexecutionresponse.md): Every field of the create execution response in an executionCreated event: the execution's status, workflow, amount, initial results and any required action. - [Workflow Schemas: Enrollment Payment Composition](https://docs.payrails.com/reference/enrollmentpaymentcomposition.md): Every field of a payment method in a networkOffersEnrollmentCompleted event's paymentComposition: the method, instrument, provider config and result. - [Workflow Schemas: Payment Composition](https://docs.payrails.com/reference/paymentcomposition.md): Every field of a payment method in an action event's paymentComposition: the operation, amount, result, provider, acquirer data and any dispute. - [Workflow Schemas: Payout Composition](https://docs.payrails.com/reference/payoutcomposition.md): Every field of a payout method in an action event's payoutComposition: the operation, amount, result, provider, acquirer data and any dispute. - [Workflow Schemas: Pending Payment Composition](https://docs.payrails.com/reference/pendingpaymentcomposition.md): Every field of a payment method in an executionActionPending event's paymentComposition: the operation, amount, result, provider and acquirer data. - [Workflow Schemas: Resolved Rulesets](https://docs.payrails.com/reference/resolvedrulesets.md): Every field of a workflow step's resolved rulesets: the full ruleset definitions, with their rules and actions, that a workflow configuration returns. - [Workflow Schemas: Rule Evaluation](https://docs.payrails.com/reference/ruleevaluation.md): Every field of one rule engine evaluation in a ruleEngineExecuted event: the chosen rule, its action, the selected entity and each rule's result. - [Workflow Schemas: Step Next Actions](https://docs.payrails.com/reference/workflowstepnextactions.md): Every field of a workflow action step's next actions: the actions that run in order when the step is scheduled, started, paused, completed or updated. - [Web SDK Event API Reference](https://docs.payrails.com/docs/sdks/web/references/event-api-reference.md): Reference for the web SDK event API: every instance event and element event, the payload each one carries, and when it fires. - [Web SDK Appearance API Reference](https://docs.payrails.com/docs/sdks/web/references/appearance-api-reference.md): Reference for the web SDK appearance option: option types, rule semantics, and the CSS classes and state modifiers on the DOM. - [Web SDK Payrails Class Reference](https://docs.payrails.com/docs/sdks/web/references/payrails-api-reference.md): Reference for the Payrails class and package exports of the web SDK: initialization, element factories, and payment session data. - [SDK Reference: iOS SDK API Reference](https://docs.payrails.com/docs/sdks/ios/sdk-api-reference.md): Reference for the Payrails iOS SDK: installation, the init payload, session creation, card form and button components, and delegates. - [SDK Reference: Android SDK API Reference](https://docs.payrails.com/docs/sdks/android/api-reference.md): Public API of the Payrails Android SDK — payment methods, configuration, styling, translations and event delegates. - [SDK Reference: React Native SDK API Reference](https://docs.payrails.com/docs/sdks/react-native/api-references.md): Reference for the PayrailsDropin React Native component: every property, callback, and configuration object, with types and defaults. ## OpenAPI specification - [Payrails OpenAPI spec](https://cdn.payrails.io/docs/api/openapi.min.json): Machine-readable definition of every Payrails REST endpoint, including schemas, parameters and examples. ## Optional - [Payrails website](https://www.payrails.com): Product, platform and company overview. - [Website llms.txt](https://www.payrails.com/llms.txt): Index of Payrails marketing and company pages. - [Blog](https://www.payrails.com/blog): Payment strategy, product updates and engineering deep dives. - [GitHub](https://github.com/payrails): Payrails SDKs and open-source repositories. - [Contact](https://www.payrails.com/contact): Request a demo or reach the Payrails team.