Checkout - Android - Mangopay docs

This guide helps you get started with the Checkout SDK on Android.

Prerequisites

A ClientId and an API key – if you don’t have these, contact Sales to get access to the Mangopay Dashboard
A User and their associated Wallet to complete the pay-in
A card to register or payment method setup (see Testing - Payment methods for testing information)

For Android:

Android minSdk = 21

Best practice – Check out our example app and demo

To support you with your integration, be sure to make use of our example app on GitHub.

Installation

The Mangopay Checkout SDK is published as a Maven artifact on Maven Central Repository.

Add the following code to your app/build.gradle file:

repositories {
  mavenCentral()
}

dependencies {
   implementation("com.mangopay.android:checkout-sdk:<latest-version>")
}

Optionally, to enable the fraud prevention Profiler SDK, add the following to settings.gradle.kts:

maven {
    url = uri("https://nethone.jfrog.io/artifactory/nethonesdk-android-mangopay/")
}

Initializing the SDK

Initialize the SDK with your ClientId and select your environment (Sandbox or Production).

Note – Initialize once per app instance

The initialization should only be done once for an instance of the application.

We recommend putting this inside the Application() class.

MangopaySdk.initialize(
    context = this,
    clientId = “clientId”,
    profilingMerchantId = “profilingMerchantId”,
    tenantId = TenantId.EU,
    environment = Environment.SANDBOX,
    logLevel = LogLevel.Basic
)

Initialization parameters

Property	Type	Description
`context`	Application	The application context.
`clientId`	String	The unique identifier associated with the Mangopay API key, giving access to the Mangopay API.
`profilingMerchantId`	Int	The unique identifier associated with your fraud protection package. Contact Mangopay to obtain this value.
`environment`	Environment	The Mangopay environment. Allowed values: `Environment.SANDBOX`, `Environment.PRODUCTION` Default values: `Environment.SANDBOX`
`logLevel`	LogLevel	The specification of the HTTP request and response log. We recommend `None` for Production build. Allowed values: `LogLevel.None` , `LogLevel.Basic` Default values: `LogLevel.None`
`tenantId`	TenantId	The identifier of the Mangopay tenant. Allowed values: `TenantId.EU`, `TenantId.UK`

Configuration

To configure the Checkout SDK’s payment sheet:

Configure the PaymentMethodOptions

Configure the options for each payment method as described below.

Present the payment sheet

Add PaymentMethodOptions and callbacks and display the payment sheet.

val paymentMethodOptions = PaymentMethodOptions.Builder()
        .cardOptions(cardOptions)
        .googlePayOptions(googlePayOptions) // OPTIONAL
        .paypalOptions(paypalOptions) // OPTIONAL
        .amount(amount)
        .build()

MangopayCheckoutSdk.create(
    mContext = this,
    paymentMethodOptions = paymentMethodOptions, 
    listener = paymentSheetCallbacks()
) 

Property	Type	Description
`mContext`	Activity / Fragment	Activity or Fragment context
`paymentMethodOptions`	PaymentMethodOptions	Configuration parameters
`listener`	Mangopay.PaymentSheetResultListener	Callback listeners

The payment sheet closes automatically when events are emitted to prevent users from clicking again.

Handling redirection

Warning – Use Mangopay Checkout domain as return URL

When making the pay-in request from your backend, use the Mangopay Checkout URL as the SecureModeReturnURL or ReturnURL (depending on the payment method):

http://checkout.mangopay.com

The user must be returned to this URL after redirection.

Some payment methods (card, Google Pay, PayPal) require or may require the user to be redirected to authorize or complete a transaction.

The Checkout SDK allows you to manage the entire payment flow seamlessly while retaining control over transaction logic in your backend. Once a payment method is selected and payment details are provided, use the onCreatePayment function to request the transaction from your backend.

Subsequently, and when necessary for the transaction type, the Checkout SDK seamlessly manages additional redirect actions for 3DS authorization or otherwise validating the payment.

To manage transaction redirects effectively with the SDK:

Define onCreatePayment

In your PaymentMethodOptions configurations, define an onCreatePayment attribute as a function.

Within your function:

Request a transaction from your server and subsequently, Mangopay.
Return the unaltered transaction response object to the SDK.

The SDK:

Redirects the user to the payment authentication page when necessary.
Manages payment provider redirects back to the SDK.
Triggers the onPaymentCompleted event with the ID and status of the transaction.
Confirms the redirect result on your server by invoking the corresponding GET API of the transaction.
Presents the payment result to the user.

Creating payment handler callbacks

