JavaScript SDK

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

Our vanilla JavaScript component allows you to quickly and easily integrate Volume into your web application in no time!

Importing the script

Import our Volume script into your web page.

    <script src="https://js.volumepay.io/Volume-0.9.3.min.js"></script>

If you do not want to hardcode the version of the Volume component you can source the script from the domain. This will always fetch the newest version:

    <script src="https://js.volumepay.io"></script>

Component usage

After importing our Volume script you can initialise Volume object:

    const volume = new window.Volume({
    		environment: "SANDBOX",
    		applicationId: "5fd31d88-e59a-467e-b084-5c01430afced",
            country: "GB/DE/..",
    		disablePayButton: false, // not required; default FALSE
    		isWebView: false, // not required; default FALSE
    		eventConsumer: (event) => {
                console.log("A VOLUME EVENT: " + event)
            },
            errorConsumer: (error) => {
                console.error(JSON.stringify(error))
            },
    		payLabel: "Pay $", // used for translations; default "Pay by Bank App" 
    		agentType: "WEB_BROWSER" // not required
    	})

Volume component accepts an object with this set of options:

A disabled Pay Button look:

Creating the payment

    let generatedMerchantPaymentId = generateMerchantPaymentId();
 
    volume.createPayment({
        amount: 6.22,
        currency: "EUR/GBP",
        merchantPaymentId: generatedMerchantPaymentId, // UUID
        paymentReference: "payment reference", //max 18 characters
        metadata: { // Optional, max 5000 chars after serialization
            "email": "email@mail.com"
        },
        agentType: "MOBILE_APPLICATION" // Optional
    })

Available countries

When createPayment function is executed, Volume component prepares all the necessary data to communicate with the Volume backend.

amount field should not be wrapped in quotes. Volume supports up to two decimal places.

merchantPaymentId is a UUID which can be used in webhooks consumer to correlate payments. This field is required and must be unique per payment.

paymentReference is the string which will be visible to the client in banking application. This field can be up to 18 characters long.

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: {
        "email": "email@mail.com",
        "id": "0001",
        "type": "donut",
        "name": "Cake",
        "batters":
            {
                "batter":
                    [
                        { "id": "1001", "type": "Regular" }
                    ]
            },
    }

agentType is an optional (default WEB_BROWSER) parameter which can be set on the initial config level or override this value on each createPayment method call. This parameter will determine which backend configured callback url. will be used. 
If WEB_BROWSER is chosen (or left the default), then user will be redirected to the callback URL set in the dashboard under name "Callback url for web". 
Otherwise, if MOBILE_APPLICATION is chosen, then user will be redirected to the callback URL set in the dashboard under name "Callback url for mobile".

Regenerating Merchant Payment ID

It is very important to remember that merchantPaymentId is unique per payment.
It is required to regenerate its value each time payment_initiated event is emitted.

Injecting the component

    volume.injectComponent("volume-element-container")

When injectComponent function is executed, Volume component HTML is injected into your web application exactly into the element with the id, which equals to the provided string.

Enabling and disabling the Pay Button

    volume.toggleButton(buttonEnabledBoolean)

The value passed as an argument to this function will enable or disable the button.

Regenerating Merchant Payment ID

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

Error consumer

This callback function is triggered each time an error occurs. It can be a validation error, authentication error, network error etc. etc. The detail description of the issue will be passed in the argument of the callback method.

    const volume = new window.Volume({
    		...
    		errorConsumer: (error) => {
                console.error("Something is wrong ... : " + JSON.stringify(error))
            }
    		...
    	})

The argument is an object containing two attributes:

• location of type ErrorLocation
• error - a string description of the issue

Example:

    {
       "error": "Input validation error: field=[paymentRequest.reference], value=[TOO LOOOOOOOOOOOOONG], error=[must not be longer than 18 characters]",
       "location":"payWithBankInstitution"
    }

    const ErrorLocation = {
        payWithBankInstitution: "payWithBankInstitution",
        fetchInstitutions: "fetchInstitutions"
    }

Programmatic payment initiation

A payment does not have to be initiated by the user clicking on an institution icon. If the institution is known upfront, it can also be triggered via a function call. Executing this function will open the bank authentication url, just as initiated by the user clicking on an icon.

    volume.createPayment({
        amount: 6.22,
        ...
    })
    volume.payWithInstitution("monzo")

Programmatic opening of the institution selection list

The institution selection list does not have to be initiated by the user clicking on the Pay Button. Executing the openInstitutionSelection function will show the list of institution icons just as it would be opened by the user.

    volume.createPayment({
        amount: 6.22,
        ...
    })
    volume.openInstitutionSelection()

Important note If the function is executed before institutions are fetched from the Volume server, the institution list will be opened after all the necessary data is fetched.

Merchant Provided Payer Details (CoP)

