Search Overlay

Using Android SDK

Import SDK

Import the Paysafe SDK dependency in your gradle file:

dependencies {
implementation("com.github.paysafegroup:paysafe_sdk_android_payments_api:threedsecure:x.y.z")
}

Important

For 3DS operations, Paysafe SDK uses Cardinal SDK. It is not a transitive dependency but a direct dependency (an AAR file) served through the paysafe-cardinal module.

If your project already has Cardinal SDK integrated, it will clash with our paysafe-cardinal module. To solve this, you must exclude one of the Cardinal dependencies from your project.

In this example, we exclude paysafe-cardinal from being used when importing the card-payments module:

implementation("com.github.paysafegroup.paysafe_sdk_android_payments_api:card-payments:0.0.43") {
    exclude(
        "com.github.paysafegroup.paysafe_sdk_android_payments_api",
        "paysafe-cardinal"
    )
}

Set up the SDK

Configure the SDK with your Paysafe API Key & Environment so that it can make requests to the Payments API, such as in your activity or fragment.

import com.paysafe.android.PaysafeSDK

try {
PaysafeSDK.setup("<api-key>", PSEnvironment.TEST)
} catch (e: PaysafeException) {
// handle exception
}

The setup function creates and initializes the Paysafe Android SDK. Pass the following parameters during its initialization from the application:

  1. The Base64-encoded version of the single-use token API key (used to authenticate with the Payments REST API).
  2. Environment (TEST/ LIVE).
  3. Theme (optional).

Initialize Paysafe3DS

The Paysafe3DS initializer has the following signature:

val paysafe3DS = Paysafe3DS()
                                

Do not use real card numbers or other payment instrument details in the Merchant Test environment as this is not compliant with Payment Card Industry Data Security Standards (PCI DSS) and does not protect cardholder/ payee information. Uploading real cardholder data is strictly prohibited, as described in the Terms of Use.

Start challenge

Use your provider API or service to generate a paymentHandle.

Using the paymentHandle, you can start the 3DS challenge by calling the following method. It returns a publisher that publishes a String representing either the deviceFingerprintingId or a PSError object:

/**
* Initialize the 3DS challenge SDK.
*
* @param lifecycleOwner Context that owns a lifecycle. Most of the cases an [Activity].
* @param cardBin Card bank identification number.
* @param callback Result object with success/failure methods to handle 3DS initialization.
*/
fun start(
context: Context,
lifecycleOwner: LifecycleOwner,
bin: String,
accountId: String,
threeDSRenderType: ThreeDSRenderType?,
callback: PSResultCallback<String>
)

/**
* Coroutine to initialize the 3DS challenge SDK.
*
* @param bin Bank identification number.
* @return Device finger print ID.
*/
suspend fun start(
context: Context,
bin: String,
accountId: String,
threeDSRenderType: ThreeDSRenderType?
): PSResult<String>

Paysafe3DS parameters

Parameter Required Type Description

accountId

true

String

The id of the selected merchant account to use for processing the payment.

If you are a merchant, this field is required only if you have more than one account configured for the same payment method and currency. If you are a partner using a shared API key, this field is mandatory.

bin

true

String

The card Bank Identification Number (BIN) or network BIN. This is typically the first 6–8 digits of the card.

threeDSRenderType

false

ThreeDSRenderType

ThreeDSRenderType is an enum type with the following values:

  • NATIVE
  • HTML
  • BOTH

callback

true

PSResultCallback<String>

A callback that handles the result.

  • onSuccess it returns the deviceFingerprintingId
  • onFailure it returns an exception

lifecycleOwner

true

LifeCycleOwner

The lifecycle owner for observing lifecycle events.

Usage example

paysafe3DS.start(
context = context,
lifecycleOwner = lifecycleOwner,
bin = "<card-bin or network-bin>",
accountId = "<account-id>",
threeDSRenderType = ThreeDSRenderType.BOTH,
callback = object : PSResultCallback<String> {
override fun onSuccess(value: String?) {
print("deviceFingerprintId: $value")
}

override fun onFailure(exception: Exception) {
// handle exception
}
})

Once you have received the deviceFingerprintingId from the mobile SDK you should include it in your Authentication request along with the other required fields and contextual data. See the API documentation for a complete description of the parameters required for the Authentication request.

When the authentication is complete, Paysafe interprets the directory server response and returns a response containing the status and threeDResult* parameters along with the authenticationId.

If status=COMPLETED, you should consult the Liability Shift matrix to determine whether to proceed with the Authorization request.
If status=PENDING and threeDResult=C, the card issuer has challenged the authentication request and requires additional verification. In this situation, you should continue with the challenge flow.

See the 3DS Overview for more information about these flows.

Challenge

Use your provider API or service to authenticate your deviceFingerprint to generate challengePayload and then launch 3DS Challenge.

Method signature

/**
* Launch the 3DS challenge request.
*
* @param activity Reference for android framework activity.
* @param challengePayload 3DS challenge payload.
* @param callback Result object with success/failure methods to handle 3DS challenge payload.
*/
fun launch3dsChallenge(
activity: Activity,
challengePayload: String,
callback: PSResultCallback<ThreeDSChallengePayload>
)

ThreeDSChallengePayload is the result of the challenge and it contains:

  • authenticationId - 3DS challenge authentication ID.
  • accountId - Account ID that launch 3DS challenge.
  • serverJwt - 3DS challenge server JWT.

Usage example

let challengePayload = ... // authenticating using the deviceFingerprintId
paysafe3DS.launch3dsChallenge(
activity,
challengePayload,
object : PSResultCallback<ThreeDSChallengePayload> {
override fun onSuccess(value: ThreeDSChallengePayload?) {
//Assert
print("$value?.serverJwt"")
}

override fun onFailure(exception: Exception) {
// handle exception
}
})