Skip to main content

Wallet Setup

note

This API is available only to merchants with standaloneWallet access and walletSetup scope to the config token.

Introduction
Feature in development
​

The Wallet Setup service exposes operations for setting up the Paysafe Embedded Wallet:

  • Initiate a customer data verification process
  • Submit a customer data verification attempt
  • Onboard a new customer
  • Change customer credentials

Use the following code to obtain an instance of WalletSetupService:

val walletSetup = Wallet.getInstance().getWalletSetupService()

Initiate a customer data verification process​

Use initiateDataVerificationProcess method to initiate a verification process for a specific customer attribute, such as email or mobile. The method requires an object of type CustomerDataVerificationRequest. More information about it, you can find here for Android and here for iOS.

val emailDataVerificationRequest = CustomerDataVerificationRequest(
    CustomerDataVerificationAttribute(
        CustomerDataVerificationAttributeType.EMAIL,
        "john.doe@paysafe.com"
    ),
    CustomerDataVerificationFlow.WALLET_SETUP
)

try {
  val emailDataVerificationResponse = walletSetup.initiateDataVerificationProcess(emailDataVerificationRequest)
  Log.d(TAG, response.toString())
} catch (exception: Exception) {
  Log.d(TAG, exception.toString())
}

After calling the initiateDataVerificationProcess you will receive a CustomerDataVerificationResponse object, containing a verificationId attribute. This attribute is key for submitting a customer data verification attempt and onboarding a customer. See Submit a customer data verification attempt and Onboard a customer.

Submit a customer data verification attempt​

Use submitDataVerificationAttempt method to submit a verification attempt for a specific customer attribute tied to an already initiated verification process.

The method submitDataVerificationAttempt requires a verificationId. You should obtain it from the CustomerDataVerificationResponse object that you received after calling initiateDataVerificationProcess. This verification id is the link to the data verification process initiated by the customer. The second parameter, required by the submitDataVerificationAttempt method is a CustomerDataVerificationAttemptRequest object. A more detailed information about the object, you can find here for Android and here for iOS.

val dataVerificationAttemptRequest = CustomerDataVerificationAttemptRequest(
    attribute = CustomerDataVerificationAttribute(
        type = CustomerDataVerificationAttributeType.EMAIL,
        value = "john.doe@example.com"
    ),
    notificationType = CustomerDataVerificationNotificationType(
        method = CustomerDataVerificationNotificationMethod.OTP,
        channel = CustomerDataVerificationNotificationChannel.EMAIL
    ),
    value = "123456"
)

try {
  val dataVerificationAttemptResponse = walletSetup.submitDataVerificationAttempt(
      emailDataVerificationResponse.verificationid,
      dataVerificationAttemptRequest
  )
  Log.d(TAG, response.toString())
} catch (exception: Exception) {
  Log.d(TAG, exception.toString())
}

Onboard a customer​

Use onboardCustomer method to onboard a new customer. You need to provide an object of type CustomerPersonRequest. Details about the object can be found here for Android and here for iOS. By onboarding a customer, we will ensure that they meet all the necessary requirements to use the wallet. Once successful, customer can be authenticated using provided contact method and credentials. The CustomerIdentifiersOnboarding consists of two CustomerIdentifier objects. Both identifiers must be provided in the request. Each identifier has a verificationId which will be used to ensure that the customer has been verified through the data verification process. See Inititate a customer data verification process and Submit a customer data verification attempt and Onboard a customer for more details.

val customerPersonRequest = CustomerPersonRequest(
    title = null,
    firstName = "John",
    lastName = "Doe",
    birthDate = "1981-08-24",
    nationality = "GB",
    occupation = Occupation.ARCHITECTURE_CARTOGRAPHY_SURVEYOR,
    vulnerabilities = listOf(
        Vulnerability.PHYSICAL_DISABILITY
    ),
    additionalAttributes = mapOf("KEY_ALIGNED_WITH_PAYSAFE" to "VALUE_GIVEN_BY_CUSTOMER"),
    customerIdentifiers = CustomerIdentifiersOnboarding(
        email = CustomerIdentifier(
            value = "john.doe@paysafe.com",
            verificationId = emailDataVerificationResponse.verificationId
        ),
        mobile = CustomerIdentifier(
            value = "+359897765463",
            verificationId = mobileDataVerificationResponse.verificationId
        )
    ),
    customerCredentials = CustomerCredentials(
        password = "Password1.",
        pin = null,
    ),
    currencyCode = "EUR",
    address = Address(
        countryCode = "GB",
        stateProvince = null,
        city = "London",
        postalCode = "E1 8RU",
        address1 = "221b Baker St",
        address2 = null,
    ),
    preferences = Preferences(
        marketing = MarketingPreferences(
            receivePushNotifications = true,
            receiveMarketingEmails = true,
            receiveMarketingSms = true,
            receiveSocialAds = false,
            receiveTargetedAds = false,
            receiveThirdPartyAds = false,
        ),
        data = DataPreferences(
            consentForTargetedAds = true,
            consentForAnalytics = false,
            consentForPerformanceTracking = true
        )
    ),
    termsAndConditions = true,
    isPoliticallyExposed = false,
)

try {
    val customerInfo = walletSetup.onboardCustomer(customerPersonRequest)
    Log.d(TAG, customerInfo.toString())
} catch(e: Exception) {
    Log.d(TAG, exception.toString())
}

Change customer credentials​

Use changeCredentials method to change a specific customer credential, such as password. You need to provide an object of type ChangeCustomerCredentialsRequest to the method. The CustomerIdentifiers consists of two CustomerIdentifier objects. At least one identifier must be provided in the request. Each identifier has a verificationId which will be used to ensure that the customer has been verified through the data verification process. See Inititate a customer data verification process and Submit a customer data verification attempt for more details how to obtain the verificationId parameter. The CustomerCredentials is a struct representing the credentials you wish to change (e.g. password).

ChangeCustomerCredentialsRequest​

ParameterData typeDescriptionExample
customerIdentifiersCustomerIdentifiersRequired. The client's email or mobile.CustomerIdentifiers(CustomerIdentifier("john.doe@paysafe.com", "06bdcd2c"), null) / CustomerIdentifiers(email: CustomerIdentifier(value: "john.doe@paysafe.com", verificationId: "06bdcd2c"), mobile: nil)
customerCredentialsCustomerCredentialsRequired. The new client credentials.CustomerCredentials("Password1.") / CustomerCredentials(password: "Password1.")
val changeCustomerCredentialsRequest = ChangeCustomerCredentialsRequest(
    CustomerIdentifiers(
        email = CustomerIdentifier(
            value = "john.doe@paysafe.com",
            verificationId = "06bdcd2c-0cce-4b36-97ec-281c8f5d743c"
        ),
        mobile = null
    ),
    CustomerCredentials(
        password = "Password1."
    )
)

try {
    walletSetup.changeCredentials(changeCustomerCredentialsRequest)
    Log.d(TAG, "Credentials changed successfully")
} catch (exception: Exception) {
    Log.d(TAG, exception.toString())
}