@quickpay/js

Vanilla JavaScript SDK for accepting payments in any web application.

Installation

Terminal

npm install @quickpay/js

Alternatively, load via CDN:

HTML

<script src="https://js.quickpay.com/v1/quickpay.min.js"></script>

Initialization

Create a YardPay instance with your publishable key. This is safe to expose in client-side code.

quickpay.ts

import { QuickPay } from '@quickpay/js';

const qp = QuickPay('pk_live_your_publishable_key');

Elements System

Elements are pre-built UI components that collect payment details securely. They handle card tokenization, 3DS authentication, and input validation automatically.

Creating Elements

elements.ts

// Create an Elements instance bound to a checkout session
const elements = qp.elements({ clientSecret: 'cs_live_abc123_secret_xyz789' });

// PaymentElement — renders card, Click to Pay, and all available methods
const paymentElement = elements.create('payment', {
  layout: 'tabs', // 'tabs' | 'accordion' | 'auto'
});
paymentElement.mount('#payment-element');

// CardElement — renders a standalone card input
const cardElement = elements.create('card', {
  style: {
    base: { fontSize: '16px', color: '#1a1a1a' },
    invalid: { color: '#e53e3e' },
  },
});
cardElement.mount('#card-element');

PaymentElement

The PaymentElement automatically displays available payment methods based on your checkout session configuration, including card payments, Click to Pay, and saved cards.

const paymentElement = elements.create('payment', {
  layout: 'tabs',
  defaultValues: {
    billingDetails: {
      name: 'Jane Doe',
      email: '[email protected]',
    },
  },
});
paymentElement.mount('#payment-element');

CardElement

A focused card-only input when you want full control over the UI layout.

const cardElement = elements.create('card', {
  hidePostalCode: false,
  iconStyle: 'solid',
});
cardElement.mount('#card-element');

confirmPayment()

After the user fills in the payment form, call confirmPayment() to submit the payment. The SDK handles 3DS challenges automatically.

confirm.ts

const { paymentResult, error } = await qp.confirmPayment({
  elements,
  confirmParams: {
    return_url: 'https://yoursite.com/order/complete',
  },
});

if (error) {
  // Show error in your UI (e.g. card declined)
  document.getElementById('error-message')!.textContent = error.message;
} else if (paymentResult) {
  // Payment succeeded without redirect
  console.log('Payment status:', paymentResult.status);
}

Note

If the payment requires a redirect (e.g. 3DS challenge), the user will be automatically redirected to the return_url with the session ID appended as a query parameter.

redirectToCheckout()

For hosted checkout mode, redirect the user to YardPay's hosted payment page.

redirect.ts

await qp.redirectToCheckout({
  sessionId: 'cs_live_abc123_secret_xyz789',
});

// The user is redirected to YardPay's hosted checkout page.
// After payment, they return to your successUrl or cancelUrl.

Pay button

A ready-made, accessible <button> that sends the customer to the hosted checkout page. Card details are entered on the hosted page, never on yours. Use qp.payButton() when your server should create the session at click time, or elements.create('payButton') for a session you already created.

pay-button.ts

// Session created by your server when the customer clicks
const button = qp.payButton({
  label: 'Pay $25.00',
  createSession: async () => {
    const res = await fetch('/api/create-checkout-session', { method: 'POST' });
    const { clientSecret } = await res.json();   // from POST /api/v1/checkout-sessions (mode: "hosted")
    return clientSecret;
  },
});
button.mount('#pay-button');

// Or, for a session you already have
const elements = qp.elements({ clientSecret: 'cs_live_abc123_secret_xyz789' });
elements.create('payButton', { label: 'Pay now' }).mount('#pay-button');

button.on('change', (e) => {
  if (e.error) console.warn(e.error.message); // also shown inline under the button
});

Options: label, processingLabel, ariaLabel, disabled, clientSecret, createSession and style.base / style.invalid. The session must be created with mode: "hosted".

onPaymentStatus()

Poll or listen for the final payment status after a redirect. Use this on your return page to display the outcome.

status.ts

// On your return_url page
const qp = QuickPay('pk_live_your_publishable_key');

const { status, paymentResult } = await qp.onPaymentStatus({
  clientSecret: 'cs_live_abc123_secret_xyz789',
});

switch (status) {
  case 'succeeded':
    showSuccessMessage();
    break;
  case 'processing':
    showProcessingMessage();
    break;
  case 'requires_payment_method':
    showRetryMessage();
    break;
}

Event Handling

Elements emit events you can listen to for building dynamic UIs.

events.ts

// Listen for changes on the payment element
paymentElement.on('change', (event) => {
  // event.complete — true when the form is valid
  // event.empty — true when the form has no input
  // event.error — validation error if present
  submitButton.disabled = !event.complete;
});

// Focus and blur events
cardElement.on('focus', () => {
  cardContainer.classList.add('focused');
});

cardElement.on('blur', () => {
  cardContainer.classList.remove('focused');
});

// Ready event — element has fully loaded
paymentElement.on('ready', () => {
  loadingSpinner.style.display = 'none';
});

Full Example

<!DOCTYPE html>
<html>
<body>
  <form id="payment-form">
    <div id="payment-element"></div>
    <button id="submit-btn" type="submit" disabled>Pay</button>
    <div id="error-message"></div>
  </form>
  <script type="module" src="./checkout.js"></script>
</body>
</html>