# Web SDK integration

A complete guide to integrating Peach Orchestration payments into web applications, with per-framework code samples for Vanilla JavaScript, React, Vue, and Angular.

## What this page covers
- A framework switcher (Vanilla JavaScript, React, Vue, Angular) that swaps all code samples
- Ten sections per framework: Prerequisites, Installation, Configuration, Basic integration, Payment methods, Saved cards, Error handling, Customisation, Testing, Troubleshooting
- Getting credentials from the Peach Payments Dashboard (profile ID `pro_xxx`, publishable key `pk_snd_xxx`/`pk_prd_xxx`, merchant API key `snd_xxx`/`prd_xxx`)
- Wallet prerequisites for web: Peach domain association file for Apple Pay, Peach Google Pay ID, and Peach Samsung Pay certificates
- Creating a payment intent on your backend and driving the Payment Element with the returned `client_secret`
- Payment method ordering (cards, wallets, and other payment methods), wallet configuration (Apple Pay / Google Pay / Samsung Pay), tabs vs accordion layout, inline iframe redirection
- Saved cards via customer sessions and Setup Intents
- Appearance theming (theme presets, `variables`, and CSS-like `rules`) and dark mode
- Test cards and end-to-end testing guidance

## Key steps / API

Load the Web SDK via CDN (`HyperLoader.js`). npm packages are not published yet — Peach will publish its own.

```html
<script src="https://sdk.sandbox-next.peachpayments.com/sandbox/web/0.133.4/v1/HyperLoader.js"></script>
```

```javascript
const hyper = Hyper('pk_test_your_publishable_key', {
  customBackendUrl: 'https://app.sandbox-next.peachpayments.com/api',
});

// clientSecret comes from your server (POST /payments)
const elements = hyper.elements({ clientSecret, appearance: { theme: 'default' } });
const paymentElement = elements.create('payment', { layout: 'tabs' });
paymentElement.mount('#payment-element');

const { error, paymentIntent } = await hyper.confirmPayment({
  elements,
  confirmParams: { return_url: window.location.origin + '/payment-complete' },
  redirect: 'if_required',
});
```

In React / Next.js, load `HyperLoader.js` dynamically (script tag or `document.createElement('script')`), then use the global `Hyper` the same way.

Other real API surface referenced in the source:
- `hyper.confirmSetup({ elements, confirmParams })` — save a card via a Setup Intent
- `hyper.paymentRequest({ country, currency, total })` + `canMakePayment()` — wallet availability
- `elements.create('payment', { paymentMethodOrder, wallets, layout })` — method ordering (for example `'card'`, `'apple_pay'`, `'pay_shap'`, `'payflex'`), wallet toggles (`'auto' | 'never' | 'always'`), and layout (`'tabs'` or `'accordion'`)
- Appearance: `theme` (`'default'`, `'midnight'`, `'charcoal'`, `'soft'`, `'none'`), `labels`, `variables` (colours, typography, spacing, borders, button styling), and `rules` (CSS-like selectors such as `.Input`, `.Tab`, `.AccordionItem`)
- Saved cards: pass `customerSessionClientSecret` alongside `clientSecret` in `hyper.elements(...)`

### `inline_iframe_redirection_enabled` (boolean)

One option on the Elements `options` object, alongside `layout` and `defaultValues`. Use it by default. When it is on, also pass `sdkHandleConfirmPayment` with the `return_url` — the SDK confirms from inside the element, so it needs the return URL on the element options rather than on the `confirmPayment()` call.

```js
const paymentElement = elements.create('payment', {
  // ...existing options
  inline_iframe_redirection_enabled: true,
  sdkHandleConfirmPayment: {
    confirmParams: { return_url: 'https://your-site.com/checkout/complete' },
  },
});
```

Renders a **non-card** redirect inside the checkout form (an embedded iframe) instead of the default full-screen overlay popout.

| | option off | option on (recommended) |
|---|---|---|
| Non-card redirect | full-screen popout | **inline in the form** |
| Card (3DS) | full-screen popout | full-screen popout |
| Express / one-click | full-screen popout | full-screen popout |

Prerequisites and caveats:
- It only takes effect when the connector returns a `redirect_inside_popup` next action, which requires **`is_iframe_redirection_enabled` on the Peach connector/merchant** (a backend flag). Without that, redirects are a normal full-page redirect and this option does nothing.
- **Cards always pop out** regardless of the flag — 3DS/ACS pages generally refuse to be framed.
- **Redirect targets must allow framing.** A page sending `X-Frame-Options: DENY` or a restrictive `frame-ancestors` renders blank inside the iframe. Only enable it for alternative payment method pages you control or have verified.
- Completion is detected by polling the payment intent (the embedded page advances the intent server-side), so it works cross-origin. There is a 15-minute backstop and the flow settles cleanly if the shopper abandons it.

Sandbox API base is `https://app.sandbox-next.peachpayments.com/api`; production is `https://app.next.peachpayments.com/api`.

For Apple Pay on web, download Peach's merchant domain verification file (production: `https://secure.peachpayments.com/.well-known/apple-developer-merchantid-domain-association`, sandbox: `https://testsecure.peachpayments.com/.well-known/apple-developer-merchantid-domain-association`), then host it at `{{yourDomain}}/.well-known/apple-developer-merchantid-domain-association`. While you do not need your own merchant ID and payment processing certificate, the same restrictions for verifying a domain as specified on [Apple's documentation](https://developer.apple.com/documentation/ApplePayontheWeb/configuring-your-environment#Register-and-Verify-Your-Domain) apply. Allow requests without a user-agent, or allowlist Apple IP addresses as described in [Setting up your server](https://developer.apple.com/documentation/apple_pay_on_the_web/setting_up_your_server). Web-only Google Pay may use the Peach Google Pay ID. Web-only Samsung Pay may use Peach certificates. Mobile SDK V2 requires merchant-owned wallet credentials — see the Mobile SDK guides.

## Related
- [Web SDK customisation](/operate/customization.md): live theme editor for the appearance API described here
- [Payment methods](/operate/payment-methods.md): full list of supported methods
- [iOS SDK](/sdk-mobile-ios.md): native iOS equivalent of this integration
- [API Playground](/playground.md): create a payment intent and get a `client_secret`
- [Simple purchase](/flows/simple-purchase.md): the end-to-end payment flow this SDK drives
- [Testing](/docs/testing.md): test cards and sandbox guidance

---

Interactive version: https://playground.peachpayments.com/sdk-web