Overview
The Paysafe Android SDK is a flexible and fully customizable mobile SDK that seamlessly integrates into your mobile app. It handles data security and PCI compliance while giving you the freedom to customize the entire customer experience to match your mobile app's design. The mobile SDK takes care of sensitive payment fields (card number, CVV, and expiry date, year, and month), while keeping data security and PCI compliance in mind.
Paysafe handles the customer input and data storage. The Paysafe Android SDK uses the Payments API for processing payments. The SDK is designed with a clear and modular structure to ensure a seamless implementation experience.
Advantages
- Paysafe native SDK may provide better PCI scope because of how Paysafe collects the card data right from within the mobile app. Please consult with your Qualified Security Assessor to determine your PCI level.
- Extensive customization options enable you to customize payment forms that match your mobile app design. Create as many translated or localized versions of your payment form as required.
- Embeds naturally and remains invisible.
- Supports processing payments with 3D Secure-enabled cards.
- No redirection to an external webpage for 3DS is required.
- Supports native Android Platform SCA authentication.
Before you begin
Contact your business relationship manager or send an email to integrations@paysafe.com for your Business Portal credentials.
To obtain the Public API key from the Business Portal:
- Log in to the Business Portal.
- Go to Integrate > API Keys.
- For the Public Key, click the Copy icon to copy the API key.
- Your API key will have the following format:
- Key Username – MerchantXYZ
- Key Password –
B-tst1-0-51ed39e4-312d02345d3f123120881dff9bb4020a89e8ac44cdfdcecd702151182fdc952272661d290ab2e5849e31bb03deede7
- Use the same API key for all payment methods.
- You must Base64 Encode your Public API key before using it in the Payments Android SDK.
- The API key is case-sensitive and sent using HTTP Basic Authentication.
- To use HTTP Basic Authentication, you must send the API key credentials using the Authorization header with every request.
- You must construct the Authorization header as follows:
- Combine the Key Username and Key Password into a string separated by a colon, e.g., “Key Username:Key Password”.
- The resulting string literal is then encoded using Base64.
- The authorization method and space (i.e., “Basic”) are then put before the encoded string.
- For example, using the Key Username and Password examples above, the header is formed as follows:
Authorization: Basic TWVyY2hhbnRYWVo6Qi10c3QxLTAtNTFlZDM5ZTQtMzEyZDAyMzQ1ZDNmMTIzMTIwODgxZGZmOWJiNDAyMGE4OWU4YWM0NGNkZmRjZWNkNzAyMTUxMTgyZmRjOTU yMjcyNjYxZDI5MGFiMmU1ODQ5ZTMxYmIwM2RlZWRlN2U=
For more information, see Authentication.
SDK modules
The SDK comprises several dedicated modules:
- Card payments module
- Offers dedicated views to capture and tokenize credit card details securely.
- Offers customization for individual components and supports accessibility.
- 3DS module
- Specialized for 3D Secure transactions, ensuring secure online payments by adding an authentication layer.
- Streamlines the 3DS challenge process when necessary for a credit card.
- Venmo module
- Provides integration to Venmo
- Venmo tokenization through Payments API
- Google Pay module
- Offers GooglePay payment implementation
- Provides integration to GooglePay
- Provides customization for GooglePay button rendering
- GooglePay tokenization through Payments API
- Tokenization module
- Handles the generation of payment handles
- Paysafe Core module
- The foundational module, offering core functionalities and utilities essential for the SDK's operations.
- Provides common utilities and services that are used across the SDK
Integrating the Android SDK
The Paysafe Android SDK is open source and includes a demo for testing the various functionalities. It is compatible with apps supporting Android XX or above.
To integrate the Paysafe Payments Android SDK:
STEP 1: Add the JitPack repository to your build file. Add it in your root build.gradle (or settings.gradle.kts) at the end of repositories:
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
mavenCentral()
maven { url = uri("https://jitpack.io") }
}
}
STEP 2: In your gradle file, add the dependency that includes all SDK functionalities and integrations:
dependencies {
implementation("com.github.paysafegroup:paysafe_sdk_android_payments_api:x.y.z")
}
If you want to include only one module or specific modules, specify them as shown in the following example:
dependencies {
implementation("com.github.paysafegroup.paysafe_sdk_android_payments_api:venmo:x.y.z")
implementation("com.github.paysafegroup.paysafe_sdk_android_payments_api:google-pay:x.y.z")
implementation("com.github.paysafegroup.paysafe_sdk_android_payments_api:card-payments:x.y.z")
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.
SDK requirements
- Android 6.0 (API level 23) and above
- Android Gradle Plugin 3.5.1
- Gradle 5.4.1 +
- AndroidX (as of v11.0.0)
Setup
After the Paysafe Android package is integrated into your project, set up the PaysafeSDK on application start.
import com.paysafe.android.PaysafeSDK
try {
PaysafeSDK.setup("<api-key>", PSEnvironment.TEST)
} catch (e: SomeException) {
// handler
}
The setup function creates and initializes the Paysafe Android SDK. Pass the following parameters during its initialization from the application:
Parameter | Required | Type | Description |
---|---|---|---|
apiKey | true | String | The Base64-encoded version of the single-use token API key is used to authenticate with the Paysafe Payment API. |
environment | true | Enum PSEnvironment | Paysafe server environment. Environment is an enum class with the following cases:
|
API Key
The Base64-encoded version of the single-use token API key is used to authenticate with the Payments API. For more information about obtaining your API Keys, see Before you begin.
Note that this key can only be used to generate single-use tokens and has no other API access rights (such as for taking payments). Consequently, it can be exposed publicly in the customer's browser.
Environment
The environment string is used to select the environment for tokenization. The accepted environments are PROD (Paysafe Production environment) and TEST (Paysafe Merchant Test or Sandbox environment).
Do not use real card numbers or other payment instrument details in the Merchant Test environment. Test/ Sandbox is not compliant with Payment Card Industry Data Security Standards (PCI-DSS) and does not protect cardholder/ payee information. Any upload of real cardholder data is strictly prohibited, as described in the Terms of Use.
Callback error object
The following table describes the contents of the error object:
Parameter | Required | Type | Description |
---|---|---|---|
code | true | String | Error code |
displayMessage | true | String | Error message for display to customers. |
detailedMessage | true | String | Detailed description of the error (this information should not be displayed to customers). |
correlationId | true | String | Unique error ID to be provided to Paysafe Support during investigation |
Setup errors
Error code | Display message | Detailed message | Comments |
---|---|---|---|
9167 | There was an error (9167), please contact our support. | The API key should not be empty. |
|
9013 | There was an error (9013), please contact our support. | Invalid API key. | The decoded API key doesn’t conform with the format “username:password”. |