JavaScript

Opens the checkout over your page, so the buyer pays into escrow without leaving your site. It’s a small launcher with no dependencies: the checkout itself is drawn by KetaPay inside a secure frame. Source on GitHub. Using React? See React.

How it works

Your server creates a checkout session with your secret key and sends its url to the page.
Your page calls KetaPay.open({ url }). The checkout opens as a centred window on a computer, and fills the screen on a phone.
The buyer pays. You get onSuccess in the browser and escrow.funded on your server.

onSuccess can’t prove a payment. Before you ship anything, wait for the escrow.funded webhook or fetch the session (see Verify payments).

This library takes no keys. Your secret key stays on your server.

Install

<script src="https://js.ketapay.com/v0.1.0-beta.1/checkout.js"></script>

npm install @ketapay/checkout@next

The script tag adds window.KetaPay.

Open the checkout

// With the script tag, use window.KetaPay instead
import { KetaPay } from '@ketapay/checkout'

payButton.addEventListener('click', async () => {
  const { url } = await fetch('/api/checkout', {
    method: 'POST',
  }).then((r) => r.json())

  KetaPay.open({
    url,
    onSuccess: () => showThankYou(),
    onError: () => showMessage('Checkout could not load.'),
    onClose: () => {},
  })
})

Option
`url`	The session’s `url`, exactly as the API returned it. Required
`onReady`	The checkout is showing
`onSuccess`	The buyer paid. The receipt stays on screen until they close it
`onError`	The checkout didn’t load. Gets a `KetaPayCheckoutError`
`onClose`	The checkout closed, whether or not the buyer paid

open returns { close, result }. result resolves once, to 'success' when the buyer pays, 'error' if the checkout doesn’t load, or 'closed' if they close it first:

const checkout = KetaPay.open({ url })
if ((await checkout.result) === 'success')
  window.location.href = '/orders'

Call checkout.close() to close it yourself, for example straight after onSuccess if you’d rather show your own receipt. Opening a second checkout while one is showing returns the one already open.

Branding

The checkout shows your business’s logo and colour from your KetaPay settings. There are no styling options in the browser, so it looks the same as your hosted checkout.

Errors

Every error is a KetaPayCheckoutError with a code. Mistakes in the call are thrown by open before anything shows; a checkout that doesn’t load goes to onError.

Code	How you get it	When
`invalid_url`	thrown	The `url` isn’t a KetaPay checkout. Pass the session’s `url` unchanged
`not_in_browser`	thrown	Called during server rendering. Call it from a click handler or an effect
`load_failed`	`onError`	The checkout didn’t load: an unknown or expired session, or the buyer’s network. The overlay closes, `onClose` runs and `result` is `'error'`

Good to know

Server rendering: importing the package touches neither window nor document, so it’s safe in Next.js, Remix and Nuxt.
Content Security Policy: add frame-src https://checkout.ketapay.com, and script-src https://js.ketapay.com if you use the script tag. The overlay needs nothing in style-src.
Sandbox: sessions created with an sk_test_ key open the same checkout in test mode. See Testing.
Browsers: the last two versions of Chrome, Edge, Firefox and Safari, and Safari on iOS 15 or later.

Versions

Script tag URLs name an exact version and never change once published. When 1.0 is out, https://js.ketapay.com/v1/checkout.js will always serve the newest 1.x.

SDKs

Server

Browser

Plugins

How it works

Install

Open the checkout

Branding

Errors

Good to know

Versions

​How it works

​Install

​Open the checkout

​Branding

​Errors

​Good to know

​Versions

How it works

Install

Open the checkout

Branding

Errors

Good to know

Versions