Accept payments on your Android app

Last updated: March 12, 2025

Information

We are not onboarding new merchants to Frames.

Upgrade to Flow instead, our pre-built, customizable payment user interface. Flow provides a more flexible, scalable, and feature-rich integration.

If you've integrated the Frames Android SDK to your Android app, you can tokenize a customer's payment details or Card Verification Value (CVV) to use in a payment request.

Create a callback for the payment flow:


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};

Create a new configuration for the payment form:


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);

Create a new PaymentFormMediator object:


1val paymentFormMediator = PaymentFormMediator(paymentFormConfig)


1PaymentFormMediator paymentFormMediator = new PaymentFormMediator(paymentFormConfig);

Display the payment form with the PaymentForm() method exposed by PaymentFormMediator:


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}

Information

You can customize the forms used to collect customers' payment details.

Create a CheckoutApiServiceFactory object:


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);

Create a token for Google Pay:


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}

When the customer submits the required payment forms, the payment details are sent directly to Checkout.com's servers and tokenized. The tokenized payment details are then sent back to you, for you to use in a payment request.

Information

Checkout.com is fully compliant with the Payment Card Industry Data Security Standards (PCI DSS). If you use one of our UI-based solutions, you are subject to a lower level of PCI compliance (SAQ A).

To request a payment, call the following endpoint from your back end:

post

https://api.checkout.com/payments

For the full API specification, see the API reference.


1{
2  "source": {
3    "type": "token",
4    "token": "tok_4gzeau5o2uqubbk6fufs3m7p54"
5  },
6  "amount": 100,
7  "currency": "USD",
8  "processing_channel_id": "pc_ovo75iz4hdyudnx6tu74mum3fq",
9  "reference": "ORD-5023-4E89",
10  "metadata": {
11    "udf1": "TEST123",
12    "coupon_code": "NY2023",
13    "partner_id": 123989
14  }
15}


1{
2  "id": "pay_mbabizu24mvu3mela5njyhpit4",
3  "action_id": "act_mbabizu24mvu3mela5njyhpit4",
4  "amount": 100,
5  "currency": "USD",
6  "approved": true,
7  "status": "Authorized",
8  "auth_code": "770687",
9  "response_code": "10000",
10  "response_summary": "Approved",
11  "3ds": {
12    "downgraded": true,
13    "enrolled": "N"
14  },
15  "risk": {
16    "flagged": true
17  },
18  "source": {
19    "type": "card",
20    "id": "src_nwd3m4in3hkuddfpjsaevunhdy",
21    "billing_address": {
22      "address_line1": "123 Anywhere St.",
23      "address_line2": "Apt. 456",
24      "city": "Anytown",
25      "state": "AL",
26      "zip": "123456",
27      "country": "US"
28    },
29    "phone": {
30      "country_code": "+1",
31      "number": "555 123 4567"
32    },
33    "last4": "4242",
34    "fingerprint": "F31828E2BDABAE63EB694903825CDD36041CC6ED461440B81415895855502832",
35    "bin": "424242"
36  },
37  "customer": {
38    "id": "cus_udst2tfldj6upmye2reztkmm4i",
39    "email": "[email protected]",
40    "name": "John Smith"
41  },
42  "processed_on": "2024-09-10T10:11:12Z",
43  "reference": "ORD-5023-4E89",
44  "processing": {
45    "retrieval_reference_number": "909913440644",
46    "acquirer_transaction_id": "440644309099499894406"
47  },
48  "eci": "06",
49  "scheme_id": "489341065491658",
50  "links": {
51    "self": {
52      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
53    },
54    "action": {
55      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions"
56    },
57    "void": {
58      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/voids"
59    },
60    "capture": {
61      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/captures"
62    }
63  }
64}

When you send a 3D Secure charge request from your server, you 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.

Information

You can use the 3D Secure mobile SDKs to handle 3DS challenges natively instead.

The redirect 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 DemoActivity.java from the SDK's project files.

Create 3DS result handler:


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};

Configure the 3DS request:


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}

Some regions require you to send a Card Verification Value (CVV) when you perform a payment with a stored card.

To remain at PCI compliance level SAQ-A, you can use the SDK's CVV component to securely tokenize a CVV.

The CVV token is returned to your application layer, so that you can submit it when you perform a payment request from your back end.

To start, initialize the CVV component:


