> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## 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.

# Accept in-app payments

> Use the Payrails native SDKs to accept payments from within your mobile apps

## Why Payrails agnostic in-app payments

* **No platform lock-in** – The April 30 U.S. court ruling lets you link to external payment methods, keeping revenue you once lost to up-to-30 % app-store fees.
* **Any PSP, any market** – Connect to any global or local processor (or Merchant-of-Record) and switch at will, without code rewrites.
* **Optimise cost and conversion** – Dynamically route transactions for lower fees, higher authorisation rates, or reduced risk, and A/B test strategies in real time.
* **Unified data and control** – Consolidate web and app payments in one dashboard and experiment from a single rule engine.
* **Security built-in** – Payrails tokenises data and keeps you in PCI SAQ-A scope.

***

## Intro: your implementation options

Payrails offers two ways to bring checkout into a mobile experience.

| Option | Best for | How it works |
| - | - | - |
| **iOS/React native SDK integration** | Native iOS apps that want the smoothest UX | Present the Payrails Payment Sheet inside your app; if the chosen method requires a bank or wallet redirect, the Generic Redirect Element opens an in-app Safari view and returns when the flow completes. |
| **Server-to-Server Redirect Flow** | Cross-platform or webview apps, or when you need full UI control | Your backend creates the workflow execution, then sends back redirect URL to Payrails HPP to client. |
| **Classical Payrails payment flow** | Full control on UI, advanced payment flow setups | Standard payment process through Payrails, without any UI limitations |

Either option lets you decide where the final checkout UI lives:

* **Use the Payrails Hosted Payment Page** - quickest path, fully branded to your colours and logo.
* **Render your own page** - host the redirect yourself and retain total design control while relying on Payrails for compliance and payment logic.

***

## Client-side integration options

### Option 1 — iOS/RN SDK with Generic Redirect Element *(recommended for native apps)*

| Step | What you do | What the SDK does |
| - | - | - |
| 1 | Install the Payrails SDK | Bundles the GenericRedirectElement and HPP |
| 2 | Call `Payrails.GenericRedirectButton()` | Displays UI button, which redirect the user to Payrails HPP where payments happens |
| 4 | Listen for `sdk authorization events` and update your UI | Sends the authorization result to the app and the final webhook to your server. |

**Why pick this?** Fastest time-to-market and best user experience—no context switch to the browser, and Payrails maintains the redirect handler for new payment methods.

For complete element documentation, read here - [iOS SDK](/docs/orchestration/checkout-sdks/ios/sdk-api-reference#generic-redirect-button)

***

### Option 2 — Server-to-Server Redirect Flow *(works for any platform)*

1. **Configure Payrails acceptance workflow to include Payrails HPP option**
2. **Create a Workflow execution with lookup as initial action**.
3. **Take the redirection url from lookup result**
4. **Redirect** the user to **Payrails Hosted Payment Page**
5. **Handle the return** on `return_url`, then verify status via API or webhook.

**Why pick this?** Works in any environment, gives full design control, and enables out-of-band use cases such as pay-links or email invoices.

<br />

### Option 3 - Payrails payment inside the iframe

1. Implement your custom payment/checkout page by using Payrails SDKs
2. Open it in webview, handle the payment flow inside the checkout page
3. Update the status of the app


## Related topics

- [SDK Concepts](/docs/orchestration/checkout-sdks/android/sdk-concepts.md)
- [How to accept alternative payment methods without a redirect](/docs/orchestration/checkout-sdks/web/guides/how-to-accept-alternative-payment-methods-without-a-redirect.md)
- [Accept payments via API](/docs/orchestration/checkout-sdks/accept-payments-via-api.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.