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/reactVolume 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
| key | type | example | description |
|---|---|---|---|
| applicationId | string | 123456789 | Your Application Id as provided in your Merchant Portal. (For BETA merchants please contact us directly for your ID.) |
| volumeEnvironment | string | sandbox | An environment to be used, this is either 'live' | 'sandbox' | A full URI if we have provided a specific environment for you. |
Optional Props
| key | type | example | description |
|---|---|---|---|
| onEvent | callback function | onEvent | Event handler function, see onEvent for detailed instructions on how it works. |
import { VolumeProvider } from '@getvolume/react-web'
export default function Root() {
return (
<VolumeProvider
applicationId="123456789"
volumeEnvironment="sandbox"
onEvent={handleEvent}
>
<App />
</VolumeProvider>
)
}Volume event callback
This callback function is triggered each time an internal Volume event occurs.
<VolumeProvider
applicationId="123456789"
volumeEnvironment="sandbox"
onEvent={(event: VolumeEvent) => {
console.log(JSON.stringify(event))
}}
>
...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 event | description | meta |
|---|---|---|
| GENERIC_ERROR | Is triggered when an unknown error happens. | Meta is a string description of the problem. |
| PAYMENT_INITIATED | Is triggered when the user clicks a certain bank icon. | Look below the table for the example. |
| AWAITING_AUTHORISATION | Is triggered when the user clicks the confirm button. | Look below the table for the example. |
| UI event | description | meta |
|---|---|---|
| BANK_SELECTION_LOADED | Is triggered when the page with bank icon selection list is displayed. | No metadata. |
| CONFIRM_PAGE_LOADED | Is triggered when the page with the Confirm Button is displayed. | No metadata. |
| BANK_LAUNCHED_LOADED | Is 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: 'institution.id',
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: 'institution.id',
reference: 'payment reference'
}Styles
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:
| key | type | constraints | example | description |
|---|---|---|---|---|
| amount | number | Min 0.01 | 1 | Amount to be paid, ie £1.00. |
| currency | string | ISO 4217 | GBP | Currency of payment |
| reference | string | Max 18 chars, Alphanumeric | ABC-123 | Pass a bank transfer reference, it will be visible by both a client and merchant in bank transfer history. |
| merchantPaymentId | string (Optional) | Max 50 chars, unique per payment | 123456 | Pass 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 |
| metadata | json 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. |
| paymentStatusCallback | callback 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. | |
| componentViewTypeCallback | callback 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 (
<>
...
<Volume
amount={50}
currency={'GBP'}
reference={'Example Reference'}
merchantPaymentId={'123456'}
metadata: { // Optional, max 5000 chars after serialization
"mydata": "myvalue"
}
paymentStatusCallback={
(paymentStatus: PaymentStatusResponse) => {
console.log("I've got a new status: " + JSON.stringify(paymentStatus));
}
}
componentViewTypeCallback={
(componentViewType: ComponentViewType) => {
console.log("Component UI type is: " + componentViewType);
}
}
/>
</>
)
}metadata
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",
"batters":
{
"batter":
[
{ "id": "1001", "type": "Regular" }
]
},
}paymentStatusCallback
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",
AWAITING_AUTHORIZATION = "AWAITING_AUTHORIZATION",
AUTHORIZED = "AUTHORIZED",
PENDING = "PENDING",
COMPLETED = "COMPLETED",
FAILED = "FAILED",
UNDEFINED = "UNDEFINED"
}componentViewTypeCallback
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 {
DESKTOP = "DESKTOP",
MOBILE_NEW_CUSTOMER = "MOBILE_NEW_CUSTOMER",
MOBILE_RETURNING_CUSTOMER = "MOBILE_RETURNING_CUSTOMER"
}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
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.