Android


Generate a Client Token

Get an API Key

You require an API Key to talk with our APIs. Head to the Developers area to manage your API keys.

When your account is created, we will also create an API token automatically. You can use this API key to get started.

Never share your API Key, only your backend should have access to it.

Find out more about API Keys in our API Reference

Generate a Client Session

client token A client session is the starting point for integrating payments at Primer. You can attach all the metadata associated with the order to the client session, and generate a clientToken, a temporary key used to initialize Universal Checkout.

The information you include in the client session is used in the Dashboard to conditionally route payments with Workflows, and activate payment methods and other features in Universal Checkout, so pass as much information as you can.

The X-Api-Version specifies the API version information. Earlier, this was supposed to be a date. For example, 2021-10-19. This has changed post API version v2 which was represented by 2021-09-27 date. Starting API version v2.1, the X-Api-Version needs to provide the API version as v2.1. Depending upon the API version specified in the client-session request, your client-session will be processed accordingly with requisite features and options that are available for that version.

See API Reference Changelog for details.

Here is how the client session request to the Primer API should look like:

POST/client-session
12345678910111213
# Generate a client token with cURLcurl --location --request \  POST 'https://api.sandbox.primer.io/client-session' \  --header 'X-Api-Key: <YOUR_API_KEY>' \  --header 'X-Api-Version: 2021-10-19' \  --header 'Content-Type: application/json'  --data '{    "orderId": "<YOUR_ORDER_ID>",    "currencyCode": "GBP",    "amount": 1200,    "customerId": "<YOUR_CUSTOMER_ID>"    "order": { "countryCode": "GB" }  }'
curl
copy

Example Response

12345678910
{  "clientToken": "<THE_CLIENT_TOKEN>",  "clientTokenExpirationDate": "2021-08-12T16:14:08.578695",  "orderId": "<YOUR_ORDER_ID>",  "currencyCode": "GBP",  "amount": 1200,  "customerId": "<YOUR_CUSTOMER_ID>",  "metadata": {},  "warnings": []}
JSON
copy
ℹ️
Make sure to pass all the information required by the payment methods and features activated on your Dashboard.

As a rule of thumb, pass as much information as you can when creating the client session. As a minimum, make sure to pass:

  • orderId
  • currencyCode
  • amount
  • order.countryCode

The clientToken is a key concept within Primer. You may receive a client token from various places but as long as you pass it to the SDK, Universal Checkout knows where to start/resume the flow.

Set up the Universal Checkout

Step 1. Install SDK

Add the following to your app/build.gradle file

1234567
repositories {  mavenCentral()} dependencies {  implementation 'io.primer:android:latest.version'}
kotlin
copy

For more details about SDK versions, please see our changelog.

Step 2. Prepare the checkout listener

12345678910111213141516171819202122
public class CheckoutActivity extends AppCompatActivity {     private final CheckoutEventListener listener = new CheckoutEventListener() {        @Override        public void onCheckoutCompleted(@NonNull CheckoutData checkoutData) {            /* TODO */        }    };     @Override    protected void onCreate(@Nullable Bundle savedInstanceState) {        super.onCreate(savedInstanceState);        setContentView(R.layout.activity_main);         configureCheckout();    }     private void configureCheckout() {        // with default settings        Primer.getInstance().configure(new PrimerConfig(), listener);    }}
java
copy

Step 3. Generate a client token

💡

Check our guide on how to set up the client session here.

Make an API call to your backend to fetch a Client Token. Here is a simple example of how it can be done from your activity:

1234567891011121314151617181920212223242526272829
public class CheckoutActivity extends AppCompatActivity {     private CheckoutViewModel viewModel;     @Override    protected void onCreate(@Nullable Bundle savedInstanceState) {        super.onCreate(savedInstanceState);        setContentView(R.layout.activity_main);         configureCheckout();        setupViewModel();        setupObservers();        fetchClientToken();    }     private void setupViewModel() {        viewModel = new ViewModelProvider(this).get(CheckoutViewModel.class);    }     private void fetchClientToken() {        viewModel.fetchClientToken();    }     private void setupObservers() {        viewModel.clientToken.observe(this, clientToken -> {         });    }}
java
copy

Your view model code may look something like this:

12345678910
public class CheckoutViewModel extends ViewModel {     private final MutableLiveData<String> _clientToken = new MutableLiveData<>();    public LiveData<String> clientToken = _clientToken;     public void fetchClientToken() {        // fetch your token here (ask your backend to provide token) add our docs to exlain        _clientToken.postValue("retrieved_token");    }}
java
copy

Step 4. Show Universal Checkout

When the client token is retrieved, show Universal Checkout.

123456789101112
public class CheckoutActivity extends AppCompatActivity {       // other code goes here         private void setupObservers() {              viewModel.clientToken.observe(this, this::showUniversalCheckout);        }         private void showUniversalCheckout(String clientToken) {              Primer.getInstance().showUniversalCheckout(this, clientToken);        }}
java
copy

Step 5. Listen to onCheckoutCompleted

On the client-side, listen to the onCheckoutComplete  callback to be notified when the payment has been successfully completed. Use it to show an order confirmation screen, or to fulfil the order.

1234567
private CheckoutEventListener listener = new CheckoutEventListener() {        @Override        public void onCheckoutCompleted(@NonNull CheckoutData checkoutData) {           Log.d(CheckoutActivity.class.getSimpleName(),                    String.format("Checkout completed with payment %s", checkoutData.getPayment()));        }    };
java
copy

What’s next?

Customize Universal Checkout

Configure 3DS

In order to integrate Primer 3DS library, please follow the guide here.

To improve 3DS success rates, it is recommended to pass the following elements in the Client Session:

  • customer.emailAddress
  • customer.billingAddress

Learn more about how to configure 3DS!