Quick Start
Let's get started with Volume in less than 5 minutes.
React Native component for Volume is a thin wrapper that allows you to display Volume Transparent checkout and start accepting payments from your customers in zero time into any React Native app.
Getting Started
Get started by installing the required dependencies:
npm install @getvolume/react-native react-native-mmkv
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.
export default function App() {
return (
<VolumeProvider
applicationId="123456789"
volumeEnvironment="sandbox"
onEvent={handleEvent}
>
<App />
</VolumeProvider>
)
}
Props
Full reference documentation on the VolumeProvider props can be found here: VolumeProvider
Expand the section below for a quick glance at what you need to know.
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 | Environement 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 | function | Events | Event handler function, see Events for detailed instructions on how this works |
debug | DebugConfig | Debugging | Outlines configuration for additional debugging features the Volume component offers, see Debugging for full details |
showWebBanks | boolean | true | In addition to the banks installed on the device, with this flag set to true , modelo-sandbox and natwest-sandbox are available for selction. Paying with these banks will redirect to the in device browser. |
featureFlags | FeatureFlags | {flagName:true,flag2Name:false} | Object of keys with boolean values. |
minPaymentAmount | number | 0.01 (default: 0.01) | Minimum value the amount key in paymentMeta prop of the <Volume/> component, when supplying a value smaller than this, a PAYMENT_AMOUNT_TOO_SMALL event will be emitted and the payment will not reach the volume api. |
maxPaymentAmount | number | 15000 (default: 15000) | Maximum value the amount key in paymentMeta prop of the <Volume/> component, when supplying a value larger than this, a PAYMENT_AMOUNT_TOO_LARGE event will be emitted and the payment will not reach the volume api. |
buttonText | string | Place deposit | Override the payment button text (default: "Pay with") |
buttonCustomisation | string | {headingFontSizePx:20} | Tweak the look and feel of the Volume button, properties to make changes to the colous, text, and border of the button. Each property has a typescript docstring comment to explain its output and the default value |
For more information on Events with onEvent
. Check out Events.
The Volume Button
Once you have added the VolumeProvider, all you need to do is add the Volume
component to your app!
The Volume button accepts following props:
paymentMeta provides the details for the current payment
key | type | constraints | example | description |
---|---|---|---|---|
amount | number | Min 0.01, up to 2 decimal places | 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. |
country | string | ISO 3166-1 alpha-2 | GB | Country of origin of the payment. |
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. |
onButtonEvent | function | Event handler function, see Events for detailed instructions on how this works |
buttonContainerStyles allows you to provide custom styling
Regular Style prop as passed to RN component ie
<View style={{
...
}}/>
isButtonEnabled allows you to disable Volume button based on your own
validation rules
If not provided the default value is set true
onButtonEvent callback function to handle button events
This is useful if you have multiple Volume
components in your app and you want
to handle events differently for each of them.
The callback function is passed a single object argument of the following shape
{
type: "PAYMENT_INITIATED" | "PAYMENT_AUTHORIZED_SDP" | "PAYMENT_ERROR" | "GENERIC_ERROR" | "PAYMENT_AMOUNT_TOO_SMALL" | "PAYMENT_AMOUNT_TOO_LARGE",
time: number,
meta?: {
merchantPaymentId?: string,
error?: string,
}
}
Use your IDE to explore the typescript types for the onButtonEvent
callback function.
There is a docstring comment with more detail and an example implementation, similar to the one below.
export default function Product() {
return (
<>
...
<View style={{ marginLeft: '10%' }}>
<Text style={{ fontSize: 35 }}>Mens Nike Trainers</Text>
<Text style={{ fontSize: 20 }}>Price: £50</Text>
</View>
<Image source={require('./nike-1.png')} />
<View style={{ marginTop: 'auto' }}>
<Volume
paymentMeta={{
amount: 50,
currency: 'GBP',
country: 'GB',
reference: 'Example Reference', // Generate new reference value each time PAYMENT_AUTHORIZED_SDP event is emitted
merchantPaymentId: '123456', // Generate new value each time PAYMENT_AUTHORIZED_SDP event is emitted
metadata: {
type: 'shirt',
color: 'black',
owner: {
position: 'CTO',
description: 'Very handsome man',
details: {
name: 'John',
surname: 'Doe',
},
relatedItems: [
{ itemName: 'trousers', color: 'blue' },
{ itemName: 'shoes', color: 'white' },
],
},
},
}}
onButtonEvent={(event) => {
switch (event.type) {
case 'GENERIC_ERROR':
console.log('GENERIC_ERROR: ')
// Meta does not exist
// console.log('GENERIC_ERROR: ', event.meta);
break
case 'PAYMENT_AMOUNT_TOO_LARGE':
case 'PAYMENT_AMOUNT_TOO_SMALL':
case 'PAYMENT_AUTHORIZED_SDP':
case 'PAYMENT_INITIATED':
console.log(`${event.type}: ${event.meta?.merchantPaymentId}`)
break
case 'PAYMENT_ERROR':
console.log(
`PAYMENT_ERROR: ${event.meta?.merchantPaymentId} | ${event.meta?.error}`
)
break
default:
break
}
}}
buttonContainerStyles={{ marginBottom: 50 }}
isButtonEnabled={true}
/>
</View>
</>
)
}
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" }
]
},
}
Regenerating Merchant Payment ID
Each time VolumeEvent.PAYMENT_AUTHORIZED_SDP
is emitted Merchant Payment ID should be set to a new unique value.
Implementing the after payment screen (Callback) in mobile app
Upon completion of the payment process, users are directed back from the banking app to your app using a callback via an app link or universal link.
Volume accepts only https
links, which means traditional deep links like myapp://callback are not supported.
Instead, we recommend using App Links and Universal Links, such as https://myDomain.com/callback (opens in a new tab), for their superior security, user experience, seamless integration, and web fallback capabilities.
Android:
About app links (opens in a new tab)
Create Deep Links to App Content (opens in a new tab)
iOS:
Supporting universal links in your iOS app (opens in a new tab)
Supporting associated domains on iOS (opens in a new tab)
Flutter:
Flutter app links library (opens in a new tab)
Universal links on Flutter (opens in a new tab)
React Native:
React Native linking documentation (opens in a new tab)
React Native app links tutorial (opens in a new tab)
Documentation for the Volume Callback parameters: Callback
iOS Banks detection required setup
To make bank detection work Apple require we add some values in your Info.plist to indicate intent to work with app schemes, we use this to detect which banking apps the end user has installed on their phone so that we can show them only banks they have installed.
To complete the setup there are some <string>
tags we need to add under the LSApplicationQueriesSchemes
key in Info.plist file.
<key>LSApplicationQueriesSchemes</key>
<array>
<string>BMBGB</string>
<string>revolut</string>
<string>natwestbank</string>
<string>monzo</string>
<string>santanderuk</string>
<string>rbs</string>
<string>lloyds-retail</string>
<string>ukcomhsbcmobilebanking</string>
<string>zappcfi437759</string>
<string>hsbc-pwnwguti5z</string>
<string>zapp</string>
<string>launchAIB</string>
<string>ie.aib.mobilebanking</string>
<string>BOIOneAPP</string>
<string>halifax-retail</string>
<string>starlingbank</string>
<string>tescobank</string>
<string>tsbmobile</string>
<string>sparda-app</string>
<string>bankingappspardaproduktion</string>
<string>secureappspardaproduktion</string>
<string>sapp-pushtan</string>
<string>sapp-invest</string>
<string>de.sparda.securego</string>
<string>bos-retail</string>
<string>launchbca</string>
<string>comfirstdirectbankingonthego</string>
<string>cs-com.virginmoney.uk.mobile.ios</string>
<string>transferwise</string>
<string>ybssavings</string>
<string>chase-international</string>
</array>
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.