Web embed

Volley's web embed lets you accept payments directly on your website without redirecting customers away. Add our JavaScript SDK to your page, and Volley renders a payment modal right in your checkout flow - handling bank selection, approval, and confirmation without the customer ever leaving your site.

Try it out

Click the button below to open a live Volley embed on this page.

Using the embed on your webpage

Add the Volley SDK to your page by including the script tag:

<script src="https://app.volley.nz/js/v1/volley-checkout.js"></script>

Then create a checkout instance by passing in the requestId from a payment request you've already created server-side.

// Returns returns a thenable. You can await it to pre-load the checkout fully before showing it
// or call open() or mount() immediately and Volley will display a loading state while it gets ready.
const checkout = Volley.createCheckout({ requestId: "request_qTVSdEszuE9jfpTQaJ3j7" })

// Call open to open the embed as a modal over the page
checkout.open()

// Or call mount to show the checkout within the page in an element you control
checkout.mount("#checkout-container")

Pre-selecting a provider

If you already know which bank your customer uses or you did bank selection in your own UI, you can skip the bank selection step by passing a provider:

// provider can be any of: "anz", "asb", "bnz", "kiwibank", or "westpac".
const checkout = Volley.createCheckout({ requestId: "request_qTVSdEszuE9jfpTQaJ3j7", provider: "asb" })

Handling a payment result

const checkout = Volley.createCheckout({
  requestId: "request_qTVSdEszuE9jfpTQaJ3j7",

  onSuccess({ payment_id, request_id }) {
    // Payment completed - show a confirmation, redirect, or update your UI
  },

  onCancel() {
    // Customer closed the checkout without completing payment
  },

  onError({ payment_id, request_id }) {
    // Payment failed - show an error state or offer a retry
  },
})

All three callbacks are optional, but we recommend implementing at least onSuccess and onError so you can update your UI immediately if necessary. For payment verification, don't rely solely on these client-side callbacks - always confirm the payment status server-side using the API and/or webhooks.

Cleaning up

When you no longer need the checkout on the page, call destroy() to remove it from the DOM entirely. After calling destroy(), the instance can't be reused — call Volley.createCheckout() again if you need a new one.

checkout.destroy()

Setting an allowed domain

Before you can use the embed on your webpage you need to configure the domain you will be hosting it from as an allowed domain in the Volley Dashboard.

The Volley embed renders inside an iframe on your page. For security, Volley only allows the iframe to load your requests on domains you've explicitly approved. Any embed attempts from an unlisted domain will be blocked by the browser. Because Volley ties allowed domains to your account, your payment requests can only ever appear on websites you control - if a request ID is leaked or guessed, it can't be embedded elsewhere.