The merchantProvidedPayerDetails parameter allows merchants to pre-populate payer information to optimize the user experience during payment flow. This is also required to gain access to Volume's Confirmation of Payer feature, and to enable the search and filtering of payments by these details.

Usage

return volume.createPayment(
  {
    amount: amount,
    currency: currency,
    paymentReference: reference,
    merchantPaymentId: merchantPaymentId,
    metadata: {
      customerId: "customer01",
      email: "example@getvolume.com"
    },
  },
  {
    // Customer KYC details object
    email: "example@getvolume.com",
    name: "Trevor Scott",
    phone: "+447458674426",
    address: {
      addressLine1: "123 Main Street",
      addressLine2: "Apt 4B",
      countryCode: "GB",
      town: "London",
      postCode: "SW1A 1AA",
    },
  }
);

Compliance Details

Pay-ins can carry compliance details about the payer, the payment and the final recipient. The component has no UI for them: you pass the values you already hold, and the component sends them with the payment. dateOfBirth, nationality and residentialAddress go in the payer details object (the second argument of createPayment). reasonForPayment and ultimateBeneficiary go in the payment object.

volume.createPayment(
  {
    amount: 6.22,
    currency: "GBP",
    merchantPaymentId: generatedMerchantPaymentId,
    paymentReference: "payment reference",
    reasonForPayment: "Invoice 1042",
    ultimateBeneficiary: {
      fullName: "Jane Roe",
      currency: "GBP",
      country: "GB",
    },
  },
  {
    email: "john.doe@example.com",
    name: "John Doe",
    dateOfBirth: "1990-01-31",
    nationality: "GB",
    residentialAddress: "10 Downing Street, London, SW1A 2AA",
  }
);

Payer Details Properties

Payment Properties

ultimateBeneficiary Properties

Required Details

By default every compliance detail is optional. Volume can make a set of them required for your application. When it is required, a payment without every one of these is rejected and no payment is created:

• name and email in the payer details
• dateOfBirth in the payer details
• an address: either residentialAddress, or a complete address (addressLine1, town, postCode, countryCode) in the payer details
• reasonForPayment in the payment

nationality, phone and ultimateBeneficiary are never required.

Handling a Rejected Payment

When a payment is rejected, no payment is created.

When the payer picks a bank in the component (countries with the native flow, GB and FR), your errorConsumer is called. Its error holds the reason from Volume, so you can log it and fix the data you send. For example:

    {
        "error": "400 - Missing required fields: merchantProvidedPayerDetails.dateOfBirth, reasonForPayment",
        "location": "payWithBankInstitution"
    }

Styling

Volume

If the disableVolumeStyling property is set to TRUE, then Volume component will NOT fetches any Volume classes from this location:

    https://js.volumepay.io/Volume-0.4.css

Component will not be styled properly and your own page CSS will have to apply a correct design to it.

Tailwind [DEPRECATED since component version 0.5]

If the disableTailwindStyling property is set to TRUE, then Volume component will NOT fetches any Tailwind classes from this location:

    https://js.volumepay.io/Volume-tailwind-0.1.css

Volume component was created using a set of Tailwind (opens in a new tab) classes, and Volume specific ones. It this property is set to FALSE (or left default), then Volume component will link a CSS file containing a set of Tailwind classes used to style the component. If this property is set to TRUE, the styling will rely on classes provided by your application.

Testing

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 support@getvolume.com 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.

WebView issues

Rendering the VanillaJS component in a WebView container presents no issues but the WebView technology itself is not prepared to open Android App Links correctly. It opens banking institution as web pages instead.

To prevent this issue we have added a mechanism which allows detecting this situation and handling it differently in the application.

Use the isWebView configuration parameter to tell the component to add a special postfix #OPEN_AS_APPLINK to the URL which should redirect the user to the banking application.

    new window.Volume({
    		isWebView: true,
    ...})

In Your application please add a specific code that handles links differently if the URL contains this kind of postfix and removes the postfix from the URL.

The #OPEN_AS_APPLINK postfix needs to be removed from the authorisation URL before redirecting the user. Leaving it causes some banks to fail the whole payment.

        // handle VOLUME OPEN BANKING authentication
        if (url.endsWith("#OPEN_AS_APPLINK")) {
            try {
                val urlWithoutFragment = url.replace("#OPEN_AS_APPLINK", "")
                val newUri = Uri.parse(urlWithoutFragment)
                val newBrowseIntent = Intent(Intent.ACTION_VIEW).setData(newUri)
                context.startActivity(newBrowseIntent)
            } catch (e: Exception) {
                // log the error
            }
            return true
        }

A simple sample project that has this logic implemented: https://github.com/getvolume/WebViewExample (opens in a new tab)

Direct code link: https://github.com/getvolume/WebViewExample/blob/main/app/src/main/java/info/plateaukao/einkbro/browser/NinjaWebViewClient.kt#L141-L152 (opens in a new tab)