Quick Start

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

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

Getting Started

Get started by installing Volume Android SDK.

    repositories {
        maven {
            name = "GitHubPackages"
            url = uri("https://maven.pkg.github.com/getvolume/volume-android-sdk")
            credentials {
                username volume-public
                password // Token provided by Volume
            }
        }
    }

Add dependency to volume-android-sdk (Ask Volume team for the latest version number)

dependencies {
    implementation "com.volume.sdk:volume-android-sdk:1.2.0"
}

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.

class SampleApplication : Application() {
    override fun onCreate() {
        super.onCreate()
 
        VolumeProvider.init(
            volumeSetup = VolumeSetup(
                applicationId = "", // Provided by Volume
                volumeEnvironment = "sandbox",
                onEvent = { Timber.v("[Sample App Volume] On Event: $it") }, // Your own event listener
                logger = logger, // Your own logger implementation
                showSandboxBanks = true,
                maxPaymentAmount = 150.toBigDecimal(),
                minPaymentAmount = 0.01.toBigDecimal(),
                buttonCustomisation = ButtonCustomisation(),
                translations = mapOf(
                    "EN" to VolumeTranslations(accountHolderNameText = "Name and Surname"),
                    "DE" to VolumeTranslations(accountHolderNameText = "Name und Nachname")
                ),
                language = "EN",
            ),
            app = this
        )
        VolumeProvider.setLanguage("DE") // Use this to change language in runtime
    }
}

Properties

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

VolumeProvider properties

Required Properties

key	type	example	description
applicationId	String	123456789	Your Application Id as provided in your Merchant Portal. (Provided by Volume)
volumeEnvironment	String	sandbox	Environment to be used, this is either 'live' \| 'sandbox' \| A full URI if we have provided a specific environment for you.

Optional Properties

key	type	example	description
onEvent	VolumeEventListener	Events	Event listener, object that reacts to Volume events, see Events for detailed instructions on how this works
logger	Logger	Timber or Android.log wrapper	Logger implementation to log Volume information, if not set then no-op implementation is used
showSandboxBanks	Boolean	true	Flag to enable showing sandbox banks. Used for testing
minPaymentAmount	BigDecimal	0.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.
maxPaymentAmount	BigDecimal	15000 (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.
buttonCustomisation	ButtonCustomisation		Tweak the look and feel of the Volume button, properties to make changes to the colours, text, and border of the button.
translations	Map String to VolumeTranslations		Map of VolumeTranslations per language like "EN" or "DE". Allows to translate Volume component.
language	String		Sets the language to be used on Volume component.

💡

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

The Volume Button

When VolumeProvider is initialized then you can add Volume button to your screen by adding VolumePaymentButtonView View:

    <com.volume.sdk.payment.VolumePaymentButtonView
        android:id="@+id/volumePaymentView"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_marginTop="16dp"
        app:layout_constraintTop_toBottomOf="@id/volume_toggle" />

Then you can set the properties from your Activity/Fragment code

        binding.volumePaymentView.setAmount("1".toBigDecimal())
        binding.volumePaymentView.setReference("Example Reference") // Generate new reference value each time navigateToPaymentConsent event is emitted
        generateAndSetMerchantPaymentId()
        binding.volumePaymentView.setCurrency("GBP")
        binding.contentMain.volumePaymentView.setOnButtonEvent {
            when (it) {
                is VolumeEvent.NavigateToPaymentConsent -> {
                    generateAndSetMerchantPaymentId()
                }
                else -> {}
            }
        }
 
        binding.contentMain.volumePaymentView.setMetadata(
            mapOf(
                "type" to "shirt",
                "color" to "black",
                "owner" to mapOf(
                    "position" to "CTO",
                    "description" to "A tall guy",
                    "details" to mapOf(
                        "name" to "John",
                        "surname" to "Doe",
                    ),
                    "relatedItems" to listOf(
                        mapOf(
                            "itemName" to "trousers",
                            "color" to "blue",
                        ),
                        mapOf(
                            "itemName" to "shoes",
                            "color" to "white",
                        ),
                    )
                ),
            )
        )
 
        private fun generateAndSetMerchantPaymentId() {
            val merchantPaymentId = "This should be unique value" //TODO Get merchant Payment Id value from backend
 
            binding.contentMain.merchantPaymentId.setText(merchantPaymentId)
        }

VolumePaymentView has following setters

key	type	constraints	example	description
onEvent	VolumeEventListener			Event listener, object that reacts to Volume events, see Events for detailed instructions on how this works
setAmount	BigDecimal	Min 0.01	1	Amount to be paid, ie £1.00.
setCurrency	String	ISO 4217	GBP	Currency of payment
setReference	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.
setMerchantPaymentId	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
setEnabled	Boolean		true	Changes the Enabled/Disabled state of the Volume button
metadata	Map String to Any?			metadata is an optional data which will be passed back in webhooks as paymentMetadata.

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 Result<PaymentIdentifiers> object containing the payment identifiers.

class VolumePaymentIdentifiersProvider : PaymentIdentifiersProvider {
    override suspend fun providePaymentIdentifiers(): PaymentIdentifiers {
        val merchantPaymentId = generateMerchantPaymentId()
        val reference = generateReference()
        val generatedPaymentIdentifiers = // Get MerchantPaymentId and Reference from the backend
        return PaymentIdentifiers(merchantPaymentId = generatedPaymentIdentifiers.merchantPaymentId, reference = generatedPaymentIdentifiers.reference)
    }
}
 
// Usage in the VolumePaymentButtonView
binding.contentMain.volumePaymentView.setPaymentIdentifiersProvider(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 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

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.

Events