Card Deposits

The card deposit service enables users to add funds to their account using either a new card or an existing card.

To initiate a deposit with an existing card, first use the preview method to create a deposit with a valid paymentInstrumentReference. Then, call the start method with the depositId obtained from the preview response. To initiate a deposit with a new card, call the preview method with null/nil for the paymentInstrumentReference property.

warning

In order to integrate the card deposit native flow a parameter scope pci-dss-1 is required when issuing SDK JWT token. More information about PCI DSS can be found here.

Use the following code to obtain an instance of CardDepositService:

Kotlin

val cardDeposits = Wallet.getInstance().getCardDepositService()

Swift

import PaysafeWallet

let cardDeposits = Wallet.instance.cardDepositService

Preview Card Deposit

Use preview method to create a card deposit for the current customer. Card Deposits are created in PREVIEW state. Card Deposits in PREVIEW state do not create an actual transaction in Paysafe Wallet system. It allows to check deposit parameters and display any present fees.

CardDepositRequest

Parameter	Data type	Description	Example
amount	Int	Required parameter for amount of deposit in minor units.	100
currencyCode	String	Required parameter for currency of the deposit. Format ISO 4217.	"USD"
paymentInstrumentReference	PaymentInstrumentReference	Optional parameter, reference to existing verified payment instrument.	PaymentInstrumentReference(...)
merchantRefNum	String	Optional parameter for merchant reference number.	"2b01127a-4929-4d0e-b9cb-a29a8d1c499c"

PaymentInstrumentReference

Parameter	Data type	Description	Example
id	String	Required parameter for payment instrument reference of the deposit.	"123"
instrumentType	InstrumentType	Required parameter for payment instrument type of the deposit.	InstrumentType.CARD/.card

InstrumentType

Enum class representing different types of payment instruments.

Android	iOS	Description
CARD	.card	Payment card.
SEPA_BANK_ACCOUNT	.sepaBankAccount	SEPA bank account.
UK_BANK_ACCOUNT	.ukBankAccount	UK bank account.
US_BANK_ACCOUNT	.usBankAccount	US bank account.
UNKNOWN	.unknown	Returned when no valid value was found.

Kotlin

val cardDepositRequest = CardDepositRequest(
    amount = 100,
    currencyCode = "USD",
    paymentInstrumentReference = PaymentInstrumentReference(
        id = "123",
        instrumentType = InstrumentType.CARD
    ),
    merchantRefNum = "2b01127a-4929-4d0e-b9cb-a29a8d1c499c"
)

try {
    val cardDepositPreview = cardDeposits.preview(cardDepositRequest)
    Log.d(TAG, cardDepositPreview.toString())
} catch (exception: Exception) {
    Log.d(TAG, exception.toString())
}

Swift

let cardDepositRequest = Wallet.CardDepositRequest(amount: 100,
                                                   currencyCode: "USD",
                                                   paymentInstrumentReference: .init(id: "123",
                                                                                     instrumentType: .card),
                                                   merchantRefNum: "2b01127a-4929-4d0e-b9cb-a29a8d1c499c")

cardDeposits.preview(cardDepositRequest: cardDepositRequest, completion: { result in
    switch result {
    case .success(let cardDepositPreview):
        // Handle cardDepositPreview
    case .failure(let error):
        // Handle error
    }
})

Start Card Deposit

Use start method to start a screen for result for the native card deposit flow. After the card deposit flow has finished, a result of type CardDepositResult is returned to the client application. Note that the status of the deposit may not be processed immediately. To check the status use Get Single Deposit.

When the flow is initiated, users must fill in the required fields. After submitting the card details, they may be required to complete a 3DS challenge.

To customize the appearance see UI Theme Configuration for Android and UI Appearance configuration for iOS.

CardDepositResult

Status of the card deposit flow.

Android	iOS	Description
Completed	.completed	The card deposit flow has been completed. This result does not inherently mean that the deposit has been successful.
TerminalFailure(val cardDepositError: CardDepositError)	.terminalFailure(Error)	Terminal failure of the deposit. When this error is received the deposit has failed and can't be retried.
NonTerminalFailure(val cardDepositError: CardDepositError)	.nonTerminalFailure(Error)	Non terminal failure of the deposit. When this error is received the deposit can be retried as long as it hasn't expired.
Cancelled	.cancelled	The card deposit flow has been cancelled.

CardDepositError

Kotlin

Parameter	Data type	Description	Example
code	CardDepositResultCode	Required parameter representing the code of the DepositError.	INTERNAL_ERROR
message	String	Optional parameter representing the message of the DepositError.	Some message

CardDepositResultCode

Enum class representing card deposit failure codes.

Value	Description
FAILED_TO_LOAD_ACCEPTED_CARDS	Failure to load accepted cards.
INTERNAL_ERROR	There has been an internal error.
NETWORK_ERROR	There has been a network error.

Swift

Enum class representing card deposit failure codes.

Value	Description
.failedToLoadAcceptedCardsError	Failure to load accepted cards.
.internalError	There has been an internal error.

Kotlin

In Android there are two ways to open a screen by using startActivityForResult method or registerForActivityResult:

// Start the card deposit screen for result
val depositId = "123"
cardDepositService.start(this@MainActivity, 100, depositId)

// Then, obtain the card deposit result in onActivityResult
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
  super.onActivityResult(requestCode, resultCode, data)
  if (requestCode == 100 && data != null) {
    val result = IntentCompat.getParcelableExtra(data, "EXTRA_CARD_DEPOSIT_RESULT", CardDepositResult::class.java)
    when (result) {
       CardDepositResult.Cancelled -> handleCancelled()
       is CardDepositResult.TerminalFailure -> handleTerminalFailure()
       is CardDepositResult.NonTerminalFailure -> handleNonTerminalFailure()
       CardDepositResult.Completed -> handleCompleted()
       else -> handleOtherResult()
      }
  }
}

// Alternatively, the registerForActivityResult API can be used
val launcher = registerForActivityResult(OpenStartCardDeposit()) { result ->
  when (result) {
    CardDepositResult.Cancelled -> handleCancelled()
    is CardDepositResult.TerminalFailure -> handleTerminalFailure()
    is CardDepositResult.NonTerminalFailure -> handleNonTerminalFailure()
    CardDepositResult.Completed -> handleCompleted()
    else -> handleOtherResult()
  }
}
launcher.launch(depositId)

Swift

A 'UIViewController' instance should be provided as the starting point for presenting the deposit flow.

Wallet.instance.cardDepositService.start(with: depositID,
                                         viewController: someViewController,  // Provide UIViewController instance here
                                         completion: { cardDepositResult in
                                             // Handle cardDepositResult
                                         })