Virtual Instruments

Introduction

Virtual Instruments provide a Virtual Bank Account linked to customer balance account.

During customer onboarding Virtual Account can be auto-assigned and linked to customer's balance. If Virtual Account is not auto-assigned, assignment can be requested later using the provided methods.

Key Features

• Get Virtual Account information.
• Request assignment of new Virtual Account.
• Track Virtual Account assignment process.

Prerequisites

Before integrating the Virtual 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 VirtualInstrumentService instance in your app as shown below:

Kotlin

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

val virtualInstrumentService = Wallet.getInstance().getVirtualInstrumentService()

Swift

import PaysafeWallet

let virtualInstrumentService = Wallet.instance.virtualInstrumentService

Retrieve Virtual Instruments

To retrieve all virtual instruments associated with a specific account, use Get Customer Accounts functionality provided by the ProfileService.

Get Supported Virtual Instrument Types

Kotlin

Use getSupportedTypes method to retrieve the supported types of virtual instruments for the account represented by the VirtualInstrumentTypeList object.

val accountId =  "acde070d-8c4c-4f0d-9d8a"

val supportedTypes = virtualInstrumentService.getSupportedTypes(accountId)

Swift

Use getSupportedTypes method to retrieve the supported types of virtual instruments for the account represented by the VirtualInstrumentTypeList object.

let accountID = "acde070d-8c4c-4f0d-9d8a"

virtualInstrumentService.getSupportedTypes(accountID: accountID, completion: { result in
  switch result {
  case .success(let supportedTypes):
    // Display supported types
  case .failure(let error):
    // Handle error
  }
})

Get status of all Virtual Instrument Request

Kotlin

Use getAllRequestStatuses method to retrieve the list of virtual instrument assignment request statuses of the account represented by the VirtualInstrumentsRequestStatusParameters object.

 val virtualInstrumentsParameters = VirtualInstrumentsRequestStatusParameters(
     limit = 10,
     offset = 0,
     accountId = "12345",
     instrumentType = null // filters instruments of specific type i.e. VirtualInstrumentType.US_BANK_ACCOUNT
 )

val requests = virtualInstrumentService.getAllRequestStatuses(virtualInstrumentsParameters)

Swift

Use getAllRequestStatuses method to retrieve the list of virtual instrument assignment request statuses of the account represented by the VirtualInstrumentsRequestStatusParameters object.

let virtualInstrumentsParameters = VirtualInstrumentsRequestStatusParameters(
     limit: 10,
     offset: 0,
     accountID: "12345",
     instrumentType: nil // filters instruments of specific type i.e. .usBankAccount
 )

virtualInstrumentService.getAllRequestStatuses(parameters: virtualInstrumentsParameters, completion: { result in
  switch result {
  case .success(let requests):
    // Display virtual instrument statuses
  case .failure(let error):
    // Handle error
  }
})

Get status of Virtual Instrument assignment request

Kotlin

Use getRequestStatus method to retrieve the status of a given virtual instrument assignment request.

val virtualInstrumentRequestId = "acde070d-8c4c-4f0d-9d8a"

val request = virtualInstrumentService.getRequestStatus(virtualInstrumentRequestId)

Swift

Use getRequestStatus method to retrieve the status of a given virtual instrument assignment request.

let virtualInstrumentRequestID = "acde070d-8c4c-4f0d-9d8a"

virtualInstrumentService.getRequestStatus(virtualInstrumentRequestID: virtualInstrumentRequestID, completion: { result in
  switch result {
  case .success(let virtualInstrumentRequestStatus):
    // Display virtual instrument status
  case .failure(let error):
    // Handle error
  }
})

Request assignment of new Virtual Instrument

Kotlin

Use requestVirtualInstrument method to request a new virtual instrument by passing the VirtualInstrumentRequest object.

val virtualInstrumentRequest = VirtualInstrumentRequest(
    accountId = "12345",
    instrumentType = VirtualInstrumentType.US_BANK_ACCOUNT,
)

val virtualInstrumentRequest = virtualInstrumentService.requestVirtualInstrument(virtualInstrumentRequest)

Swift

Use requestVirtualInstrument method to request a new virtual instrument by passing the VirtualInstrumentRequest object.

let virtualInstrumentRequest = VirtualInstrumentRequest(
    instrumentType: .usBankAccount,
    accountID: "12345",
)

virtualInstrumentService.requestVirtualInstrument(request: virtualInstrumentRequest, completion: { result in
  switch result {
  case .success(let virtualInstrumentRequestStatus):
    // Display virtual instrument request
  case .failure(let error):
    // Handle error
  }
})