Skip to main content

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:

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

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

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.

Verify instrument diagramVerify instrument diagramVerify instrument diagramVerify instrument diagram

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

val deepLinkUri: Uri = intent.data

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

Peruvian Bank Accounts (CCI)​

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

val cciBankAccount = CciBankAccount(
    accountNumber = "00232616269435820577",
    accountType = AccountType.CHECKING
)

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

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.

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

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

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
}

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:

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

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

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.

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
}

Delete Single Payment Instrument​

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

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

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