private fun paymentSheetCallbacks() = object : Mangopay.PaymentSheetResultListener {
    override fun onTokenizationCompleted(paymentMethod: PaymentMethod?, profilerAttemptReference: String?) {

        when (paymentMethod) {
            is PaymentMethod.CARD -> TODO()
            is PaymentMethod.GOOGLE_PAY -> TODO()
            else -> TODO()
        }
    }

    override fun onPaymentCompleted(id: String?, resultCode: ResultCode) {

    }

    override fun onPaymentMethodSelected(paymentMethod: PaymentMethod) {

    }

    override suspend fun onCreatePayment(paymentMethod: PaymentMethod, profilerAttemptReference: String?): Payment? {
        return when(paymentMethod){
            is PaymentMethod.PAYPAL -> TODO()
            is PaymentMethod.CARD -> TODO()
            is PaymentMethod.GOOGLE_PAY -> TODO()
            is GooglepayObject -> TODO()
        }
    }

    override suspend fun onCreateCardRegistration(card: Card): CardRegistration {

    }

    override fun onError(exception: MangopayException?) {

    }

    override fun onCancel() {

    }
}

PaymentSheet callbacks

Callback	Description	Return type
`onTokenizationCompleted(paymentMethod: PaymentMethod?, profilerAttemptReference: String?)`	Triggered when a card tokenization is completed and a `CardId` is returned.
`onPaymentCompleted(id: String?, resultCode: ResultCode)`	Triggered when the transaction is completed, whatever the outcome (whether successful or failed).
`onPaymentMethodSelected(paymentMethod: PaymentMethod)`	Triggered when a payment method has been selected.
`onCreatePayment(paymentMethod: PaymentMethod, profilerAttemptReference: String?): Payment?`		`Payment?`
`onCreateCardRegistration(card: Card): CardRegistration?`	Triggered only when the user selects card payment. This callback gives you control over making the card registration optional during the session.	`CardRegistration?`
`onError(exception: MangopayException?)`	Triggered when an internal Checkout SDK error has occurred, which propagates the exception.
`onCancel()`	Called when the payment sheet is closed.

The payment sheet automatically closes when events are emitted to prevent users from clicking again.

Configuring the amount

val amount = Amount.Builder()
        .value(200.00)
        .currency(Currency.EUR)
        .build()

Amount configuration parameters

Property	Type	Description
`value`	Double
`currency`	Currency

Configuring card payments

val cardOptions = CardOptions.Builder()
                    .supportedCardSchemes(
                        listOf(CardScheme.Maestro,CardScheme.MasterCard,CardScheme.Visa,)
                    )
                    .build()

Card configuration parameters

Property	Type	Description
`supportedCardSchemes`	List<Card>	The card networks displayed to the user.
`cardRegistration`	CardRegistration?	You can provide CardRegistration optionally from configuration or provide it from callbacks.

Handling card tokenization

In the options for the card payment method, create a function to handle creation of Card Registration event handler in the payment methods object:

Your onCreateCardRegistration function calls your server, and passes it the card brand of the user.
Your server makes a request to Create a Card Registration.
In response, your server receives a Card Registration object.
In your onCreateCardRegistration function, return the unmodified Card Registration object to the SDK.
The SDK tokenizes the card and updates the Card Registration object to create the CardId which is used for payment.

Managing cards

You can use the following endpoints to manage cards:

View a Card provides key information about the card, including its Fingerprint which can be used as an anti-fraud tool
Deactivate a Card allows you to irreversibly set the card as inactive

Warning – End user’s approval needed to save card details

Under no circumstances should card information be kept without the end user’s approval.

If you don’t have the end user’s approval, you need to deactivate the card systematically after use in your implementation.

Requesting card pay-ins

You can use a registered card (CardId) for requests with the following API objects:

The Card Validation object, to validate a card without debit
The Direct Card PayIn object, for one-shot card payments
The Recurring PayIn Registration object, for recurring card payments
The Preauthorization object, for 7-day preauthorized card payments
The Deposit Preauthorization object, for 30-day preauthorized card payments

In your requests:

Ensure that the SecureModeReturnURL parameter is set to https://checkout.mangopay.com
Submit the PreferredCardNetwork value if it was received by onCreatePayment

Verifying the payment result

Best practice – Check payment result from backend

It is highly recommended that you confirm the transaction result from your backend using the API endpoint.

Configuring Google Pay

Note – Google Pay setup required

Offering Google Pay requires additional setup by the platform. For more information, see the How to process a Google Pay payment tutorial.

To offer the Google Pay payment method, include the GooglePayOptions in the payment sheet:

Configure TransactionInfo object
Create GooglePay object
Configure GooglePayObject

val transactionInfo = TransactionInfo.Builder()
        .currencyCode("EUR")
        .countryCode("FI")
        .totalPriceStatus(TotalPriceStatus.FINAL)
        .totalPrice(5000.0)
        .transactionId(UUID.randomUUID().toString())
        .build()

