Payment Instruments

Introduction

The Payment Instrument service streamlines the management of payment instruments by offering key functions such as adding, verifying, retrieving, and removing them. This service facilitates the development of secure and efficient payment workflows, giving users the tools to manage their financial operations smoothly and safely, while adapting to different financial needs.

Key Features

• Adding payment instruments to a user’s account, enabling them to deposit or withdraw funds.
• Simultaneously add and verify payment instruments, such as bank accounts, through third-party verification services.
• The Payment Instrument service ensures that all sensitive data related to payment instruments is stored securely in compliance with industry standards and regulations.

Prerequisites

Before integrating the Payment Instrument Service, ensure you have:

• A valid Paysafe account with appropriate permissions.
• Set up instructions for Paysafe SDK Android or iOS.

To get started, initialize the PaymentInstrumentService in your app as shown below:

Kotlin

import com.paysafe.wallet.android.core.wallet.Wallet

val instrumentsService = Wallet.getInstance().getPaymentInstrumentService()

Swift

import PaysafeWallet

let instrumentsService = Wallet.instance.paymentInstrumentService

Adding Payment Instruments

The section explains how to add and manage different types of payment instruments, highlighting specific methods and how they apply to various instruments.

Card instruments

Cards are added to the system when a deposit is made using the Deposit Service. If your application doesn't meet PCI DSS level 1 compliance requirements, you can use the Card Deposit Service. This service offers a fully integrated PCI DSS compliant user interface that also simplifies the card addition process.

US Bank Accounts

US bank accounts are added and verified through the startVerification method which ensures that the account is both securely verified and seamlessly integrated into your application, enhancing the overall user experience. This method creates a new verification session and returns an InstrumentVerification object. It accepts two parameters: InstrumentType and a returnUrl, which should deep link back to your application after the flow is completed.

Visual Overview: Payment Instrument Addition & Verification Process

Thе diagram illustrates the steps for adding and verifying US bank accounts, providing a clear overview of the process from start to finish.

Kotlin

Details about the InstrumentVerification object are available here.

val instrumentVerificationRequest = InstrumentVerificationRequest(
  returnUrl = "myapp://verification-completed",
  instrumentType = InstrumentType.US_BANK_ACCOUNT
)

try {
  val instrumentVerification = instrumentsService.startVerification(instrumentVerificationRequest)
  instrumentsService.openExternalVerificationFlow(requireActivity(), instrumentVerification)
} catch (exception: Exception) {
   // Handle exception
}

Swift

Details about the InstrumentVerification object are available here.

let request = Wallet.InstrumentVerificationRequest(
    returnUrl: "myapp://verification-completed",
    instrumentType: .usBankAccount
)

instrumentsService.startVerification(request: request) { result in
    switch result {
    case .success(let instrumentVerification):
        instrumentsService.openExternalVerificationFlow(instrumentVerification: instrumentVerification, completion: ...)
    case .failure(let error):
        // Handle error
    }
}

IMPORTANT

In order to use startVerification method you need to implement deep link handling, either with custom scheme or universal links.

After obtaining the session with startVerification, you should call openExternalVerificationFlow method to open the instrument verification flow in the system browser. Upon flow completion, the browser will redirect the customer to the provided deep link returnUrl.

After the customer has been redirected back to the application via the provided deep link, use completeExternalVerificationFlow method with the return URL as parameter to verify the status and retrieve an instrument verification session.

Kotlin

val deepLinkUri: Uri = intent.data

try {
  val instrumentVerification = instrumentService.completeExternalVerificationFlow(deepLinkUri)
} catch (exception: Exception) {
   // Handle exception
}

Swift

guard let deepLinkUrl = URLContexts.first?.url else { return }

instrumentsService.completeExternalVerificationFlow(returnUrl: deepLinkUrl) { result in
    switch result {
    case .success(let status):
        // Display instrument verification status
    case .failure(let error):
        // Handle error
    }
}

Peruvian Bank Accounts (CCI)

To add a Peruvian bank account (CCI) for seamless withdrawals via Pago Efectivo, the add method should be used.

Kotlin

val cciBankAccount = CciBankAccount(accountNumber: "10239485761029384756")

try {
  val instrument = instrumentsService.add(paymentInstrument: cciBankAccount)
} catch (exception: Exception) {
   // Handle exception
}

Swift

let cciBankAccount = Wallet.CciBankAccount(accountNumber: "10239485761029384756")

instrumentsService.add(paymentInstrument: cciBankAccount) { result in
    switch result {
    case .success(let instrument):
        // Handle the created CCI instrument
    case .failure(let error):
        // Handle error
    }
}

Managing Instrument Verification Sessions

