Mobile: Android SDK
Integration guide
1. Get an API key
During your onboarding process, your dedicated integration manager will provide you with your unique API key. If at any time you lose your API key, please reach out to your dedicated integration manager to reset your API key.
You can also find the API key in the Partner Portal under the "For developers" section.
2. Build Integration
Now that you have an API key you are able to set up crypto purchases via Widget in several ways. You can build the integration with a quote or without a quote.
Integration without a quote
When you build an integration without a quote it means you don't show your customer a quote for purchase in your UI. Your customer starts his journey without predefined transaction details. It is a more simple integration and you can implement it by creating simple CTA (call to action) buttons in your UI. Your customer will be able to select everything (cryptocurrency, fiat currency, amount, etc) in the widget and his journey will start from an exchange form.
To implement this type of integration you will need to:
- Create a requestID with an empty quote. You still have an option to add parameters when creating the requestID. You can read more about it in Create request.
- After you receive the requestID you can initiate the Android widget with it. Please read the Android widget installation guide here.
Integration with a quote
You can also build an integration with a quote. It is a bit more complicated than the integration without a quote because you have to use one more API endpoint. This also means you will need to spend more time developing your UI. This integration is useful if you want to allow your customer to see transaction details in your UI. It is also being used when implementing several on-ramp solutions and allowing your customer to compare how much they get for their money from different providers. When you implement this type of integration your customer will start their journey with predefined transaction values like transaction amount, cryptocurrency, fiat currency, etc.
To implement this type of integration you will need to:
- Create a quote first. Please read more about how to create a quote here.
- Create a requestID with the quoteID you got from the quote you created. Please read more about creating requestID here.
- After you receive requestID you can initiate a widget Android with it. Please read Android installation guide here.
Important Tip!
Tip: when building your UI in order to get the list of available fiat/crypto pairs and their respective min/max limits per transaction use the Get currency pairs to buy crypto and Get currency pairs to sell crypto endpoints.
Please note the API endpoints for environments:
- Sandbox for testing: - https://widget-api.sandbox.paybis.com/v1/*
- Production: - https://widget-api.paybis.com/v1/
3. Setup the Paybis Widget Android SDK
Add our SDK to your project so you can run the widget’s UI and handle its events. More information about the Android SDK can be found here.
4. Run the widget
With the requestId received, you can start the widget using Android SDK. For that, you need to request the start function. As a result, the widget’s UI is displayed over your application and the user can interact with it directly.
Installation guide
Maven
- Firstly you’ll need to ask Paybis team for your personal private token to SDK’s Maven repository
- Open project-level
build.gradle
and add following to authenticate to the Package Registry
allprojects {
repositories {
... other repositories above ...
maven {
url "https://gitlab.com/api/v4/projects/37932505/packages/maven"
name "GitLab"
credentials(HttpHeaderCredentials) {
name = 'Private-Token'
value = *Your private token*
}
authentication {
header(HttpHeaderAuthentication)
}
}
}
}
For Gradle version 7+ this code goes to settings.gradle
dependencyResolutionManagement {
... other repositories above ...
maven {
url "https://gitlab.com/api/v4/projects/37932505/packages/maven"
name "GitLab"
credentials(HttpHeaderCredentials) {
name = 'Private-Token'
value = *Your private token*
}
authentication {
header(HttpHeaderAuthentication)
}
}
}
- After that, you can add Paybis SDK as a project dependency. Add this line to your app-level
build.gradle
(latest version number can be found on changelog)
dependencies {
implementation "com.paybis:mobile_widget_sdk:$latestVersion"
}
- SDK has an implementation for QR code scanning that users may want to use to scan their crypto wallet address. For this, you may add Camera permission to your application
AndroidManifest.xml
<manifest>
... other permissions above ...
<uses-permission android:name="android.permission.CAMERA" />
... your classes and meta data below ...
</manifest>
- SDK is built using DataBinding, so please add the following code to your Gradle files
android {
...
buildFeatures {
dataBinding = true
}
}
Additional dependencies
The widget uses SumSub library for Know Your Customer process and risk.js
package for the payment fraud detection, it is required to add the following dependencies to the project-level build.gradle
.
repositories {
... other repositories above ...
maven { url 'https://jitpack.io' }
maven { url "https://maven.sumsub.com/repository/maven-public/" }
// for mobsdk versions 2.2.8+
maven { url = uri("https://maven.fpregistry.io/releases") }
}
Google Pay
Widget has optional Google Pay support. If you skip this step widget will still work, but the option to pay with Google Pay will not show up.
- To use Google Pay, first enable the Google Pay API by adding the following to your
AndroidManifest.xml
<application>
... your classes and meta data above ...
<meta-data
android:name="com.google.android.gms.wallet.api.enabled"
android:value="true" />
</application>
- Configure Google Pay before launching the widget
PaybisMobileWidget.setGPayConfiguration(
PaybisGPayConfiguration(
environment = PaybisGPayEnvironment.TEST, // TEST or PROD
merchantCountry = "GB",
merchantName = "Your Company Name"
merchantId = "Your Merchant ID"
)
)
After finishing tests for TEST
environment you'll need to request access to production GPay for your app here. Then after testing PROD
environment you are free to release your app with SDK integration.
Start widget
You can start PaybisMobileWidget with your requestId
any time. This method will start a new activity with crypto purchase flow. This flow includes user authentication.
PaybisMobileWidget.startWidget(
application,
PaybisEnvironment.SANDBOX,
"<generated_request_id>",
null,
false
)
Possible Environment
values:
enum class PaybisEnvironment {
SANDBOX, QA, PROD
}
Single sign-on flow
You can avoid user authentication by providing oneTimeToken
when starting widget
PaybisMobileWidget.startWidget(
application,
PaybisEnvironment.SANDBOX,
"<generated_request_id>",
"<generated_one_time_token>",
false
)
To get your oneTimeToken
you just need to create Request
passing passwordless
parameter as true
, according to API documentation.
Android SDK options
Name | Arguments | Details |
---|---|---|
startWidget | application - your Application instance [required]environment - widget environment [required]requestId - generated unique requestId [required]oneTimeToken - generated one-time token [optional] | used to open the widget UI |
closeWidget | n/a | used to close the widget UI |
SDK Events
Name | Arguments | Details |
---|---|---|
PaymentInitiated | - | Issued when a user has initiated the payment in the widget (relevant for Frictionless sell crypto flow) |
SDK API Usage Examples
The examples below are related to the above table. The following list is not meant to be a guide but simply demonstrates a possible usage of the SDK
class ExampleActivity : AppCompatActivity() {
private val vm by viewModels<ExampleViewModel>()
...
override fun onStart() {
...
// Here should be your logic to retreive `requestId` and `oneTimeToken` (if needed)
vm.requestCreated
.onEach { request ->
startWidget(request.requestId, request.oneTimeToken)
}
.launchIn(lifecycleScope)
}
private fun startWidget(requestId: String, oneTimeToken: String?) {
// some logic to define which environment you want to use
val paybisEnv =
if (BuildConfig.FLAVOR == "prod") PaybisEnvironment.PROD
else PaybisEnvironment.SANDBOX
PaybisMobileWidget.startWidget(
application,
paybisEnv,
requestId,
oneTimeToken,
)
}
}
In frictionless Offramp flow, you can react to the payment being initiated and close the widget when the following event is sent:
PaybisMobileWidget.setPaymentInitiatedListener {
PaybisMobileWidget.closeWidget()
}
There is also an event that is sent when the widget is closed:
PaybisMobileWidget.setCloseWidgetListener {
// react to the event here
}
Updated about 1 month ago