Quick Start

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

iOS xcframework for Volume is a library with custom view that allows you to display Volume checkout and start accepting payments from your customers in zero time into any iOS app.

Getting Started

Get started by installing VolumeComponent xcframework.

via Cocoapod

   platform :ios, '14.0'
    source ''
    source 'https://' + ENV['GIT_AUTHORIZATION'] + ''
    target 'SampleApp' do
      pod 'Alamofire'
      pod 'VolumePayComponent', '2.0.0'

Where GIT_AUTHORIZATION is environment variable made of github user and it's token volume-public:<token> in that manner. Token is provided by Volume.

e.g. volume-public:github_pat_72A4HWM8I0LwB3_T0kenProv1dedByV0lume__V3o9ZRvFBM5cmENW8vf8ES365KNJ7b6u7gY1

The best way to do this is to export shell variable as:

   export GIT_AUTHORIZATION=volume-public:github_pat_72A4HWM8I0LwB3_T0kenProv1dedByV0lume__V3o9ZRvFBM5cmENW8vf8ES365KNJ7b6u7gY1

this will work only in your current terminal session if you prefer more permanent solution please consider adding this command to your .bashrc or .zshrc.

If you will encounter Cocoapod bug with runtime error: RuntimeError - [Xcodeproj] Unknown object version (56). the solution is described in stackoverflow (opens in a new tab)

Volume Provider & Volume Button

The volume provider should be placed at the root level of your application, this provides key global configuration for using volume in your application. When VolumeProvider is initialized then you can add Volume button to your screen by adding VolumeButtonComponent to ExampleAppView struct.