1// Create a one-time cvvComponentApi instance
2val cvvComponentApi = CVVComponentApiFactory.create(
3    publicKey = "<PUBLIC_KEY>",               
4    environment = Environment.SANDBOX,       
5    context = context                        
6)


1// Create a one-time cvvComponentApi instance
2CVVComponentApi cvvComponentApi = CVVComponentApiFactory.create(
3    "<PUBLIC_KEY>",
4    Environment.SANDBOX,
5    context
6);

Create an instance of CVVComponentConfig. Use this object to configure the parameters for the CVV component.

You can set a card scheme for the component using the optional CardScheme parameter. If you do so, the SDK can validate that the CVV submitted by the customer is in a valid format for the given card scheme via isEnteredCVVValid.

If you do not explicitly set a card scheme, the scheme defaults to UNKNOWN. You receive an error at the API level if the CVV is invalid.

If the user submits an empty field as the security code, the SDK throws a validation error when you call createToken(), regardless of the card scheme you specified.

Information

For a list of valid scheme name string values, refer to your back end.

To customize the UI, specify a cvvComponentStyle within CVVComponentConfig. You can use any of the styling attributes exposed by the SDK.


1val cvvComponentConfig = CVVComponentConfig(
2    cardScheme = CardScheme.fromString(cardSchemeValue = "<CARD_SCHEME>"),  // set an optional card scheme
3    onCVVValueChange = { isEnteredCVVValid ->    // update your listener from the onCVVValueChange 
4      enteredVisaCVVUpdated.value = isEnteredCVVValid
5    },
6    cvvInputFieldStyle = inputFieldStyle,    // set your cvvInputFieldStyle
7)


1CVVComponentConfig cvvComponentConfig = new CVVComponentConfig(
2        CardScheme.Companion.fromString("visa"), // set an optional card scheme
3        isEnteredCVVValid -> Unit.INSTANCE, 
4        DefaultCVVInputFieldStyle.INSTANCE.create()
5);

You can then instantiate the cvvComponentMediator using your configuration:


1val cvvComponentMediator = cvvComponentApi.createComponentMediator(cvvComponentConfig)


1CVVComponentMediator cvvComponentMediator = cvvComponentApi.createComponentMediator(cvvComponentConfig);

Use the cvvComponentMediator object to load the CVV component:


1cvvComponentMediator.CVVComponent()


1cvvComponentMediator.CVVComponent();


1// Access the LinearLayout by its Resource ID
2val linearLayout = findViewById<LinearLayout>(R.id.linearLayout)
3
4// Get the cvvComponentView 
5val cvvComponentView = cvvComponentMediator.provideCvvComponentContent(linearLayout)
6
7// Add the cvvComponentView to parent Layout
8linearLayout.addView(cvvComponentView)


1// Access the LinearLayout by its Resource ID
2LinearLayout linearLayout = findViewById(R.id.linearLayout);
3
4// Get the cvvComponentView
5View cvvComponentView = cvvComponentMediator.provideCvvComponentContent(linearLayout);
6
7// Add the cvvComponentView to the parent Layout
8linearLayout.addView(cvvComponentView);

Use the cvvComponentMediator object to create a token:


1cvvComponentMediator.createToken { result ->
2  when (result) {
3    is CVVTokenizationResultHandler.Success -> {
4      result.tokenDetails // Handle success result
5    }
6    is CVVTokenizationResultHandler.Failure -> {
7      result.errorMessage // Handle failure result
8    } 
9  }
10}


1cvvComponentMediator.createToken(result -> {
2  if (result instanceof CVVTokenizationResultHandler.Success) {
3    // Tokenization was successful
4    CVVTokenDetails tokenDetails = ((CVVTokenizationResultHandler.Success) result).getTokenDetails();
5
6    // Get token
7    tokenDetails.getToken()      
8    } else if (result instanceof CVVTokenizationResultHandler.Failure) {
9      // Tokenization failed
10      String errorMessage = ((CVVTokenizationResultHandler.Failure) result).getErrorMessage();
11    } 
12  return Unit.INSTANCE;
13});

You can then request a payment using the tokenized security code.

Accept payments on your Android app

Information

Configure the payment handler

Configure the payment form

Display the payment form

Information

Handle Google Pay

Use the token to request a payment

Information

Request example

Response example

Handle 3D Secure

Information

Tokenize a CVV

Initialize the CVV component

Configure the CVV component

Information

Load the CVV component

Create a CVV token