Search Overlay
Searchbox clear search filters ESC
Filter PreferencesClear

No results found

Payment Instruments

asdf

Introduction

The Payment Instrument service exposes operations for managing payment instruments. Payment instruments are used for Deposit and Withdrawal operations. Only VERIFIED instruments can be used for withdrawal:

  • Get payment instruments list
  • Get single payment instrument
  • Verify payment instrument
  • Get instrument verification sessions
  • Delete single payment instrument

Use the following code to obtain an instance of PaymentInstrumentService:

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

let instrumentsService = Wallet.instance.paymentInstrumentService

Different types of instruments are represented by the InstrumentType enumeration.

InstrumentType

Android iOS Description
SEPA_BANK_ACCOUNT .sepaBankAccount SEPA bank account
UK_BANK_ACCOUNT .ukBankAccount UK bank account
US_BANK_ACCOUNT .usBankAccount US bank account
CARD .card Payment card

Get Payment Instruments

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

PaymentInstrumentsParameters

Parameter Data type Description Example
instrumentType InstrumentType Optional parameter for filtering by instrument type SEPA_BANK_ACCOUNT/.sepaBankAccount
paymentOption PaymentOptionType Optional parameter for filtering by payment option BANK_TRANSFER/.bankTransfer

PaymentOptionType

Enum representing different types of payment options.

Android iOS Description
RAPID_TRANSFER .rapidTransfer Rapid transfer
BANK_TRANSFER .bankTransfer Bank transfer
CARD .card Card 
val paymentInstrumentParameters = PaymentInstrumentsParameters(
    instrumentType = InstrumentType.SEPA_BANK_ACCOUNT,
    paymentOption = PaymentOption.BANK_TRANSFER
)

try {
    val instruments = instrumentsService.getAll(paymentInstrumentParameters)
    Log.d(TAG, instruments.toString())
} catch (exception: Exception) {
    Log.d(TAG, exception.toString())
}
let parameters = Wallet.PaymentInstrumentsParameters(instrumentType: .usBankAccount,
                                                     paymentOption: .bankTransfer)

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

Get Payment Instrument

Use get method to retrieve a single instrument with specific type and identifier.

PaymentInstrumentParameters

Parameter Data type Description Example
instrumentId String Required parameter that represents the id of the instrument "123456"
instrumentType InstrumentType Required parameter that represents the instrument type SEPA_BANK_ACCOUNT/.sepaBankAccount 
val paymentInstrumentParameters = PaymentInstrumentParameters(
    instrumentId = "123456",
    instrumentType = InstrumentType.SEPA_BANK_ACCOUNT
)

try {
    val instrument = instrumentsService.get(paymentInstrumentParameters)
    Log.d(TAG, instrument.toString())
} catch (exception: Exception) {
    Log.d(TAG, exception.toString())
}
let parameters = Wallet.PaymentInstrumentParameters(instrumentId: "123456",
                                                    instrumentType: .sepaBankAccount)

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

Verify Payment Instrument

Use startVerification method to create new instrument verification session and obtain an InstrumentVerification object. The startVerification method accepts a InstrumentType parameter and a String parameter returnUrl. This is the URL that will be started by the system browser on flow completion. This link should deep link back to the client application.

Important: It is responsibility of the client application 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.

InstrumentVerificationRequest

Parameter Data type Description Example
instrumentType InstrumentType Required parameter representing the instrument type SEPA_BANK_ACCOUNT/.sepaBankAccount
returnUrl String Required parameter. It is the URL to which users will be redirected after completing the required activities in Paysafe hosted UI "myapp://verification-completed" 
val instrumentVerificationRequest = InstrumentVerificationRequest(
    returnUrl = "myapp://verification-completed",
    instrumentType = InstrumentType.SEPA_BANK_ACCOUNT
)

try {
    val instrumentVerification = instrumentsService.startVerification(instrumentVerificationRequest)
    instrumentsService.openExternalVerificationFlow(requireActivity(), instrumentVerification)
} catch (exception: Exception) {
    Log.d(TAG, exception.toString())
}
let request = Wallet.InstrumentVerificationRequest(returnUrl: "myapp://verification-completed",
                                                   instrumentType: .usBankAccount)

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

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)
    Log.d(TAG, instrumentVerification.toString())
} catch (exception: Exception) {
    Log.d(TAG, exception.toString())
}
guard let deepLinkUrl = URLContexts.first?.url else { return }

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

Get Instrument Verification Session

Use getVerification method to retrieve previously created instrument verification session.

Parameter Data type Description Example
sessionId String Required parameter for the Instrument Verification Session ID, when it was created. instrumentVerification.id 
try {
    val instrumentVerifications = instrumentsService.getVerification(instrumentVerification.id)
    Log.d(TAG, instrumentVerifications.toString())
} catch (exception: Exception) {
    Log.d(TAG, exception.toString())
}
instrumentsService.getVerification(sessionId: instrumentVerification.id, completion: { result in
    switch result {
    case .success(let instrumentVerification):
        // Display instrument verification
    case .failure(let error):
        // Handle error
    }
})

Get Instrument Verification Sessions

Use getAllVerifications method to retrieve a list of instrument verification sessions. null/nil can be passed instead of InstrumentVerificationParameters.

InstrumentVerificationParameters

Parameter Data type Description Example
limit Int Optional parameter that limits the number of results 10
offset Int Optional parameter representing the Offset of the results 10
sessionStatus InstrumentVerificationStatus Optional parameter that is used to filter the Instrument Verification by status ACTIVE/.active

InstrumentVerificationStatus

Enum representing the current status of the session.

Android iOS Description
ACTIVE .active The initial session status
ONGOING_VERIFICATION .ongoingVerification Payment instrument is obtained and ongoing verification is in progress.
AWAITING_USER_INPUT .awaitingUserInput Waiting user input in order to continue the verification process.
COMPLETED .completed Verification process is completed, the instrument should be in either VERIFIED or REJECTED status.
FAILED .failed Instrument verification failed.

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
 val instrumentVerificationParameters = InstrumentVerificationParameters(
    limit = 10,
    offset = 10,
    sessionStatus = InstrumentVerificationStatus.ACTIVE
 )

try {
    val instrumentVerifications = instrumentsService.getAllVerifications(instrumentVerificationParameters)
    Log.d(TAG, instrumentVerifications.toString())
} catch (exception: Exception) {
    Log.d(TAG, exception.toString())
}
let parameters = WalletWallet.InstrumentVerificationParameters(limit: 10,
                                                               offset: 10,
                                                               sessionStatus: .active)

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

Delete Single Payment Instrument

Use delete method to remove specific payment instrument.

PaymentInstrumentParameters

Parameter Data type Description Example
instrumentId String Required parameter that represents the id of the instrument "123456"
instrumentType InstrumentType Required parameter that represents the instrument type SEPA_BANK_ACCOUNT/.sepaBankAccount 
val paymentInstrumentParameters = PaymentInstrumentParameters(
    instrumentId = "123456",
    instrumentType = InstrumentType.SEPA_BANK_ACCOUNT
)

try {
    val instrument = instrumentsService.delete(paymentInstrumentParameters)
    Log.d(TAG, instrument.toString())
} catch (exception: Exception) {
    Log.d(TAG, exception.toString())
}
let parameters = Wallet.PaymentInstrumentParameters(instrumentId: "123456",
                                                    instrumentType: .sepaBankAccount)

instrumentsService.delete(parameters: parameters, completion: { result in
    switch result {
    case .success(let instrument):
        // Display instrument
    case .failure(let error):
        // Handle error
    }
})
On this Page