val cardParameters = CardParameters.Builder()
       .allowedAuthMethods(listOf("PAN_ONLY", "CRYPTOGRAM_3DS"))
       .allowedCardNetworks(listOf( "MASTERCARD", "VISA"))
       .build()

val googlePayObject = GooglePayObject.Builder()
        .merchantName("Example Test")
        .gatewayMerchantId("your-mangopay-client-id")  
        .transactionInfo(transactionInfo)
        .cardParameters(cardParameters)
        .build()

val googlePayOptions = GooglePayOptions.Builder()
        .googlePayObject(googlePayObject)
        .build()

Google Pay Parameters

Property	Type	Description
`gatewayMerchantId`	String	Your Mangopay `ClientId`.
`transactionInfo`	TransactionInfo	Information about the transaction. For more information on this object parameter, see the Google Pay documentation.
`cardParameters`	CardParameters	Information about the card used for the payment.

`CardParameters` required parameters

Property Type Description

Property	Type	Description
`allowedAuthMethods`	List<String>	The supported authentication methods: PAN_ONLY, meaning the card is registered in the user’s Google account and requires additional authentication; CRYPTOGRAM_3DS, meaning the card is enrolled in the customer’s Google Wallet and authentication is handled by Google, with no 3DS redirection and no liability for the platform. Allowed values: PAN_ONLY, CRYPTOGRAM_3DS
`allowedCardNetworks`	List	The card networks supported by Mangopay: VISA and MASTERCARD. Allowed values: VISA, MASTERCARD

allowedAuthMethods

List<String>

The supported authentication methods:

PAN_ONLY, meaning the card is registered in the user’s Google account and requires additional authentication;
CRYPTOGRAM_3DS, meaning the card is enrolled in the customer’s Google Wallet and authentication is handled by Google, with no 3DS redirection and no liability for the platform.

Allowed values: PAN_ONLY, CRYPTOGRAM_3DS

allowedCardNetworks

List

The card networks supported by Mangopay: VISA and MASTERCARD.

Allowed values: VISA, MASTERCARD

`TransactionInfo` required parameters

Property	Type	Description
`countryCode`	String
`currencyCode`	String
`totalPriceStatus`	TotalPriceStatus
`totalPrice`	Double

Requesting Google Pay pay-in

To request the payment, use the Create a Google Pay PayIn endpoint and include the Google Pay PaymentData provided by the Checkout SDK.

Configuring PayPal

val paypalOptions = PaypalOptions.Builder()
          .buttonOptions(buttonOptions)
          .build()

PayPal configuration parameters

Property	Type	Description
`buttonOptions`	PaymentButtonOptions

Using Card Element

Card Element is a ready-made component that allows you to create your own card payment experience and tokenize card payment details. With Card Element, you can incorporate a custom pay button and have control over the tokenization process.

When using Card Element, you still benefit from card data validation, and the ability to customize the payment form.

To use Card Element, proceed as follows:

1. Add the payment form to the intended layout

<com.mangopay.android.checkout.view.PaymentFormView
            android:id="@+id/payment_form"
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            app:mangopay_elementBorderLineType="rectangle" />


<!-- Add custom pay button -->
<Button
            android:id="@+id/btn_pay"
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:visibility="visible"
            android:layout_below="@+id/payment_form"
            android:layout_marginTop="50dp"
            android:text="Pay" />

2. Create the Card Registration as described above

val cardRegistration = CardRegistration.Builder()
        .id("Id")
        .userId("UserId")
        .accessKey("AccessKey")
        .preRegistrationData("PreRegistration")
        .cardRegistrationURL("CardRegistrationURL")
        .build()

3. Tokenize the card with the paymentForm object

//Find and connect PaymentFormView from Java/Kotlin code
val paymentForm = findViewById<PaymentFormView>(R.id.payment_form)
val payButton = findViewById<PaymentFormView>(R.id.btn_pay)
// tokenize card with the paymentForm object.
 payButton.setOnClickListener {

    //check if the paymentForm passed validation
    if(paymentForm.isComplete()){

            MangopayCheckoutSdk.tokenizeCard(
     paymentForm.toCardRequest(), cardRegistration,
       this@PaymentFormActivity, object: Mangopay.CheckoutTokenizeCardResultCallback {

             override fun success(result: CardResult?, attemptReference: String?) {
                 //process payment in your backend
             }
             override fun error(exception: MangopayException) {
                 //show error to shopper 
             }
           }
        )
    }
 }

Branding

You can customize the appearance of the payment sheet by adding a theme.xml file to the PaymentFormView object.

