Hosted vs. Embedded Flows

Volley supports two user experience options for payments on your website. You can either redirect customers to our hosted checkout or embed the payment flow directly into your own pages using our iframe widget.

The hosted checkout involves minimal setup: just create a payment request and redirect customers to complete their payment. The embedded checkout offers the same functionality while keeping customers on your site throughout the entire transaction.

Using the Hosted Checkout

Using Volley’s hosted checkout is the easiest way to get started with payment requests. You only need to create a payment request and redirect your customer to the hosted checkout URL, and Volley will handle the entire payment interface, bank selection, and authentication flow.

Benefits

• No frontend integration required: Volley provides the complete payment UI

• Automatic device detection: Displays QR code for desktop users or direct redirect for mobile users

• Built-in failure handling: Payment failures and retry logic managed by Volley

Redirection

The hosted checkout can be used by redirecting your customer’s browser to the request.url returned from the POST /requests endpoint. To have a user return to your app after payment, provide the success_redirect_url and failure_redirect_url fields when creating a request.

Using the Embedded Checkout

The embedded checkout is an iframe widget that integrates Volley's payment flow directly into your checkout page, offering a simple payment experience without redirecting customers away from your site.

The embedded checkout widget renders:

• On desktop: A QR code that customers scan with their mobile device to complete payment via their banking app

• On mobile: A button that redirects customers to their banking app to authorize the payment

Benefits

• Seamless integration: Customers stay on your site throughout the payment process

• Reduced friction: No full-page redirects on desktop, maintaining checkout context

• Responsive design: Automatically adapts between QR code (desktop) and redirect button (mobile)

• Event callbacks: JavaScript events for payment status updates and user interactions

Include the Volley Checkout SDK

Include the Volley Checkout Element SDK on your checkout page.

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

Render the Checkout Element

Initialise the checkout element with a payment request ID created by your backend.

// Options:
//  request_id,
//  payment_id (optional), use if you're pre-creating payments via the API
//  orientation (optional), can be 'horizontal' or 'vertical' to fit different UI 

<volley-checkout
  request_id="request_5X2V9irwVZfUaBv9KlWqn"
  orientation="horizontal">
</volley-checkout>

Listen for Status Updates

When a payment is completed, the Checkout Element will update your webpage through the window.postMessage API. You can set up a listener for these events and then guide your user to the next step of your flow.

// Add event listener for messages from iframe
window.addEventListener('message', (event) => {
  // Recommended: Verify the origin of the iframe
  if (event.origin !== 'https://app.volley.nz') {
    return;
  }

  // Events can be one of:
  //  - volley.payment_cancelled
  //  - volley.payment_failed
  //  - volley.payment_successful

  if (event.data.type === 'volley.payment_successful') {
    const { payment_id, request_id } = event.data.payload;
    
    // Pass the payment ID back to your backend for validation
    // ... then complete your payment flow
  }
});

The cancelled and failed events may have an additional property retryable. If this is set, Volley will prompt for the user to retry paying the request.