Skip to content
Integrate / SDKs / Android SDK / Reference

Android SDK reference

Last updated: 14th July 2022

Our Frames for Android reference is here to help you find those hard-to-find bits of information all in one place.

You can only create charges in currencies that have been enabled for your account. Please contact your Customer Success manager if you need to process payments in additional currencies.

Required when using our pre-built UI

First, you need to make sure you declare the form in XML.

1
2
3
4
5
<com.checkout.android_sdk.PaymentForm
   android:id="@+id/checkout_card_form"
   android:layout_width="match_parent"
   android:layout_height="match_parent"
 />
Method nameDescription

setSubmitListener({your PaymentFormCallback})

The callback for the payment form's interaction outcomes.

setKey({your key})

Your public key. Make sure you use the correct key for your environment.

setEnvironment({your environment})

The setter used to decide which environment will be used. Possible values: Environment.SANDBOX or Environment.LIVE.

Required when using your own UI

Parameter/setterDescription

context

Your activity context.

environment

The setter used to decide which environment will be used.Possible values: Environment.SANDBOX or Environment.LIVE.

public key

Your public key. Make sure you use the correct key for your environment.

setTokenListener({your CheckoutAPIClient.OnTokenGenerated callback})

Your callback used to handle the tokenization outcome.

Handling 3D Secure

The module allows you to handle 3D Secure URLs within your mobile app.

When you send a 3D Secure charge request from your server, you will get back a 3D Secure URL. You can then pass the 3D Secure URL to the module to handle the verification.

Step 1: Create a callback

1
2
3
4
5
6
7
8
9
10
11
PaymentForm.On3DSFinished m3DSecureListener =
  new PaymentForm.On3DSFinished() {
    @Override
    public void onSuccess(String token) {
      // success
    }
    @Override
    public void onError(String errorMessage) {
      // fail
    }
  };

Step 2: Pass the callback to the module and handle 3D Secure

1
2
3
4
5
6
7
mPaymentForm = findViewById(R.id.checkout_card_form);
mPaymentForm.set3DSListener(m3DSecureListener); // pass the callback
mPaymentForm.handle3DS(
  'https://sandbox.checkout.com/api2/v2/3ds/acs/687805', // the 3D Secure URL
  'https://example.com/success', // the Redirection URL
  'https://example.com/fail', // the Redirection Fail URL
);

Handling Google Pay

The module allows you to handle a Google Pay token payload and retrieve a token which can be used to create a charge from your backend.

Step 1: Create a callback

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
CheckoutAPIClient.OnGooglePayTokenGenerated mGooglePayListener =
  new CheckoutAPIClient.OnGooglePayTokenGenerated() {
    @Override
    public void onTokenGenerated(GooglePayTokenisationResponse response) {
      // success
    }
    @Override
    public void onError(GooglePayTokenisationFail error) {
      // fail
    }
    @Override
    public void onNetworkError(VolleyError error) {
      // your network error
    }
  };

Step 2: Pass the callback to the module and generate the token

1
2
3
4
5
6
7
mCheckoutAPIClient = new CheckoutAPIClient(
  context, // activity context
  'pk_XXXXX', // your public key
  Environment.SANDBOX, // the environment
);
mCheckoutAPIClient.setGooglePayListener(mGooglePayListener); // pass the callback
mCheckoutAPIClient.generateGooglePayToken(payload); // the payload is the JSON string generated by GooglePay

Payment form methods

Method nameDescription

setSubmitListener({a PaymentFormCallback)}

Set the callback for the payment form.

setEnvironment({an Environment})

Set the environment to be used.

setKey({your public key})

Set the public key to be used in the tokenization process.

setAcceptedCard({array of CardUtils.Cards})

Set all the card schemes that you want to accept. This will determine which logos to display.

setDefaultBillingCountry({a Locale country})

This will automatically set the country drop-down to be your desired locale.

handle3DS({string url, final String successUrl, final String FailsUrl})

Used to handle 3DS URLs.

set3DSListener({an On3DSFinished handler})

Set the 3DS handler.

includeBilling({a BillingModel})

In case you already collected the customer's billing details, you can inject them here so they don't have to enter them again.

injectPhone({a phoneModel})

In case you already collected the customer's phone details, you can inject them here so they don't have to enter them again.

injectCardHolderName({string})

In case you already collected the customer's name, you can inject it here so they don't have to enter it again.

clearForm()

Clears the payment form.

setFormListener({a PaymentFormCallback})

Sets a callback for when the form is submitted.

CardTokenisationResponse Object

All the properties have getters.

PropertyType

type

String

token

String

expires_on

String

expiry_month

Integer

expiry_year

Integer

scheme

String

last4

String

bin

String

card_type

String

card_category

String

issuer

String

issuer_country

String

product_id

String

product_type

String

billing_address

BillingModel

phone

PhoneModel

name

String

CardTokenisationFail Object

All the properties have getters.

PropertyType

request_id

String

error_type

String

error_code

String[]

On this page

Required when using our pre-built UI
Required when using your own UI
Handling 3D Secure
Handling Google Pay
Payment form methods
CardTokenisationResponse Object
CardTokenisationFail Object