Property	Type
mangopay_elementTopLabelColor	Color
mangopay_elementInputColor	Color
mangopay_elementInputHintColor	Color
mangopay_elementTopLabelSize	Dimension
mangopay_elementTopLabel	String
mangopay_buttonBackgroundColor	Color
mangopay_buttonTextColor	Color
mangopay_progressBarColor	Color
mangopay_elementBorderLineType	Enum

Example – Theme
<style name="Theme.ShuFitness" parent="Theme.MaterialComponents.DayNight.DarkActionBar">
        <!-- Primary brand color. -->
        <item name="colorPrimary">@color/shopping_primary</item>
        <item name="colorPrimaryVariant">@color/shopping_primary</item>
        <item name="colorOnPrimary">@color/white</item>

        <item name="mangopay_elementTopLabelColor">@color/black</item>
        <item name="mangopay_elementInputColor">@color/black</item>
        <item name="mangopay_elementTopLabelSize">@dimen/top_label_size</item>
        <item name="mangopay_elementInputHintColor">@color/black</item>
        <item name="mangopay_progressBarColor">@color/shopping_secondary</item>
    </style>

You can add your theme to the application in AndroidManifest.xml.

<application
    android:allowBackup="true"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name"
    android:roundIcon="@mipmap/ic_launcher_round"
    android:supportsRtl="true"
    android:theme="@style/Theme.ShuFitness">

Configuring the Google Pay button

Configure the Google Pay button for your app in line with Google Pay’s brand guidelines.

Example – Google Pay configuration
val paymentMethods = JSONArray().put(PaymentsUtil.baseCardPaymentMethod())
val gpayButtonOption = ButtonOptions.newBuilder()
       .setButtonTheme(ButtonConstants.ButtonTheme.LIGHT)
       .setButtonType(ButtonConstants.ButtonType.BUY)
       .setAllowedPaymentMethods(paymentMethods.toString())
       .setCornerRadius(10)
       .build()

Localization

The Mangopay Checkout SDK allows you to localize language strings.

Property	Type
mangopay_elementTopLabel	String
mangopay_buttonCheckoutText	String
mangopay_cardNumberHint	String
mangopay_cardNumberError	String
mangopay_cardNameHint	String
mangopay_cardNameError	String
mangopay_cardMMYYHint	String
mangopay_cardMMYYError	String
mangopay_cardCVVHint	String
mangopay_cardCVVError	String
mangopay_orPayWithText	String
mangopay_sheetAppBarText	String

Getting started

Integration options

Resources

Useful links

Checkout - Android

Installation

Initializing the SDK

Initialization parameters

Configuration

Handling redirection

Creating payment handler callbacks

PaymentSheet callbacks

Configuring the amount

Amount configuration parameters

Configuring card payments

Card configuration parameters

Handling card tokenization

Managing cards

Requesting card pay-ins

Verifying the payment result

Configuring Google Pay

Google Pay Parameters

`CardParameters` required parameters

`TransactionInfo` required parameters

Requesting Google Pay pay-in

Configuring PayPal

PayPal configuration parameters

Using Card Element

1. Add the payment form to the intended layout

2. Create the Card Registration as described above

3. Tokenize the card with the paymentForm object

Branding

Configuring the Google Pay button

Localization

Getting started

Integration options

Resources

Useful links

​Installation

​Initializing the SDK

​Initialization parameters

​Configuration

​Handling redirection

​Creating payment handler callbacks

​PaymentSheet callbacks

​Configuring the amount

​Amount configuration parameters

​Configuring card payments

​Card configuration parameters

​Handling card tokenization

​Managing cards

​Requesting card pay-ins

​Verifying the payment result

​Configuring Google Pay

​Google Pay Parameters

​CardParameters required parameters

​TransactionInfo required parameters

​Requesting Google Pay pay-in

​Configuring PayPal

​PayPal configuration parameters

​Using Card Element

​1. Add the payment form to the intended layout

​2. Create the Card Registration as described above

​3. Tokenize the card with the paymentForm object

​Branding

​Configuring the Google Pay button

​Localization

Installation

Initializing the SDK

Initialization parameters

Configuration

Handling redirection

Creating payment handler callbacks

PaymentSheet callbacks

Configuring the amount

Amount configuration parameters

Configuring card payments

Card configuration parameters

Handling card tokenization

Managing cards

Requesting card pay-ins

Verifying the payment result

Configuring Google Pay

Google Pay Parameters

`CardParameters` required parameters

`TransactionInfo` required parameters

Requesting Google Pay pay-in

Configuring PayPal

PayPal configuration parameters

Using Card Element

1. Add the payment form to the intended layout

2. Create the Card Registration as described above

3. Tokenize the card with the paymentForm object

Branding

Configuring the Google Pay button

Localization