# Embedded Checkout

Embedded Checkout lets customers pay without leaving your website or mobile app. Choose the **xMoney.js v2 SDK** for websites and mobile WebViews, or a native SDK for iOS, Android, and React Native.

Use Embedded Checkout when you want customers to stay in your checkout experience instead of being redirected to the Finance Computer hosted checkout page. For redirect-based checkout, see [Hosted Checkout](/guides/checkout/hosted-checkout).

## What you can build

All SDKs provide a fast, complete checkout and composable surfaces for custom layouts:

- **Web:** mount a full payment form or individual card, saved-card, Apple Pay, and Google Pay components.
- **Native mobile:** present a drop-in Payment Sheet, mount Payment Element in your layout, or show a standalone native wallet.


The native iOS, Android, and React Native SDKs share one `PaymentConfig`, `PaymentIntent`, and `PaymentResult` model. See [Native mobile SDKs](/guides/checkout/native-sdks) to choose a platform.

## Web SDK methods

| SDK method | Purpose |
|  --- | --- |
| `window.XMoney.paymentForm(config)` | Full inline checkout form with card, saved cards, Apple Pay, and Google Pay. |
| `window.XMoney.paymentCard(config)` | Card-only form for custom layouts. |
| `window.XMoney.applePay(config)` | Standalone Apple Pay button. |
| `window.XMoney.googlePay(config)` | Standalone Google Pay button. |
| `window.XMoney.savedCardPayment(config)` | Headless payment with an existing saved card. |
| `window.XMoney.getPaymentMethodCapabilities()` | Detect Apple Pay and Google Pay availability before rendering wallet buttons. |


## Integration guides

Website integration
Create an order on your backend, mount `paymentForm()`, handle callbacks, update cart totals, and clean up SDK instances.

Customer details
Collect Dashboard-configured name, email, phone, and billing-address data for card, Apple Pay, and Google Pay.

Custom layouts
Compose `paymentCard()`, standalone wallet buttons, manual submit, validation, runtime theming, and capability checks.

Saved cards
Save cards during checkout and charge existing card tokens with `savedCardPayment().pay({ cardId })`.

Installments
Offer BIN-based installment plans in `paymentForm()` and `paymentCard()`, and sync custom CTAs with `onPaymentChange`.

3DS and results
Understand 3DS modal behavior, background transaction refresh, result callbacks, redirect fallback, and server-side confirmation.

Native mobile SDKs
Integrate Payment Sheet, Payment Element, Apple Pay, or Google Pay in iOS, Android, and React Native apps.

Mobile WebViews
Use the same inline checkout page inside iOS or Android WebViews while preserving wallet and 3DS lifecycle behavior.

## Web quickstart

### 1. Load the SDK

```html
<!-- Production -->
<script src="https://secure.xmoney.com/sdk/v2/xmoney.js"></script>

<!-- Staging -->
<script src="https://secure-stage.xmoney.com/sdk/v2/xmoney.js"></script>
```

### 2. Add a container

```html
<div id="xmoney-payment-form"></div>
```

### 3. Create a signed order on your backend

Your backend creates the order payload, signs it with your private key, and returns only the public values needed by the browser:

```json
{
  "publicKey": "pk_test_your_key",
  "orderPayload": "base64-encoded-order",
  "orderChecksum": "base64-encoded-checksum"
}
```

Never expose your private key in client-side code.

### 4. Mount the payment form

```javascript
const paymentForm = await window.XMoney.paymentForm({
  container: 'xmoney-payment-form',
  publicKey,
  orderPayload,
  orderChecksum,
  card: {
    savedCards: {
      enabled: true,
      optInVisible: true,
    },
  },
  customerDetails: {
    card: true,
    applePay: true,
    googlePay: true,
  },
  paymentMethods: {
    applePay: { enabled: true },
    googlePay: { enabled: true },
  },
  options: {
    locale: 'en-US',
    enableBackgroundRefresh: true,
    appearance: {
      theme: 'light',
    },
  },
  onReady() {
    console.log('Payment form ready')
  },
  onValidation(snapshot) {
    console.log('Validation:', snapshot.isValid, snapshot.fields)
  },
  onPaymentChange({ installments, button }) {
    console.log('Payment display:', installments, button.label)
  },
  onPaymentProcessing(isProcessing) {
    console.log('Processing:', isProcessing)
  },
  onPaymentComplete(transaction) {
    console.log('Payment completed:', transaction)
  },
  onError(error) {
    console.error('Payment error:', error)
  },
})
```

