> For the complete documentation index, see [llms.txt](https://docs.payr.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payr.com/payment-interface/payr-sdk.md).

# Payr SDK

The Payr JavaScript SDK allows you to embed a fully customizable payment interface directly into your platform, with control over colors, fonts, and styling to match your brand.

***

### Overview

The SDK provides the same payment features as the iframe integration (APMs, recurring payments, wallet payments, and card management) with the added benefit of full UI customization through the `appearance` API.

**Key Benefits:**

* Full UI customization (colors, fonts, border radius, typography)
* All payment features can be included
* Embedded in your page (not isolated iframe)
* Programmatic control via JavaScript API

***

### Embedding the SDK

Partners can load the SDK in two common ways. Pick one pattern per page; mixing two copies of the SDK can cause state conflicts.

#### 1. ES Module (Recommended for Modern Browsers)

Use a **module script** and the **default** export:

```html
<div id="payr-form"></div>
<script type="module">
  import PAYR from 'https://cdn.mypayr.co.uk/payr-sdk.js';

  await PAYR.init({
    apiBaseUrl: 'https://sandbox-api.mypayr.co.uk',
    authToken: '…', // from your backend
    container: '#payr-form',
    environment: 'sandbox'
  });
</script>
```

**Use case:** Modern checkout pages, static sites, or any HTML where you control the deployment. Smaller initial parse with code-splitting; chunks load on demand.

**Requirements:** Browsers that support ES modules. `script type="module"` is deferred and runs after the document is parsed unless you use `async`.

***

#### 2. Single-File UMD (Legacy Support)

Load the UMD build with a classic script tag. The global **`PAYR`** object exposes `init`, `pay`, `destroy`, and other public methods.

```html
<div id="payr-form"></div>
<script src="https://cdn.mypayr.co.uk/payr-sdk.js"></script>
<script>
  PAYR.init({
    apiBaseUrl: 'https://sandbox-api.mypayr.co.uk',
    authToken: '…',
    container: '#payr-form',
    environment: 'sandbox'
  })
    .then(() => {
      console.log('SDK ready');
    })
    .catch((err) => console.error('Init failed:', err));
</script>
```

**Use case:** Legacy stacks, CMS templates that only allow one script URL, or environments where you cannot use ES modules.

**Trade-off:** One larger file instead of code-splitting.

***

### Quick Start

#### 1. Create a Payment Session

First, create a payment session using your backend (same as iframe integration):

```bash
curl -X POST https://sandbox-api.mypayr.co.uk/thirdparty/user-login/ \
  -H "Authorization: Token your_server_token" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'
```

**Response:**

```json
{
  "token": "x9y8z7w6v5u4t3s2r1q0p9o8n7m6l5k4j3i2h1g0f9e8d7c6b5a4",
  "session_id": "01KH1FZ0N0..."
}
```

#### 2. Initialize the SDK

Pass the `token` from `/user-login/` to initialize the SDK:

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

<script>
  // Wait for SDK to load
  window.addEventListener('load', function() {
    PAYR.init({
      apiBaseUrl: 'https://sandbox-api.mypayr.co.uk', 
      authToken: 'YOUR_TOKEN_FROM_USER_LOGIN',
      container: '#payr-payment-form',
      environment: 'sandbox',  // Use 'sandbox' for testing, 'production' for live
      features: {
        apms: true,
        recurring: true
      },
      onSuccess: function(result) {
        console.log('Payment successful:', result);
        // Handle success (e.g., show confirmation page)
      },
      onError: function(error) {
        console.error('Payment failed:', error);
        // Handle error (e.g., show error message)
      }
    });
  });
</script>
```

#### 3. Trigger Payment

The SDK renders a payment form in your container. When the user is ready to pay, call `PAYR.pay()`:

```javascript
const payButton = document.getElementById('pay-button');

payButton.addEventListener('click', async function() {
  try {
    await PAYR.pay();  // No arguments — uses config from init
  } catch (error) {
    console.error('Payment error:', error);
  }
});
```

> **Note:** For wallet payments (Apple Pay/Google Pay), users tap the wallet button directly. You don't need to call `PAYR.pay()` — the SDK handles it automatically.

***

### Configuration Reference

#### PAYR.init() Options

Initialize the SDK with your configuration.

<table><thead><tr><th width="135.92578125">Option</th><th width="137.3203125">Type</th><th>Required</th><th width="117.8515625">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>apiBaseUrl</code></td><td><code>string</code></td><td>Yes</td><td>-</td><td>Payr API base URL (no trailing slash)</td></tr><tr><td><code>authToken</code></td><td><code>string</code></td><td>Yes</td><td>-</td><td>Auth token from <code>/user-login/</code> endpoint</td></tr><tr><td><code>container</code></td><td><code>string | HTMLElement</code></td><td>Yes</td><td>-</td><td>CSS selector or DOM element for the payment form</td></tr><tr><td><code>pure_amount</code></td><td><code>number</code></td><td><strong>Required</strong> unless <code>isAmountEditable: true</code></td><td>-</td><td>Base payment amount in <strong>pounds</strong> (e.g., 10.50 for £10.50). </td></tr><tr><td><code>isAmountEditable</code></td><td><code>boolean</code></td><td>No</td><td><code>false</code></td><td>When <code>true</code>, renders an <strong>editable amount input</strong> inside the SDK UI so the user can update the amount within the session. </td></tr><tr><td><code>reference</code></td><td><code>string</code></td><td>No</td><td>-</td><td>Optional payment reference attached to all payments from this session. If omitted, SDK generates <code>PAYR_&#x3C;timestamp></code>.</td></tr><tr><td><code>environment</code></td><td><code>'sandbox' | 'production'</code></td><td>No</td><td><code>'production'</code></td><td>Sandbox for testing, Production for live.</td></tr><tr><td><code>debug</code></td><td><code>boolean</code></td><td>No</td><td><code>false</code></td><td>Enable verbose logging and 3DS verification messages</td></tr><tr><td><code>features</code></td><td><code>object</code></td><td>No</td><td><code>{}</code></td><td>Feature flags (see Features section)</td></tr><tr><td><code>appearance</code></td><td><code>object</code></td><td>No</td><td>Payr defaults</td><td>Theming options for colors, fonts, border radius</td></tr><tr><td><code>onSuccess</code></td><td><code>function</code></td><td>No</td><td>-</td><td>Success callback: <code>(result) => void</code></td></tr><tr><td><code>onError</code></td><td><code>function</code></td><td>No</td><td>-</td><td>Error callback: <code>(error) => void</code></td></tr></tbody></table>

***

#### Amount Behavior

**Fixed Amount (Default):**

The payment amount is set during SDK initialization and remains fixed for the entire session. Users cannot change it.

```javascript
PAYR.init({
  apiBaseUrl: 'https://sandbox-api.mypayr.co.uk',
  authToken: token,
  container: '#payr-payment-form',
  pure_amount: 850.00,  // Fixed amount for this session
  environment: 'sandbox'
});
```

**Editable Amount (Optional):**

Set `isAmountEditable: true` to allow users to enter or change the payment amount in the SDK UI.&#x20;

```javascript
// Empty amount input (user must enter amount)
PAYR.init({
  apiBaseUrl: 'https://sandbox-api.mypayr.co.uk',
  authToken: token,
  container: '#payr-payment-form',
  isAmountEditable: true,  // User can enter/change amount
  environment: 'sandbox'
});

// Pre-filled amount input (user can edit)
PAYR.init({
  apiBaseUrl: 'https://sandbox-api.mypayr.co.uk',
  authToken: token,
  container: '#payr-payment-form',
  pure_amount: 850.00,      // Pre-filled value
  isAmountEditable: true,   // User can change it
  environment: 'sandbox'
});
```

***

### Next Steps

Now that you understand the basics, explore advanced SDK features and setup:

**Configuration & Customization**

* [**Payment Flow**](/payment-interface/payr-sdk/payment-flow.md) - Learn how to trigger payments with `PAYR.pay()`
* [**Features**](/payment-interface/payr-sdk/features.md) - Enable APMs, recurring payments, card management, and wallets
* [**Customizing Appearance**](/payment-interface/payr-sdk/customization.md) - Match the SDK to your brand with colors, fonts, and styling
* [**Security & CSP**](/payment-interface/payr-sdk/security-requirements.md) - Configure Content Security Policy for production