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

# Web SDK - Quick Start

> Install the Payrails web SDK, initialize a client from your server's init payload, and mount a working checkout on your page.

Payrails Web provides the building blocks to create a checkout experience for<br />your customers. This page gets you to a first mounted checkout and is the hub<br />for the rest of the documentation.

You can integrate at three levels, from quickest to most control:

* **Drop-in** — all-in-one checkout UI; the quickest way to accept payments.
* **Elements** — one component per payment method (card form, wallet buttons,
  and more) for a fully customizable checkout.
* **Secure fields** — the lowest-level option: mount individual PCI-compliant
  card input iframes and build your own card-form markup around them. Most
  control, most work.

## Quick start

Install the SDK, initialize it once, then pick the integration that fits your checkout.

### 1. Install the SDK

```bash theme={null}
npm install @payrails/web-sdk
```

### 2. Initialize with your client init response

Call your backend, which calls the Payrails `/merchant/client/init` API, and pass the response to `Payrails.init`.&#x20;

`init` is asynchronous - it loads the SDK bundle (and its styles) for the version your session was created with, so `await` it:

```typescript theme={null}
import { Payrails } from "@payrails/web-sdk";

const payrails = await Payrails.init(clientInitResponse, {
  events: {
    onClientInitialized: () => console.log("SDK ready"),
  },
});
```

You now have a `payrails` client. Handle payment results with the instance-level `.on(...)` API - the same events fire for **any** integration below, so you wire them once:

```typescript theme={null}
payrails.on("success", (event) =>
  console.log("Payment success", event.paymentMethodCode),
);
payrails.on("failed", (event) =>
  console.log("Payment failed", event.data?.code),
);
```

### 3. Choose your integration

Pick one of the following and mount it into a container on your page. Each example is self-contained and assumes the `payrails` client and the `.on(...)`result handlers from step 2.

#### Drop-in

The drop-in renders every payment method enabled for the current session - you do not list methods yourself.

```html theme={null}
<div id="dropin"></div>
```

```typescript theme={null}
const dropin = payrails.dropin({});
dropin.mount("#dropin");
```

#### Elements

Compose your own layout from individual components. Here a card form and a payment button, created from the same client — the client keeps the button disabled until the form is valid and starts the payment on click.

```html theme={null}
<div id="card-form"></div>
<div id="pay-button"></div>
```

```typescript theme={null}
const cardForm = payrails.cardForm({ showCardHolderName: true });
cardForm.mount("#card-form");

const payButton = payrails.paymentButton({
  translations: { label: "Pay now" },
});
payButton.mount("#pay-button");
```

#### Secure fields

Build a card form field by field with a collect container. Sensitive data stays inside Payrails-hosted iframes and never touches your page.

```html theme={null}
<div id="card-number"></div>
```

```typescript theme={null}
import { ElementType } from "@payrails/web-sdk";

const container = payrails.collectContainer({});
const cardNumber = container.createCollectElement({
  type: ElementType.CARD_NUMBER,
});
cardNumber.mount("#card-number");
// create and mount CVV and expiry the same way, then container.collect()
```

You should now see your chosen integration render the payment methods configured for your merchant account. From here, pick a guide that matches your task.

## Reporting a Vulnerability

If you discover a potential security issue in this project, please reach out to us at [security@payrails.com](mailto:security@payrails.com).

<br />


## Related topics

- [iOS SDK - Quick start](/docs/orchestration/checkout-sdks/ios/index.md)
- [Android SDK - Quick Start](/docs/orchestration/checkout-sdks/android/index.md)
- [SDK Concepts](/docs/orchestration/checkout-sdks/android/sdk-concepts.md)