Payparse.js SDK Reference

The Payparse Client SDK allows you to embed secure, seamless Interac e-Transfer validation frames directly into your existing user interfaces without directing customers away from your platform.

Loading the Library

Include the vanilla injection script globally within your document header context:

<script src="https://js.payparse.ca/v1/payparse.js"></script>

Initializing the Client

Instantiate the global client SDK wrapper using your publishable token:

const pp = Payparse('pp_pub_test_your_publishable_key');

The constructor validates that your key begins with pp_pub_. If the key is invalid, it throws an error so failures surface immediately during development. Multiple independent instances can run simultaneously on complex enterprise pages.

Methods

pp.redirectToCheckout({ sessionId })

Redirects the browser to the fully qualified hosted checkout URL for the given session.

pp.redirectToCheckout({ sessionId: 'cs_abc123xyz' });

• sessionId (String, required): The checkout session identifier returned from your server-side call.

pp.createButton(selector, options)

Injects a styled, accessible button into a target DOM element. On click it POSTs to your sessionEndpoint to acquire a session, then triggers the redirect sequence.

pp.createButton('#payparse-button', {
  sessionEndpoint: '/api/create-checkout',
  style: {
    theme: 'dark',      // 'light' | 'dark' | 'auto'
    size: 'large',      // 'small' | 'medium' | 'large'
    borderRadius: '8px'
  },
  onError: (err) => console.error('Checkout init failed:', err)
});

• selector (String): The DOM selector for the target element.
• options.sessionEndpoint (String, required): Your server route that creates a session.
• options.style.theme: Visual theme. auto follows the OS prefers-color-scheme preference.
• options.onError (Callback): Triggered if session acquisition fails.

pp.embedCheckout(selector, options)

Renders a secure payment interface within a target container element utilizing an iframe sandbox configuration. This keeps the payment window isolated from your page's JavaScript context while preserving a native feel.

pp.embedCheckout('#payparse-container', {
  clientSecret: 'mock_secret_abc123xyz',
  onComplete: (result) => {
    console.log('Payment status updated to:', result.status);
    showSuccessMessage();
  },
  onError: (error) => {
    console.error('Checkout failed:', error.message);
  }
});

Parameters

• selector (String): The DOM selector target element (e.g., #payparse-frame).
• options (Object): Configuration payload settings:
  • clientSecret (String): The session token returned from your server-side call.
  • onComplete (Callback): Triggered when an e-Transfer signature registers successfully.
  • onError (Callback): Triggered if the validation window encounters errors.
  • onCancel (Callback, optional): Triggered when the customer cancels the embedded frame.

Security Model

The injected iframe is locked down with a strict sandbox:

<iframe sandbox="allow-scripts allow-same-origin allow-forms allow-popups"
        referrerpolicy="strict-origin-when-cross-origin"
        src="https://checkout.payparse.ca/embed/{clientSecret}"
        title="Secure checkout"></iframe>

The SDK listens for postMessage events originating strictly from https://checkout.payparse.ca and parses status transitions:

Event Type	Callback	Payload
checkout.complete	onComplete	{ status: 'pending' }
checkout.error	onError	{ message }
checkout.resize	(internal)	{ height } — auto-resizes frame

This cross-document messaging protocol prevents clickjacking and cross-origin data leakage while enabling rich runtime callbacks.

pp.getPaymentStatus(sessionId)

Polls the current state of a checkout session. Useful for simple integrations that prefer polling over webhooks.

const status = await pp.getPaymentStatus('cs_abc123xyz');
console.log(status.status); // 'PENDING' | 'COMPLETED' | 'EXPIRED'