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.

CustomerDataVerificationRequest​

ParameterData typeDescriptionExample
attributeCustomerDataVerificationAttributeRequired. The customer attribute being validated in the particular verification process.CustomerDataVerificationAttribute(CustomerDataVerificationAttributeType.EMAIL, "john.doe@example.com")/CustomerDataVerificationAttribute(type: .email, value: "john.doe@paysafe.com")
val emailDataVerificationRequest = CustomerDataVerificationRequest(
    CustomerDataVerificationAttribute(
        CustomerDataVerificationAttributeType.EMAIL,
        "john.doe@paysafe.com"
    )
)

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.

CustomerDataVerificationAttemptRequest​

ParameterData typeDescriptionExample
attributeCustomerDataVerificationAttributeRequired. The customer attribute being validated in the particular verification process.CustomerDataVerificationAttribute(CustomerDataVerificationAttributeType.EMAIL, "john.doe@example.com")/CustomerDataVerificationAttribute(type: .email, value: "john.doe@paysafe.com")
notificationTypeCustomerDataVerificationNotificationTypeRequired. The mechanism used to deliver the customer attribute verification information.CustomerDataVerificationNotificationType(CustomerDataVerificationNotificationMethod.OTP, CustomerDataVerificationNotificationChannel.EMAIL)/CustomerDataVerificationNotificationType(method: .otp, value: .email)
valueStringRequired. The value transmitted through the secure notification method and channel to confirm the specific customer attribute.123456
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 to the method in order to verify and set up customer's wallet. This will ensure that they meet all necessary requirements. Once successful, customer can be authenticated using provided contact method and credentials. The CustomerIdentifiers consists of two CustomerIdentifier objects. Based on brand configurations, 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 and Onboard a customer for more details.

CustomerPersonRequest​

ParameterData typeDescriptionExample
titleStringOptional. Personal title."Mr"
firstNameStringRequired. The first name of the customer."John"
lastNameStringRequired. The last name of the customer."Doe"
birthDateStringRequired. The birth date of the customer in YYYY-MM-DD format."1981-08-24"
nationalityStringOptional. The nationality of the customer in ISO-3166 Alpha 2 format."GB"
occupationOccupationOptional. The occupation of the customer.Occupation.ARCHITECTURE_CARTOGRAPHY_SURVEYOR / Occupation.architectureCartographySurveyor
vulnerabilities .List<Vulnerability>?/[Vulnerability]Optional. A list of vulnerabilities associated with the customer.listOf(Vulnerability.GAMBLING_ADDICTION) / [.gamblingAddiction]
customerIdentifiersCustomerIdentifiersRequired. The customer identifiers used in the onboarding process.CustomerIdentifiers(CustomerIdentifier("john.doe@paysafe.com", "06bdcd2c"), CustomerIdentifier("+359897765463", "06bdcd2c")) / CustomerIdentifiers(email: CustomerIdentifier(identifier: "john.doe@paysafe.com", code: "06bdcd2c"), mobile: CustomerIdentifier(identifier: "+359897765463", code: "06bdcd2c"))
customerCredentialsCustomerCredentialsRequired. The credentials of the customer.CustomerCredentials("Password1.") / CustomerCredentials(password: "Password1.")
currencyCodeStringRequired. Currency alphabetic code as specified by ISO 4217.EUR
addressAddressRequired. The address of the customer.Address("GB", null, "London", "E1 8RU", "221b Baker St", null) / Address(countryCode: "GB", stateProvince: nil, city: "London", postalCode: "E1 8RU", address1: "221b Baker St", address2: nil)
termsAndConditionsBoolean/BoolRequired. A boolean indicating whether the customer has accepted the terms and conditions.true
isPoliticallyExposedBoolean/BoolOptional. A boolean indicating whether whether the customer is a Politically Exposed Person (PEP).false
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
    ),
    customerIdentifiers = CustomerIdentifiers(
        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,
    ),
    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())
}