React Web
React Web Component

React Web Component

Let's get started with Volume in less than 5 minutes!.

Our React component allows you to quickly and easily integrate volume into your React application in no time!

Getting Started

Get started by installing the required dependencies:

npm install @getvolume/react

Volume Provider

The volume provider should be placed at the root level of your application, this provides key global configuration for using volume in your application.

VolumeProvider props

Required Props

applicationIdstring123456789Your Application Id as provided in your Merchant Portal. (For BETA merchants please contact us directly for your ID.)
volumeEnvironmentstringsandboxAn environment to be used, this is either 'live' | 'sandbox' | A full URI if we have provided a specific environment for you.

Optional Props

onEventcallback functiononEventEvent handler function, see onEvent for detailed instructions on how it works.
import { VolumeProvider } from '@getvolume/react-web'
export default function Root() {
  return (
      <App />

Volume event callback

This callback function is triggered each time an internal Volume event occurs.

          onEvent={(event: VolumeEvent) => {

Structure of the event object:

    interface VolumeEvent {
         * Enum of unique event types
        type: VolumeEventType;
         * Unix timestamp
        time: number;
         * Event specific meta
        meta?: {};

These types of events are supported:

    enum VolumeEventType {
        GenericError = "GENERIC_ERROR",
        PaymentInitiated = "PAYMENT_INITIATED",
        ConfirmPageLoaded = "CONFIRM_PAGE_LOADED",
        BankSelectionLoaded = "BANK_SELECTION_LOADED",
        AwaitingAuthorisation = "AWAITING_AUTHORISATION",
        BankLaunchedLoaded = "BANK_LAUNCHED_LOADED"

Volume Events can be divided into two groups:

  • Behavioral events - triggered by user actions or its results
  • UI events - triggered by UI views being loaded and presented to the user
Behavioral eventdescriptionmeta
GENERIC_ERRORIs triggered when an unknown error happens.Meta is a string description of the problem.
PAYMENT_INITIATEDIs triggered when the user clicks a certain bank icon.Look below the table for the example.
AWAITING_AUTHORISATIONIs triggered when the user clicks the confirm button.Look below the table for the example.
UI eventdescriptionmeta
BANK_SELECTION_LOADEDIs triggered when the page with bank icon selection list is displayed.No metadata.
CONFIRM_PAGE_LOADEDIs triggered when the page with the Confirm Button is displayed.No metadata.
BANK_LAUNCHED_LOADEDIs triggered when the final page with the final confirmation label is displayed. After user clicked the Confirm Button.No metadata.

A PaymentInitiated event metadata example:

    meta: {
        institution: '',
        merchantPaymentId: 'merchantPaymentId',
        paymentId: 'paymentId',
        reference: 'payment reference',
        metadata: {...} // metadata object passed by the merchant to the Volume tag

An AwaitingAuthorisation event metadata example:

    meta: {
        institution: '',
        reference: 'payment reference'


Include the following style import at your application entry point to ensure the correct styling is applied to the Volume component.


If you do not include the style import, the Volume button will not render correctly.

import '@getvolume/react/dist/index.css'

Regenerating Merchant Payment ID

Each time VolumeEventType.PaymentInitiated is emitted Merchant Payment ID should be set to a new unique value.

The Volume Button

Once you have added the VolumeProvider, all you need to do is add the Volume component to your app!

The Volume component accepts following props:

amountnumberMin 0.011Amount to be paid, ie £1.00.
currencystringISO 4217GBPCurrency of payment
referencestringMax 18 chars, AlphanumericABC-123Pass a bank transfer reference, it will be visible by both a client and merchant in bank transfer history.
merchantPaymentIdstring (Optional)Max 50 chars, unique per payment123456Pass a merchantPaymentId to associate a unique identifier for the payment, this will be returned to you in any webhook or api responses for the given payment
metadatajson object (Optional)Max 5000 chars length after serialization to string{ "mydata": "myvalue" }metadata is an optional JSON object which will be passed back in webhooks as paymentMetadata. Detailed description below.
paymentStatusCallbackcallback function (Optional)(status) => {...}A callback function called each time a payment status has changed. Works ONLY in desktop mode with QR code visible. Detailed description below.
componentViewTypeCallbackcallback function (Optional)(viewType) => {...}A callback function called when component is rendered and it detects if it has to display the mobile or desktop view. Detailed description below.
import { Volume } from '@getvolume/react-web'
export default function ProductPage() {
  return (
        reference={'Example Reference'}
        metadata: { // Optional, max 5000 chars after serialization
            "mydata": "myvalue"
            (paymentStatus: PaymentStatusResponse) => {
                console.log("I've got a new status: " + JSON.stringify(paymentStatus));
            (componentViewType: ComponentViewType) => {
                console.log("Component UI type is: " + componentViewType);


metadata is an optional JSON object which will be passed back in webhooks as paymentMetadata. metadata must be a valid JSON object, so these values are not allowed:

    metadata: 1
    metadata: "test"
    metadata: [1,2,3]

metadata can be nested. This object is a valid example:

    metadata: {
        "id": "0001",
        "type": "donut",
        "name": "Cake",
                        { "id": "1001", "type": "Regular" }


A callback function called each time a payment status has changed.


It is called ONLY in desktop mode with QR code visible. It works based on payment status pooling and in mobile view this mechanism is not used.

   interface PaymentStatusResponse {
       paymentStatus: PaymentStatus;
       errorDescription?: string;
   enum PaymentStatus {
       NEW = "NEW",
       FAILED = "FAILED",


Volume component can be automatically rendered in one of 3 views:

  • desktop view with QR code visible
  • mobile view with no bank preselected (MOBILE_NEW_CUSTOMER)
  • mobile view with a bank preselected (MOBILE_RETURNING_CUSTOMER)

When the component is being rendered this callback function is triggrred with an information which view is going to be presented to the user.

   enum ComponentViewType {

Implementing the after payment screen (Callback)

After the payment user is navigated back from the banking app to your page using callback.

Documentation for the Volume Callback parameters: Callback


After you have completed the steps above, then you can start testing.

We strongly recommend to use sandbox environment before switching to live environment.

Please note that sandbox testing will not open the Banking app due to lack of testing environment offered by the different banks in the UK. However, a successful test will open the bank environment via the browser. The user experience will differ bank by bank. Ask us more information at or use the chat in this page to get immediate assistance.

Please check Sandbox Banks Credentials to be able to test with Natwest Sandbox and other sandbox banks.