Frames Android SDK

Our Frames 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 Frames Android SDK is available on GitHub under the MIT license. For the SDK's API information, refer to the Frames Android SDK API reference.

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 Frames SDKs in another way, you may end up needing to adhere to a higher level of compliance.

Integrate our Frames Android SDK into your application's source code.
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.
Use the secure token to make a payment request.

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

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
2allprojects {
3    repositories {
4        maven { url 'https://jitpack.io' }
5    }
6}

Add Frames SDK dependency to the module gradle file:


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


1val 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}


1private final PaymentFlowHandler mPaymentFlowHandler = new PaymentFlowHandler() {
2
3    @Override
4    public void onSubmit() {
5            // form submit initiated; you can choose to display a loader here
6    }
7
8    @Override
9    public void onSuccess(@NonNull TokenDetails tokenDetails) {
10        // your token is here
11    }
12
13    @Override
14    public void onFailure(@NonNull String errorMessage) {
15        // token request error
16    }
17
18     @Override
19    public void onBackPressed() {
20        // the user decided to leave the payment page
21    }
22};


1val 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)


1PaymentFormConfig paymentFormConfig = new PaymentFormConfig(
2        PUBLIC_KEY,                     // set your public key
3        context,                        // set context
4        Environment.SANDBOX,            // set the environment
5        paymentFlowHandler,             // set the callback
6        new PaymentFormStyle(),         // set the style
7        new ArrayList<>()               // set supported card schemes, by default uses
8);


1val paymentFormMediator = PaymentFormMediator(paymentFormConfig)


1PaymentFormMediator paymentFormMediator = new PaymentFormMediator(paymentFormConfig);


1paymentFormMediator.PaymentForm()               // Compose function


1class MainActivity : ComponentActivity() {
2
3    override fun onCreate(savedInstanceState: Bundle?) {
4        super.onCreate(savedInstanceState)
5        paymentFormMediator.setActivityContent(this)
6    }
7}


1override fun onCreateView(
2    inflater: LayoutInflater,
3    container: ViewGroup?,
4    savedInstanceState: Bundle?
5): View = paymentFormMediator.provideFragmentContent(this)


1mPaymentFormMediator.PaymentForm();               // Compose function


1public class MainActivity extends ComponentActivity {
2
3    @Override
4    protected void onCreate(Bundle savedInstanceState) {
5        super.onCreate(savedInstanceState);
6        mPaymentFormMediator.setActivityContent(this);
7    }
8}


1@Override
2public View onCreateView(
3        LayoutInflater inflater,
4        ViewGroup container,
5        Bundle savedInstanceState
6) {
7    return paymentFormMediator.provideFragmentContent(this);
8}

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

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, which allows you to modify the fonts and font colors used in the default forms
themed form styling, which allows you to apply a custom theme to the preset components
custom form styling, which allows you to build and define your own components

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 Dashboard, 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 Frames Android SDK repository.


1val 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}


1private final Function1<ThreeDSResult, Unit> threeDSResultHandler = threeDSResult -> {
2    if (threeDSResult instanceof ThreeDSResult.Success) {
3        /* Handle success result */
4        String token = ((ThreeDSResult.Success) threeDSResult).getToken();
5    } else if (threeDSResult instanceof ThreeDSResult.Error) {
6        /* Handle error result */
7        String errorMessage = ((ThreeDSResult.Error) threeDSResult).getError().getMessage();
8    } else {
9        /* Handle failure result */
10    }
11    return null;
12};


1val 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)
8paymentFormMediator.handleThreeDS(request)


1private void handleThreeDS(@NonNull String redirectUrl) {
2    ThreeDSRequest threeDSRequest = new ThreeDSRequest(
3            this.findViewById(android.R.id.content), // Provide a ViewGroup container for 3DS WebView
4            redirectUrl,                             // Provide a 3D Secure URL
5            "http://example.com/success",
6            "http://example.com/failure",
7            threeDSResultHandler
8    );
9    mPaymentFormMediator.handleThreeDS(threeDSRequest);
10}

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


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


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


1val 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)
11checkoutApiClient.createToken(request)


1private void createGooglePayToken(@NonNull String tokenJsonPayload) {
2    GooglePayTokenRequest request = new GooglePayTokenRequest(
3            tokenJsonPayload,
4            tokenDetails -> {
5                /* Handle success result */
6                tokenDetails.getToken();
7                return null;
8            },
9            errorMessage -> {
10                /* Handle failure result */
11                return null;
12            }
13    );
14    checkoutApiClient.createToken(request);
15}

Now that you have the card token, you can request a payment.

Customize the Frames Android SDK

Customize the forms used to collect payment information in your Android app.

Frames Android SDK

Information

PCI DSS compliance

How it works

Integrate with our Frames Android SDK

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

Information

Step 2: Create a callback for the Payment flow

Step 3: Create a configuration object for your Payment form

Step 4: Create a Payment mediator

Step 5: Get and show Payment form

Step 6: (Optional) Customize your payment forms

Handle 3D Secure

Create 3DS result handler

Handle 3DS

Handle GooglePay

Create CheckoutApiService

Create a token for GooglePay

Related topics

Customize the Frames Android SDK