API Reference

Our reference library for integrating with our API


Find answers to our most frequently asked questions

Classic Docs

Documentation for our Classic API

Frames for Android

Start accepting online payments in just a few minutes with Frames for Android. It's quick and easy to integrate, accepts online payments from all major credit cards, and is customizable to your brand.

Minimum requirements

In order to use Frames for Android, you must be on at least version 5.0 (API 21) of the SDK.

Frames for Android is released under the MIT license.

How it works

  1. You either embed our own customizable UI in your mobile app or, if you want full flexibility, you can build your own payment form and use Frames for Android in a headless mode.
  2. Frames for Android is then used to take your customer's sensitive information and exchange them for a secure token. This process is called tokenization. Once you have the card token, you're ready to make the payment request.

Demo (our pre-built UI)

Integrate Frames for Android

Before you start

Make sure you have your public_key. You can find it in the Hub, under Settings > Channels. If you don't have an account with us yet, you can request a free test one.

Step 1: Add the dependence repository

// project gradle file
allprojects {
 repositories {
  maven { url '' }

Step 2: Add Frames and its dependencies in gradle

// module gradle file
dependencies {
    implementation 'com.checkout:frames-android:3.0.1'

If you're using the Frames SDK with the deprecated Android Support Library, follow these steps.

Learn more about gradle files.

Step 3: Decide whether or not to use our pre-built UI

The usage guidelines vary slightly depending on your choice:

Usage (with the module's UI)

Step 1: Add the module to your XML layout


Step 2: Include the module in your class

private PaymentForm mPaymentForm; // include the payment form

Step 3: Create a callback for the payment form

PaymentFormCallback mFormListener = new PaymentFormCallback() {
  public void onFormSubmit() {
    // form submit initiated; you can potentially display a loader 
  public void onTokenGenerated(CardTokenisationResponse response) {
    // your token is here
    mPaymentForm.clearForm(); // this clears the Payment Form
  public void onError(CardTokenisationFail response) {
    // token request error
  public void onNetworkError(NetworkError error) {
    // network error
  public void onBackPressed() {
    // the user decided to leave the payment page
    mPaymentForm.clearForm(); // this clears the Payment Form

Step 4: Initialize the module

// initialise the payment from 
  mPaymentForm = findViewById(;
    .setSubmitListener(mSubmitListener)    // set the callback
    .setEnvironment(Environment.SANDBOX)   // set the environemnt
    .setKey("pk_xxx");                     // set your public key 

Usage (without the module's UI)

Step 1: Include the module in your class

private CheckoutAPIClient mCheckoutAPIClient; // include the module

Step 2: Create a callback

CheckoutAPIClient.OnTokenGenerated mTokenListener = new CheckoutAPIClient.OnTokenGenerated() {
  public void onTokenGenerated(CardTokenisationResponse token) {
    // your token
  public void onError(CardTokenisationFail error) {
    // your error
  public void onNetworkError(NetworkError error) {
    // your network error

Step 3: Initialize the module and pass the card details

mCheckoutAPIClient = new CheckoutAPIClient(
  this,                // context
  "pk_XXXXX",          // your public key
  Environment.SANDBOX  // the environment
mCheckoutAPIClient.setTokenListener(mTokenListener); // pass the callback
   // Pass the payload and generate the token
     new CardTokenisationRequest(
       new BillingModel(
         "address line 1",
         "address line 2",
         new PhoneModel(

Makes Frames for Android your own


Although we kept our demo simple, you have a lot of control over the appearance of your form—from the colors and styling, to whether you want to display one input field or several. Check out our Customization guide for more details and examples.

Configuration options

You'll find a list of all the possible configuration options in our Frames for Android reference.

Next steps

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