Payment Instruments

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.

Kotlin

Use the following code to obtain an instance of PaymentInstrumentService:

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

Swift

Use the following code to obtain an instance of PaymentInstrumentService:

import PaysafeWallet

let instrumentsService = Wallet.instance.paymentInstrumentService

Get Payment Instruments

Kotlin

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 can be passed instead of PaymentInstrumentsParameters if there are no filters applied.

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())
}

Swift

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. nil can be passed instead of PaymentInstrumentsParameters if there are no filters applied.

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

Add Peruvian Bank Account (CCI)

Feature in development

Kotlin

Use add method to add a new CciBankAccount.

val cciBankAccount = CciBankAccount(
  id: null,
  customerId: null,
  status: null,
  accountNumber: "10239485761029384756"
)

try {
  val instrument = instrumentsService.add(paymentInstrument: cciBankAccount)
  Log.d(TAG, instrument.toString())
} catch (exception: Exception) {
  Log.d(TAG, exception.toString())
}

Swift

Use add method to add a new CciBankAccount.

let cciBankAccount = Wallet.CciBankAccount(id: nil,
                                           customerId: nil,
                                           status: nil,
                                           accountNumber: "10239485761029384756")

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

Get Payment Instrument

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

Kotlin

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())
}

Swift

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

Kotlin

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.

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())
}

Swift

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.

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

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.

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)
  Log.d(TAG, instrumentVerification.toString())
} catch (exception: Exception) {
  Log.d(TAG, exception.toString())
}

Swift

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.

Kotlin

try {
  val instrumentVerifications = instrumentsService.getVerification(instrumentVerification.id)
  Log.d(TAG, instrumentVerifications.toString())
} catch (exception: Exception) {
  Log.d(TAG, exception.toString())
}

Swift

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

Kotlin

Use getAllVerifications method to retrieve a list of instrument verification sessions. null 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

 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())
}

Swift

Use getAllVerifications method to retrieve a list of instrument verification sessions. 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

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.

Kotlin

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())
}

Swift

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