---
url: https://docs.youcan.shop/youcan-pay/yp-js/getting-started.md
---
# yp.js: Getting Started

`yp.js` is a self-contained JavaScript library that renders the YouCan Pay payment form in the browser. It loads from a CDN and exposes a global `yp` function. It ships as a UMD bundle, so it works with a plain `<script>` tag or a module bundler.

## Load the Library

Add the script to your page. It defines `window.yp`.

```html
<script src="https://youcanpay.com/yp.js"></script>
```

## Quick Start

You need a payment token from your server first. See the [Payment Flow](/youcan-pay/payment-flow).

```html
<div id="payment"></div>
<button id="pay" type="button">Pay</button>

<script src="https://youcanpay.com/yp.js"></script>
<script>
  const payment = yp('pub_xxx', { locale: 'en' })
    .elements({ token: 'token_xxx', container: '#payment' });

  payment.mount();

  document.getElementById('pay').addEventListener('click', async () => {
    const result = await payment.confirm();

    if (result.status === 'succeeded') {
      // send result.transaction to your server, or redirect
    } else {
      // show result.error.message
    }
  });
</script>
```

## API

### `yp(publicKey, options?)`

Creates a client. Returns an object with an `elements` method.

| Parameter | Type | Description |
| --- | --- | --- |
| `publicKey` | `string`, required | Your account public key. Prefixed with `pub_`. |
| `options.locale` | `string`, optional | Form language: `en`, `fr`, or `ar`. Defaults to `en`. `ar` renders right-to-left. |

> **Note:** Sandbox mode is detected from the token. You do not set it. See [Sandbox & Testing](/youcan-pay/yp-js/sandbox).

### `client.elements(options)`

Creates a payment element. Returns a `PaymentElement`.

| Parameter | Type | Description |
| --- | --- | --- |
| `token` | `string`, required | The payment token from your server. |
| `container` | `string` | `HTMLElement`, required | A CSS selector or element that holds the form. |
| `gateways` | `string[]`, optional | Limits and orders the payment methods. See [Gateways](#gateways). Omit to show every method the account allows. |
| `appearance` | `object`, optional | Theming for the form. See [Appearance](/youcan-pay/yp-js/appearance). |

### `element.mount()`

Renders the form inside the container. Returns a `Promise` that resolves when the form is ready. It rejects if the account is inactive, the host is not allowed, or no payment method is available.

### `element.confirm()`

Confirms the payment for the selected method. Returns a `Promise<PaymentResult>`. It never rejects. Check the `status` field.

```ts
interface PaymentResult {
  status: 'succeeded' | 'failed';
  gateway: string;          // the method used
  transaction?: object;     // present on success
  error?: { code: string; message: string }; // present on failure
}
```

For card payments with 3DS, `confirm()` handles the bank verification before it resolves. In production it uses a popup, or a redirect inside a webview. In the sandbox it uses a modal. See [Sandbox & Testing](/youcan-pay/yp-js/sandbox).

### `element.on(event, listener)`

Subscribes to an event. Returns a function that removes the listener. See [Events & Errors](/youcan-pay/yp-js/events).

### `element.destroy()`

Removes the form from the page.

## Gateways

The form shows every method the account accepts. When more than one is available, the customer picks one. Pass `gateways` to limit or order them.

| ID | Method |
| --- | --- |
| `credit-card` | Credit card, with 3DS support. |
| `cash-plus` | CashPlus. |

```js
yp('pub_xxx').elements({
  token: 'token_xxx',
  container: '#payment',
  gateways: ['credit-card'], // card only
});
```

## Next Steps

* Theme the form with [Appearance](/youcan-pay/yp-js/appearance).
* Test with [Sandbox & Testing](/youcan-pay/yp-js/sandbox).
* React to state with [Events & Errors](/youcan-pay/yp-js/events).