# Market integration

TIP

This page explains the way to integrate serviceX with your platform for offering financial services. This page describes required procedures whilst API of Markets data sharing is optional. Please have a look at API of Markets data sharing if you are interested in leveraging your data to enhance UX.

# Overview

  1. [Backend] Check if your desired service (e.g., BNPL) is available
  2. [Backend] Create Order ID if it is BNPL usage
  3. [Frontend] Start serviceX flow
  4. [Backend] Handle callback from Credify
  5. [Backend + Frontend] Render BNPL completion page if it BNPL usage
  6. [Frontend] Render my products page

TIP

If you have not set up your account on serviceX Dashboard yet, please have a look at Getting Started.

# 1. [Backend] Check if your desired service is available

api key

  1. Generate an API key like the screenshot above (select claim-provider and organization)
  • You can check what scope is necessary in API docs
  1. Call Client Authentication API with your API key
  2. Call Offers List API with your desired product codes (one or more)
Product name Code
BNPL (consumer) consumer-financing:unsecured-loan:bnpl
Health insurance insurance:health-insurance:for-individual
Motorbike insurance insurance:automobile-insurance:motorbike
Homeowners insurance insurance:home-insurance:for-homeowner
Home insurance insurance:home-insurance:for-house
Co-Branded Credit Card credit-card:cbcc

If you do not see any available offers/products, you will have to contact us.

# 2. [Backend] Create Order ID if it is BNPL usage

This step is only for BNPL use case.

  1. Call BNPL Order Creation API with the client auth token
  2. Save the Order ID you have obtained in the step 1

This Order ID is used on the frontend (next step).

# 3. [Frontend] Start serviceX flow

serviceX bnpl

# If you do not embed our SDK into your platform

This option is only available for BNPL use.

If you do not use our frontend SDK, please navigate your user to serviceX page.

  • Production
    • https://passport.credify.one/bnpl?order_id=${Order ID}
  • Sandbox
    • https://sandbox-passport.credify.dev/bnpl?order_id=${Order ID}

# If you embed our SDK into your platform

# Set up SDK

Here is how to set up the mobile SDK. The installation is described here.

  • Kotlin
  • Swift
  • React Native
  • Web

If you have created a class that extends from Application class. You only add the below code to the onCreate() method. You can generate a new API key on serviceX Dashboard.

override fun onCreate() {
    super.onCreate()
    ...
    CredifySDK.Builder()
        .withApiKey([Your API Key])
        .withContext(this)
        .withEnvironment([Environment])
        .build()
    ...
}

Otherwise, you will need to create a new class that extends from Application class. In this example, it is named as DemoApplication.

...
class DemoApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        // Generates a singleton here
        CredifySDK.Builder()
            .withApiKey([Your API Key])
            .withContext(this)
            .withEnvironment([Environment])
            .build()
    }
    ...
}

AND update your AndroidManifest.xml file.

<application
    android:name=".DemoApplication"
    ...
    >
    ...
</application>

After creating the CredifySDK instance, you can access the singleton like following:

val credifySDK = CredifySDK.instance

# Kick off the serviceX flow

This process will render serviceX's UI for users to interact with financial services, such as insurance purchase, BNPL request.

  • Kotlin
  • Swift
  • React Native
  • Web

When a user wants to use one of the offers, you will do the following:

// Create one.credify.sdk.core.model.UserProfile object
val user = UserProfile(
    id = // Logged in user's ID in your service,
    name = Name(
        firstName = // Logged in user's first name,
        lastName = // Logged in user's last name,
        middleName = // Logged in user's middle name (Optional),
        name = // Logged in user'ss full name (Optional),
        verified = // Is logged in user's name verified?
    ),
    phone = Phone(
        phoneNumber = // Logged in user's phone number,
        countryCode = // Logged in user's phone country code,
        verified = // Is logged in user's phone number verified?
    ),
    email = // Logged in user's email,
    dob = // Logged in user's date of birth (Optional),
    address = // Logged user's address (Optional)
)

// Display an offer detail:
CredifySDK.instance.offerApi.showOffer(
    context = // Context,
    offer = // String, obtained in the step 1
    userProfile = // one.credify.sdk.core.model.UserProfile object,
    credifyId = // Logged in user's credify ID. If your user have created Credify account then it should not be null,
    marketName = // Your app name,
    pushClaimCallback = // CredifySDK.PushClaimCallback callback,
    offerPageCallback = // CredifySDK.OfferPageCallback callback
)

You will have to handle CredifySDK.PushClaimCallback for calling the data digest provisioning API if you use our data sharing feature. In addition to this, you will have to handle CredifySDK.OfferPageCallback, which is called when the offer detail page is closed.

CredifySDK.instance.offerApi.showOffer(
    context = // Context,
    offer = // String,
    userProfile = // one.credify.sdk.core.model.UserProfile object,
    credifyId = // Logged in user's credify ID,
    marketName = // Your app name,
    pushClaimCallback = object : CredifySDK.PushClaimCallback {
        // Necessary only if you use the data sharing feature 
        // Otherwise, you can leave it blank
        override fun onPushClaim(
            credifyId: String,
            user: UserProfile,
            resultCallback: CredifySDK.PushClaimResultCallback
        ) {
            // Code for calling your API to send data digest.
            // After the API successful API request, you will have to notify the Credify SDK. For example:
            resultCallback.onPushClaimResult(
                isSuccess = [true if success. Otherwise, pass false]
            )
        }
    },
    offerPageCallback = object : CredifySDK.OfferPageCallback {
        override fun onClose() {
            // Your code logic here
        }
    }
)

# 4. [Backend] Handle callback from Credify

When your user makes a transaction on Service Provider's context, you can receive a webhook to get notification.

Please refer to Webhook.

# 5. [Backend + Frontend] Render BNPL completion page if it BNPL usage

This step is necessary if you consume the BNPL service. You need to implement and expose this API endpoint.

Right after a BNPL provider confirms BNPL request is completed, this endpoint is called. You are supposed to redirect a user to your payment completion page. This request might have error_message in its query parameter if it has failed.

# 6. [Frontend] Render my products page

You can embed product management feature into your service. Your users do not have to go to another app to see the status of products (BNPL status, insurance policy information).

  • Kotlin
  • Swift
  • React Native

If you want to render BNPL specific page, you can try this out.

package one.credify.marketsample.bnplandroid

import android.content.Context
import android.os.Bundle
import android.util.Log
import androidx.appcompat.app.AppCompatActivity
import one.credify.sdk.CredifySDK
import one.credify.sdk.core.model.ProductType
import one.credify.sdk.core.model.UserProfile

class MainActivity : AppCompatActivity() {
    private val mTag = "MainActivity"

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
    }

    private fun showBNPLDetail(context: Context, user: UserProfile) {
        CredifySDK.instance.passportApi.showServiceInstance(
            context = context,
            userProfile = user,
            productTypeList = listOf(ProductType.BNPL_CONSUMER),
            callback = object : CredifySDK.PageCallback {
                override fun onClose() {
                    Log.i(mTag, "Page showed")
                }

                override fun onShow() {
                    Log.i(mTag, "Page closed")
                }
            }
        )
    }
}
Last Updated: 10/31/2022, 3:19:15 AM