Skip to content

Android SDK

Last updated: December 21, 2022

Our Android SDK allows you to accept online payments from all major credit cards and offers multiple levels of customization to suit your requirements.

Information

Our Android SDK is provided under the MIT license.


PCI DSS compliance

We stay up-to-date with the latest Payment Card Industry Data Security Standards (PCI DSS). Read our PCI compliance documentation to learn how we can help you to be compliant.

Based on these standards, we advise you to use one of our UI-based solutions of the Frames SDKs to remain at the lowest level of compliance (SAQ-A).

If you build your own UI, or use the SDKs in another way, you may end up needing to adhere to a higher level of compliance.


How it works

  1. Integrate our Android SDK into your application's source code.
  2. Display the payment forms we provide to collect your customer's payment information and exchange this for a secure token. This is the tokenization step.
  3. Use the secure token to make a payment request.
android

Integrate with our Android SDK

To integrate with our Android SDK, you must be using Android API level 21 or above.

Step 1: Add the SDK to your application's source code

Information

You can find more about the installation and available versions on jitpack.io/frames-android.

Add JitPack repository to the project level build.gradle file:

1
// project gradle file
2
allprojects {
3
repositories {
4
maven { url 'https://jitpack.io' }
5
}
6
}

Add Frames SDK dependency to the module gradle file:

1
// module gradle file
2
dependencies {
3
implementation 'com.github.checkout:frames-android:<latest_version>'
4
}

Step 2: Create a callback for the Payment flow

    1
    val paymentFlowHandler = object : PaymentFlowHandler {
    2
    override fun onSubmit() {
    3
    // form submit initiated; you can choose to display a loader here
    4
    }
    5
    6
    override fun onSuccess(tokenDetails: TokenDetails) {
    7
    // your token is here
    8
    }
    9
    10
    override fun onFailure(errorMessage: String) {
    11
    // token request error
    12
    }
    13
    14
    override fun onBackPressed() {
    15
    // the user decided to leave the payment page
    16
    }
    17
    }

    Step 3: Create a configuration object for your Payment form

      1
      val paymentFormConfig = PaymentFormConfig(
      2
      publicKey = PUBLIC_KEY, // set your public key
      3
      context = context, // set context
      4
      environment = Environment.SANDBOX, // set the environment
      5
      paymentFlowHandler = paymentFlowHandler, // set the callback
      6
      style = PaymentFormStyle(), // set the style
      7
      supportedCardSchemeList = emptyList() // set supported card schemes, by default uses all schemes
      8
      )

      Step 4: Create a Payment mediator

        1
        val paymentFormMediator = PaymentFormMediator(paymentFormConfig)

        Step 5: Get and show Payment form

            1
            paymentFormMediator.PaymentForm() // Compose function

            Step 6: (Optional) Customize your payment forms

            If you want to change the styling of the forms displayed to the customer, you can do so using the PaymentDetailsStyle, BillingAddressDetailsStyle and CountryPickerStyle.

            The default payment form

            The default billing form

            The default country picker

            You can choose between three different options for customization, depending on how much control you need over the forms' UI design. In order of increasing complexity these are:

            • Default form styling: use the default forms with custom fonts and font colors.
            • Themed form styling: use our themed option to apply a custom theme to the components displayed, for greater control over the look of your forms.
            • Custom form styling: use our fully custom option to build and define your own components to display across the forms.

            Handle 3D Secure

            When you send a 3D Secure charge request from your server, you will receive a 3D Secure URL in the response's _links.redirect.href field. You can pass this URL to a PaymentFormMediator in order to handle verification.

            The redirection URLs, success_url and failure_url, are set in the Hub, but they can be overwritten in the charge request sent from your server. It's important that you provide the correct URLs to ensure a successful payment flow.

            You can find an example of handling 3DS in the DemoActivity.java file from the Android SDK repository.

            Create 3DS result handler

              1
              val threeDSResultHandler: ThreeDSResultHandler = { threeDSResult: ThreeDSResult ->
              2
              when (threeDSResult) {
              3
              is ThreeDSResult.Success -> {
              4
              /* Handle success result */
              5
              threeDSResult.token
              6
              }
              7
              is ThreeDSResult.Failure -> {
              8
              /* Handle failure result */
              9
              }
              10
              is ThreeDSResult.Error -> {
              11
              /* Handle error result */
              12
              threeDSResult.error
              13
              }
              14
              }
              15
              }

              Handle 3DS

                1
                val request = ThreeDSRequest(
                2
                container = findViewById(android.R.id.content), // Provide a ViewGroup container for 3DS WebView
                3
                challengeUrl = redirectUrl, // Provide a 3D Secure URL
                4
                successUrl = "http://example.com/success",
                5
                failureUrl = "http://example.com/failure",
                6
                resultHandler = threeDSResultHandler
                7
                )
                8
                paymentFormMediator.handleThreeDS(request)

                Handle GooglePay

                Handle a Google Pay token payload and retrieve a token, that you can use to create a charge from your backend.

                Create CheckoutApiService

                  1
                  val checkoutApiClient = CheckoutApiServiceFactory.create(
                  2
                  publicKey = PUBLIC_KEY, // set your public key
                  3
                  environment = Environment.SANDBOX, // set context
                  4
                  context = context // set the environment
                  5
                  )

                  Create a token for GooglePay

                    1
                    val request = GooglePayTokenRequest(
                    2
                    tokenJsonPayload = tokenJsonPayload,
                    3
                    onSuccess = { tokenDetails ->
                    4
                    /* Handle success result */
                    5
                    tokenDetails.token
                    6
                    },
                    7
                    onFailure = { errorMessage ->
                    8
                    /* Handle failure result */
                    9
                    }
                    10
                    )
                    11
                    checkoutApiClient.createToken(request)

                    Next steps

                    Now that you've got your card token, you're ready to request a card payment.