Checkout - Android
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 Hub - 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
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>")
}
Creating a Card Registration
In your backend, create the Card Registration via the Mangopay API, using the Id
of the user as the UserId
.
You must also define the currency and type of the card at this stage.
{
"Tag": "Created with the Mangopay Checkout SDK",
"UserId": "142036728",
"CardType": "CB_VISA_MASTERCARD",
"Currency": "EUR"
}
{
"Id": "193020188",
"Tag": null,
"CreationDate": 1686147148,
"UserId": "193020185",
"AccessKey": "1X0m87dmM2LiwFgxPLBJ",
"PreregistrationData": "XBDYiG8w9PrylPS01KmupZunmK2QRHKIC-yUF6il3aIpAnKba1TGkR9VJe5lHjHt2ddFLVXdicolcUIkv_kKEA",
"RegistrationData": null,
"CardId": null,
"CardType": "CB_VISA_MASTERCARD",
"CardRegistrationURL": "https://pci.sandbox.mangopay.com/api/mangopay/vault/tokenize/eyJjbGllbnQiOiJjbGllbnRJZCIsInRva2VuIjoidW5xaXVlVG9rZW4ifQ==",
"ResultCode": null,
"ResultMessage": null,
"Currency": "EUR",
"Status": "CREATED"
}
The data obtained in the response will be used in the cardConfig
of the card payment method configured below.
Initializing the SDK
Initialize the SDK with your ClientId
and select your environment (Sandbox or Production).
Mangopay.initialize(clientId = "your-mangopay-client-id", environment = Environment.SANDBOX)
Initialization parameters
Property | Type | Description |
---|---|---|
clientId | String | The unique identifier associated with the Mangopay API key, giving access to the Mangopay API. |
environment | Environment | The Mangopay environment. Allowed values: SANDBOX, PRODUCTION Default values: SANDBOX |
logLevel | LogLevel | The specification of the HTTP request and response log. We recommend None for Production build.Allowed values: None, Basic Default values: None |
Configuring the checkout
Create the payment tokenization handler
Create a method for ActivityResultLauncher
to receive and handle PaymentSheetResult
.
private var resultLauncher = registerForActivityResult(
ActivityResultContracts.StartActivityForResult()) { result ->
when(val paymentSheetResult = MangopayCheckoutSdk
.handlePaymentSheetResult(resultCode = result.resultCode, intentResult = result.data)) {
is PaymentSheetResult.onTokenizationCompleted -> {
// Handle payment method tokenization
}
is PaymentSheetResult.onError -> {
// Handle sheet exceptions
}
is PaymentSheetResult.onCancelled -> {
// Handle sheet closed event
}
}
}
Payment sheet callbacks
Callback | Description |
---|---|
onTokenizationCompleted | When tokenization of the payment method is successful. |
onError | When there is an error, the exception is propagated and can be accessed. |
onCancelled | When the payment is canceled by the user (either by pressing the back button or the cancel button from the appbar). |
The payment sheet automatically closes when events are emitted to prevent users from clicking again.
Offering card payments
To offer card payments in the payment sheet:
- Build the
cardRegistration
using the values of the Card Registration object created previously. - Define the
paymentMethodConfig
and add thecardConfig
- Create the
cardConfig
and add thecardRegistration
val cardRegistration = CardRegistration.Builder()
.id(Id)
.userId(UserId)
.accessKey(AccessKey)
.preRegistrationData(PreregistrationData)
.cardRegistrationURL(CardRegistrationURL)
.build()
val cardConfig = CardConfig.Builder()
.cardRegistration(cardRegistration)
.supportCardBrands(listOf(CardScheme.MasterCard, CardScheme.Visa))
.build()
val paymentMethodConfig = PaymentMethodConfig.Builder()
.cardConfig(cardConfig)
.build();
MangopayCheckoutSdk.create(launcher = resultLauncher, this, paymentMethodConfig)
Payment sheet properties
Property | Type | Description |
---|---|---|
launcher | ActivityResultLauncher | Activity result handler created previously. |
context | Context | Activity or fragment context. |
paymentMethodConfig | PaymentMethodConfig | The configuration options of the payment method. |
cardRegistration | CardRegistration | The card registration information. |
supportCardBrands | SupportedCard | The card networks displayed to the user. Allowed values: CardScheme.MasterCard, CardScheme.Visa |
Handling card tokenization
The SDK automatically handles the card tokenization, updating 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 pay-ins with the following objects:
- 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
Note – 3DS redirection required when requesting card payments
When you make a payment request, you need to be ready to handle 3DS redirection.
Handling 3DS redirection
When requesting a payment or other card authorization, you need to be able to handle 3DS redirection if it is required by the issuer. This is indicated by the SecureModeNeeded
in the API response, and the SecureModeRedirectURL
provides the redirection URL.
The Checkout SDK’s 3DS helper allows you to redirect users to authenticate securely and seamlessly.
//Create threeds (3DS) instance
val threedsDialog = ThreedsBottomDialogFragment.newInstance()
threedsDialog.handleThreeds(this, returnUrl = "returnUrl",
redirectUrl = "redirectUrl", transactionType = TransactionType.CARD_DIRECT)
threedsDialog.handleThreeds(this,
returnUrl = "secureModeReturnURL", redirectUrl = "secureModeRedirectURL", transactionType = TransactionType.CARD_DIRECT,
listener = object : Mangopay.OnThreedsFinishedListener {
override fun success(transactionId: String, status: ResultCode) {
// onSuccess response
}
override fun error(exception: MangopayException) {
// onError response
}
}
)
3DS handler parameters
Property | Type | Description |
---|---|---|
SecureModeRedirectURL | String | The URL to which users are redirected to authenticate with 3DS (if required). |
SecureModeReturnURL | String | The URL to which users are returned after the payment, whether a 3DS challenge was triggered or not and whatever the transaction outcome. |
TransactionType | TransactionType | The type of the authorization request. Allowed values: CARD_DIRECT, PREAUTHORIZE, CARD_VALIDATION |
listener | Mangopay.OnThreedsFinishedListener | |
context | Context |
3DS listener events
Event | Description |
---|---|
complete | The 3DS authentication was completed and the status indicates whether SUCCEEDED or FAILED. In this case, the SDK provides the unique identifier of the transaction. |
error | An error occurred during the 3DS redirection request. |
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.
Offering 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 googlePayConfig
in the paymentMethodConfig
.
Create the googlePayConfig
with the googlePayObject
, containing Google Pay configuration parameters, card parameters, and transaction information.
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 googlePayConfig = GooglePayConfig.Builder()
.googlePayObject(googlePayObject)
.build()
val paymentMethodConfig = PaymentMethodConfig.Builder()
.cardConfig(cardConfig)
.googlePayConfig(googlePayConfig) // OPTIONAL
.build()
MangopayCheckoutSdk.create(launcher = resultLauncher, this, paymentMethodConfig)
googlePayObject
Property | Type | Description |
---|---|---|
merchantName | String | The name of your platform. If a merchant is recognized, the message displayed in the payment sheet is “Pay Unverified Merchant”. More information. |
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
Property | Type | Description |
---|---|---|
allowedAuthMethods | List | 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
Information about the transaction and its authorization, such as whether the user agrees to the transaction, the total price and price status. For more information on this object parameter, see the Google Pay documentation.
Handling Google Pay result
private var resultLauncher = registerForActivityResult(
ActivityResultContracts.StartActivityForResult()) { result ->
when(val paymentSheetResult = MangopayCheckoutSdk
.handlePaymentSheetResult(resultCode = result.resultCode, intentResult = result.data)) {
is PaymentSheetResult.onTokenizationCompleted -> {
// Handle payment method tokenization
when(val cardPaymentMethodResult = paymentSheetResult.paymentMethod){
is PaymentMethod.GOOGLE_PAY -> {
// Get result token for testing
Log.v(TAG, cardPaymentMethodResult.token)
}
}
}
}
}
Requesting Google Pay pay-in
To request the payment, use the Create a Google Pay PayIn endpoint and include the Google Pay PaymentData
.
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 thePaymentFormView
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 |
<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.
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 |