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.

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

Quick Start

You need a payment token from your server first. See the Payment Flow.

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

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. Omit to show every method the account allows.
appearance	object, optional	Theming for the form. See 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.

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.

element.on(event, listener)

Subscribes to an event. Returns a function that removes the listener. See Events & Errors.

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.

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

Next Steps

• Theme the form with Appearance.
• Test with Sandbox & Testing.
• React to state with Events & Errors.