Vault - Android
Introduction
The Mangopay Vault SDK allows you to securely tokenize an end user’s payment card for use in your application. A tokenized card is a virtual and secure version of the card that can be used for payment.
It is very highly recommended that you use the Mangopay Vault SDK, rather than integrating the API endpoints directly. By doing so, you:
- Avoid sensitive card details transiting your system
- Benefit from PCI-DSS compliance
- Receive ongoing support and updates
To use the Mangopay Vault SDK (Android), you’ll need:
- A Mangopay
ClientId
and API key (get a Sandbox API key for free) - A User to register the card for (see Testing - Payment methods for test cards)
- Android
minSdk = 21
Installation
Add the following dependency to build.gradle (module):
implementation("com.mangopay.android:vault-sdk:<latest-version>")
Initializing the SDK
Initialize the SDK with your ClientId
and select your environment (Sandbox or Production).
MangopayVaultSdk.initialize(clientId = "your-mangopay-client-id", environment = MangopayEnvironment.SANDBOX)
Optional initialization parameters
Argument | Data-type | Description |
---|---|---|
logLevel | LogLevel | Use this to specify HTTP request and response log. We recommend Default value: Allowed values: |
environment | Environment | Expected backend environment. Default value: Allowed values: |
Creating the 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 Vault SDK",
"UserId": "193020185",
"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 preregistrationData
defined below.
Providing data for tokenization
The SDK requires the following information to tokenize the card:
- The end user’s card details (
CardRegistration
) entered in the app (see Testing - Payment methods for test cards) - The Card Registration data (
Card
) previously returned by the Mangopay API
CardRegistration
Property | Type | Description |
---|---|---|
Id | string | The unique identifier of the Card Registration object. |
AccessKey | string | The secure value used when tokenizing the card. |
PreregistrationData | string | A specific value passed to the CardRegistrationURL . |
CardRegistrationURL | string | The URL to which the card details are sent to be tokenized. |
val cardRegistration = CardRegistration.Builder()
.id(Id)
.accessKey(AccessKey)
.preRegistrationData(PreRegistrationData)
.cardRegistrationURL(CardRegistrationURL)
.build()
Card
Property | Type | Description |
---|---|---|
number | string | The card number to be tokenized, without any separators. |
expirationDate | string (Format: “MMYY”) | The expiration date of the card. |
cvv | string | The card verification code (on the back of the card, usually 3 digits). |
val card = Card.Builder()
.number("4970107111111119")
.expirationDate("1224")
.cvv("123")
.build()
Tokenizing the card
You can now tokenize the card with the card data obtained previously using the frontend SDK.
The SDK automatically updates the Card Registration object to provide you with a CardId
that can be used for payments.
// Define the callback to receive tokenization result
private fun tokenizeCallbacks() = object: Mangopay.TokenizeCardResultCallback{
override fun success(result: CardRegistration?) {
// You can use result.cardId to process payments from your backend
}
override fun error(exception: MangopayException) {
// An error has occured
}
}
// Invoke tokenizeCard method
MangopayVaultSdk.tokenizeCard(card, cardRegistration, this, tokenizeCallbacks())
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.
Making card payments
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
Caution – Card validation within 24 hours
A successful transaction (preauthorization, pay-in, or recurring) within 24 hours of the card registration is required to validate a card. Otherwise, the card remains invalid and a new card registration will be necessary to make a payment.