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

1. Firstly you’ll need to ask Paybis team for your personal private token to SDK’s Maven repository
2. 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)
        }
    }
}

3. 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"
}

4. 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>

5. 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.

1. 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>

2. 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

SDK Events

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
}