### 5. Destroy on unmount

```javascript
paymentForm.destroy()
```

Always destroy SDK instances when your checkout component unmounts or the shopper leaves the checkout page.

## Common configuration

| Property | Required | Description |
|  --- | --- | --- |
| `container` | Required for visual widgets | Element id or `HTMLElement` where the iframe should be mounted. |
| `publicKey` | Yes | Your Finance Computer public site key, such as `pk_test_...` or `pk_live_...`. |
| `orderPayload` | Yes | Base64-encoded order payload from your backend. |
| `orderChecksum` | Yes | HMAC signature generated by your backend. |
| `card` | No | Card UI, saved cards, submit button, and validation behavior. |
| `customerDetails` | No | Enables collection for `card`, `applePay`, and `googlePay`; the Dashboard controls which fields are requested. |
| `paymentMethods` | No | Apple Pay and Google Pay configuration for `paymentForm()`. |
| `options` | No | Locale, appearance, and result behavior such as `enableBackgroundRefresh`. |
| `onValidation` | No | Live card-field validation snapshot for custom layouts. |
| `onPaymentChange` | No | Installment selection and pay-button label updates for custom CTAs. |


Supported web locales: `en`, `ro`, `el`, `bg`, `hu`, and `pl`. Pass a BCP-47 tag such as `pl-PL`; the SDK uses the language subtag before the hyphen.

## Security model

Embedded Checkout keeps payment collection isolated from merchant application code:

1. On the web, card inputs and wallet flows are rendered in Finance Computer-hosted iframes.
2. In native apps, PAN and CVV are collected in native SDK views. In React Native, card data does not cross the JavaScript bridge.
3. Your backend signs order details and returns only the signed payload and checksum to the client.
4. The app contains only a publishable public key. Never include a private or secret API key in client code.
5. Final fulfillment should be confirmed server-side through webhooks or trusted API checks.


Native SDKs handle 3DS challenges, although issuer authentication may use web content internally.

If your checkout page uses Content Security Policy, configure `frame-src` for the SDK's iframe-based 3DS modal. Issuer ACS domains vary, so embedded 3DS requires allowing HTTPS frame destinations. See [3DS and payment results](/guides/checkout/inline-checkout/3ds-results#content-security-policy-for-embedded-3ds).

Confirm final status on your backend
Web callbacks and native `PaymentResult` values are client-side signals for updating the shopper experience. Always verify the final transaction status server-side before fulfilling an order or storing a saved-card token.

## Browser and wallet support

The card form is designed for modern desktop and mobile browsers. Wallet availability depends on the shopper's device, browser, wallet setup, domain verification, and merchant activation.

Apple Pay in Embedded Checkout is not limited to Safari. When Apple Pay is available in another browser, the SDK loads Apple's web SDK and may present a QR or window-based flow. Use capability checks before rendering standalone wallet buttons:

```javascript
const capabilities = await window.XMoney.getPaymentMethodCapabilities()

// Unsupported wallets include a diagnostic reason such as:
// capabilities.applePay.reason === 'APPLE_PAY_NOT_SUPPORTED'
// capabilities.googlePay.reason === 'GOOGLE_PAY_NOT_AVAILABLE'
```

For wallet-specific setup, see [Apple Pay](/guides/payments/payment-methods/apple-pay) and [Google Pay](/guides/payments/payment-methods/google-pay). For installment plans, see [Installments](/guides/checkout/inline-checkout/installments).