For instruments that require verification, like US bank accounts, additional methods are available to manage the process. The startVerification method used to add US bank accounts returns an InstrumentVerification object, which is required for the following methods.

Get Instrument Verification Session

The getVerification method retrieves a previously created verification session using the session ID from the InstrumentVerification object.

Kotlin

try {
  val instrumentVerifications = instrumentsService.getVerification(instrumentVerification.id)
} catch (exception: Exception) {
   // Handle exception
}

Swift

instrumentsService.getVerification(sessionId: instrumentVerification.id) { result in
    switch result {
    case .success(let instrumentVerification):
        // Display instrument verification
    case .failure(let error):
        // Handle error
    }
}

Get Instrument Verification Sessions

To retrieve a list of instrument verification sessions use getAllVerifications method. null/nil can be passed instead of InstrumentVerificationParameters object.

You can achieve pagination by combining the limit and offset filters. For instance, implementing pagination with a page size of 10 results per page would involve configuring:

• Page 1: limit=10, offset=0
• Page 2: limit=10, offset=10
• Page 3: limit=10, offset=20

Kotlin

Details about the InstrumentVerificationParameters object are available here.

 val instrumentVerificationParameters = InstrumentVerificationParameters(
  limit = 10,
  offset = 10,
  sessionStatus = InstrumentVerificationStatus.ACTIVE
 )

try {
  val instrumentVerifications = instrumentsService.getAllVerifications(instrumentVerificationParameters)
} catch (exception: Exception) {
   // Handle exception
}

Swift

Details about the InstrumentVerificationParameters object are available here.

let parameters = Wallet.InstrumentVerificationParameters(
    limit: 10,
    offset: 10,
    sessionStatus: .active
)

instrumentsService.getAllVerifications(parameters: parameters) { result in
    switch result {
    case .success(let instrumentVerifications):
        // Display instrument verifications
    case .failure(let error):
        // Handle error
    }
}

Managing Payment Instruments

Regardless of how a payment instrument is added — whether through the add method (e.g., Peruvian bank accounts), the Deposit Service (e.g., cards), or the startVerification method (e.g., US bank accounts) — the following methods are available for managing all payment instruments:

Get Payment Instrument

To fetch details about a specific payment instrument by its identifier and type, use the get method:

Kotlin

val paymentInstrumentParameters = PaymentInstrumentParameters(
  instrumentId = "123456",
  instrumentType = InstrumentType.SEPA_BANK_ACCOUNT
)

try {
  val instrument = instrumentsService.get(paymentInstrumentParameters)
} catch (exception: Exception) {
   // Handle exception
}

Swift

let parameters = Wallet.PaymentInstrumentParameters(
    instrumentId: "123456",
    instrumentType: .sepaBankAccount
)

instrumentsService.get(parameters: parameters) { result in
    switch result {
    case .success(let instrument):
        // Display instrument
    case .failure(let error):
        // Handle error
    }
}

Get Payment Instruments

To retrieve a list of payment instruments use the getAll method. PaymentInstrumentsParameters is used to filter the response by instrument type using instrumentType and by payment option using paymentOption. If there are no filters applied null/nil can be passed instead of PaymentInstrumentsParameters.

Kotlin

Details about the PaymentInstrumentsParameters object are available here.

val paymentInstrumentParameters = PaymentInstrumentsParameters(
  instrumentType = InstrumentType.SEPA_BANK_ACCOUNT,
  paymentOption = PaymentOption.BANK_TRANSFER
)

try {
  val instruments = instrumentsService.getAll(paymentInstrumentParameters)
} catch (exception: Exception) {
   // Handle exception
}

Swift

Details about the PaymentInstrumentsParameters object are available here.

let parameters = Wallet.PaymentInstrumentsParameters(
    instrumentType: .usBankAccount,
    paymentOption: .bankTransfer
)

instrumentsService.getAll(parameters: parameters) { result in
    switch result {
    case .success(let instruments):
        // Display instruments
    case .failure(let error):
        // Handle error
    }
}

Delete Single Payment Instrument

To remove a specific payment instrument, use the delete method by providing its identifier and type:

Kotlin

val paymentInstrumentParameters = PaymentInstrumentParameters(
  instrumentId = "123456",
  instrumentType = InstrumentType.SEPA_BANK_ACCOUNT
)

try {
  val instrument = instrumentsService.delete(paymentInstrumentParameters)
} catch (exception: Exception) {
   // Handle exception
}

Swift

let parameters = Wallet.PaymentInstrumentParameters(
    instrumentId: "123456",
    instrumentType: .sepaBankAccount
)

instrumentsService.delete(parameters: parameters) { result in
    switch result {
    case .success(let instrument):
        // Display deleted instrument
    case .failure(let error):
        // Handle error
    }
}