import VolumePayComponent
struct ExampleApp: App {
    init() {
        do {
            try volumeProvider.initialize(
                    volumeSetup: VolumeSetup(
                            applicationId: "", //provided by Volume
                            volumeEnvironment: "sandbox",
                            volumeEventListener: DefaultVolumeEventListener { message in
                            showSandboxBanks: true,
                            maxPaymentAmount: 15000,
                            minPaymentAmount: 1,
                            volumeTranslations: [ // Optional parameter
                                "DE": VolumeTranslations(buttonText: "Bezahlen mit",
                                        headingText: "Bezahlen Sie mit Ihrer Banking-App",
                                        modalTitleText: "Bank-App auswählen",
                                        modalSubtitleText: "Ihre Zahlung ist durch die Sicherheit Ihrer Bank geschützt",
                                        moreBanksText: "+ mehr",
                                        selectBankButtonText: "Wählen Sie zum Bezahlen die Bank-App aus",
                                        payerDetailsText: "Bitte geben Sie Ihre Daten ein:",
                                        accountHolderNameText: "Vorname und Nachname",
                                        ibanText: "IBAN",
                                        continueInBankText: "Weiter in der Bank-App")
        } catch {
    class DefaultVolumeEventListener: VolumeEventListener {
        let showEvent: (String) -> ()?
        init(showToast: @escaping (String) -> ()?) {
            showEvent = showToast
        func onEvent(event: VolumeEvent) {
    var body: some Scene {
        WindowGroup {
 struct ExampleAppView: View {
    @State private var currency: String = "EUR"
    @State private var country: String = "DE"
    @State private var language: LanguageCode = "EN"
    @State private var merchantPaymentId: String = generateMerchantPaymentId()
    var body: some View {
        let volumeButtonEventListener: VolumeEventListener = DefaultVolumeButtonEventListener { event in
            switch event {
            case .navigateToPaymentConsent:
                self.merchantPaymentId = generateMerchantPaymentId()
            default: break
        return VStack {
                    amount: 0.1,
                    reference: "Example Reference", // Generate new reference value each time navigateToPaymentConsent event is emitted
                    currency: $currency,
                    country: $country,
                    merchantPaymentId: merchantPaymentId, // Generate new value each time navigateToPaymentConsent event is emitted
                    isEnabled: true,
                    language: $language // Optional parameter
                    volumeButtonEventListener: volumeButtonEventListener,
                    metadata: [
                         "type": "shirt",
                         "color": "black",
                         "owner": [
                             "position": "CTO",
                             "description": "A tall guy",
                             "details": [
                                 "name": "John",
                                 "surname": "Doe",
                         "relatedItems": [
                             [ "itemName": "trousers", "color": "blue"],
                             [ "itemName": "shoes", "color": "white"],
                    .padding(.horizontal, 15.0)
                    .padding(.vertical, 50)
func generateMerchantPaymentId() -> String {
    "This should be unique value" //TODO Get merchant Payment Id value from backend
class DefaultVolumeButtonEventListener: VolumeEventListener {
    let onEvent: (VolumeEvent) -> ()?
    init(onEventAction: @escaping (VolumeEvent) -> ()?) {
        onEvent = onEventAction
    func onEvent(event: VolumeEvent) {


Expand the section below for a quick glance at what you need to know.

VolumeProvider properties

Required Properties

applicationIdString123456789Your Application Id as provided in your Merchant Portal. (Provided by Volume)
volumeEnvironmentStringsandboxEnvironment to be used, this is either 'live' | 'sandbox' | A full URI if we have provided a specific environment for you.

Optional Properties

onEventVolumeEventListenerEventsEvent listener, object that reacts to Volume events, see Events for detailed instructions on how this works
showSandboxBanksBooleantrueFlag to enable showing sandbox banks. Used for testing
minPaymentAmountDecimal0.01 (default: 0.01)Minimum value for the amount field for each payment, 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.
maxPaymentAmountDecimal15000 (default: 15000)Maximum value for the amount field for each payment, when supplying a value greater than this, a PAYMENT_AMOUNT_TOO_LARGE event will be emitted and the payment will not reach the volume api.
buttonCustomisationButtonCustomisationTweak the look and feel of the Volume button, properties to make changes to the colours, text, and border of the button.
volumeTranslations[String: VolumeTranslations]Map of VolumeTranslations per language like "EN" or "DE". Allows to translate Volume component.

For more information on Events with onEvent. Check out Events.

VolumePaymentView has following setters
amountDecimalMin 0.01 , up to 2 decimal places1Amount to be paid, ie £1.00.
currencyStringISO 4217GBPCurrency of payment
countryStringISO 3166-1 alpha-2GBCountry of origin of the 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
isEnabledBooleantrueChanges the Enabled/Disabled state of the Volume button
languageStringENSets the language to be used on Volume component
volumeButtonEventListenerVolumeEventListenerEvent listener, object that reacts to Volume events, see Events for detailed instructions on how this works
metadataDictionary String to AnyMax 5000 chars lengthmetadata is an optional JSON object which will be passed back in webhooks as paymentMetadata. It can only accepts primitives (as well as dictionaries and arrays of primitives).
paymentIdentifiersProviderPaymentIdentifiersProviderOptionalProvider for PaymentIdentifiers like MerchantPaymentId and Reference that are generatedPaymentIdentifiers on Merchant backend

Regenerating Merchant Payment ID

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

Rendering Volume Button without MerchantPaymentId (Optional)

The PaymentIdentifiersProvider is an optional feature that allows merchants to provide a MerchantPaymentId and Reference fields when the user clicks the Volume Pay button. This enables the rendering of the Volume Button before creating a Payment entity on the merchant side. providePaymentIdentifiers(): An asynchronous method that returns a PaymentIdentifiers object containing the payment identifiers.

class VolumePaymentIdentifiersProvider: PaymentIdentifiersProvider {
    func providePaymentIdentifiers() async throws -> PaymentIdentifiers {
        // Get MerchantPaymentId and Reference from the backend
        let merchantPaymentId = generateMerchantPaymentId()
        let reference = generateReference()
        return PaymentIdentifiers(merchantPaymentId: merchantPaymentId, reference: reference)
// Usage in the VolumePaymentButtonView
        amount: 0.1,
        reference: "Example Reference", // will be overridden by paymentIdentifiersProvider
        currency: $currency,
        country: $country,
        merchantPaymentId: merchantPaymentId, // will be overridden by paymentIdentifiersProvider
        isEnabled: true,
        language: $language // Optional parameter
        volumeButtonEventListener: volumeButtonEventListener,
        paymentIdentifiersProvider: VolumePaymentIdentifiersProvider()

❗When paymentIdentifiersProvider is provided then merchantPaymentId and reference fields values will be ignored and paymentIdentifiersProvider will be called each time user clicks on the Volume Button.

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 (opens in a new tab), for their superior security, user experience, seamless integration, and web fallback capabilities.


About app links (opens in a new tab)

Create Deep Links to App Content (opens in a new tab)


Supporting universal links in your iOS app (opens in a new tab)

Supporting associated domains on iOS (opens in a new tab)


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.



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.