Withdrawals

Introduction

The Withdrawal Service provides a seamless solution for managing withdrawals within your mobile application. It offers efficient management capabilities, allowing you to easily oversee withdrawals through comprehensive APIs, handle redirects, Strong Customer Authentication(SCA) and preview fees. This makes it simple to integrate and manage all aspects of withdrawal transactions in your application.

Key Features:

• Simulate a withdrawal to check fees and validate withdrawal details without creating an actual transaction.
• Perform necessary validations and initiate a withdrawal process.
• Confirm the withdrawal and move it to the processing stage, finalizing the payment flow.
• Access a list of available withdrawal methods for the customer.

Prerequisites

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

Kotlin

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

val withdrawals = Wallet.getInstance().getWithdrawalService()

Swift

import PaysafeWallet

let withdrawals = Wallet.instance.withdrawalService

Withdrawal Workflow Overview

1. Get Withdrawal Options:

The getOptions method retrieves a list of all available withdrawal options for the customer. These options refer to different methods by which a withdrawal can be made, such as using a bank account or SafetyPay(Feature in development).

Kotlin

try {
  val withdrawalOptions: List<PaymentOptionDetails> = withdrawals.getOptions()
} catch (exception: Exception) {
  // handle exception
}

Swift

withdrawals.getOptions(completion: { result in
  switch result {
  case .success(let withdrawalOptions):
    // Handle withdrawalOptions
  case .failure(let error):
    // Handle error
  }
})

2. Get payment instruments:

To create a withdrawal, you will need to specify the paymentInstrumentReference. After retrieving the available withdrawal options via the getOptions method, which provides a list of PaymentOptionDetails, use PaymentInstrumentService.getAll to fetch instruments for that option. After selecting an instrument, save its details to be used when initiating the withdrawal.

3. Withdrawal steps:

To create a withdrawal, you will follow a three-step process: preview, create, and confirm. Each method plays a specific role in moving the withdrawal through its lifecycle. Here's an explanation of what each method does:

1. Preview Withdrawal

The preview method is the first step in the withdrawal process. It allows you to validate the withdrawal parameters before actually creating the withdrawal. This step creates a withdrawal in PREVIEW state, which does not perform any transaction in the Paysafe Wallet system. Instead, it checks the withdrawal's configuration, such as fees and available options.

Purpose: To validate the withdrawal parameters (e.g., amount, payment option, etc.) and provide the ability to display fees without committing to a transaction.

Outcome: A Withdrawal object is returned, which is needed for the next steps.

2. Create Withdrawal

Once the withdrawal has been previewed, the create method is called to validate and move the withdrawal to the PENDING state. At this point, all necessary checks are performed, and the system prepares the withdrawal for processing.

Purpose: To perform the required validations and transition the withdrawal into a state where it is ready for processing.

Outcome: The withdrawal is now in PENDING state, meaning it is fully validated and ready to proceed to the next step, confirmation.

3. Confirm Withdrawal

After the withdrawal has been successfully created and validated, the confirm method is used to transition the withdrawal into the PROCESSING state. This state indicates that the payment is being processed by the payment provider, and the withdrawal is actively moving through the system.

Purpose: To confirm the withdrawal and initiate the actual processing of the payment.

Outcome: The withdrawal moves to PROCESSING state. However, if Strong Customer Authentication (SCA) is required, the withdrawal will remain in the PENDING state until the SCA challenge is completed.

note

This operation might require Strong Customer Authentication (SCA). Please read Strong Customer Authentication for more information on the process. If the Withdrawal object returned by confirm has action: PaymentCompletionAction.SCA, the scaDetails will contain the SCA authentication properties needed to complete the process. Follow the steps outlined in Submit the SCA Authentication to confirm the event. After the SCA event is accepted, invoke confirm method again, providing scaDetails in the WithdrawalConfirm parameter.

Withdrawal types:

The Paysafe Wallet SDK currenty supports ACH Withdrawal. Below is described how you can integrate it into your application.

ACH Withdrawals

Automated Clearing House (ACH) withdrawals allow customers to transfer funds directly from the Paysafe Wallet to their bank account.

ACH Withdrawal

Steps for creating ACH withdrawal:

Step 1: Begin by calling the preview method and supplying the necessary information, paymentInstrumentReference should be provided. Additionally, save the withdrawal id from the response to proceed with the next steps.

Step 2: Then call the create method with the saved withdrawal ID.

Step 3: Finally call the confirm method with the same withdrawal ID.

Kotlin

// Use the id of the instrument you want to use
// Instrument id can be retrieved from PaymentInstrumentService
val bankAccountId = "11112"

// Step 1 - Preview.

val withdrawalRequest = WithdrawalRequest(
    amount = 100,
    currencyCode = "USD",
    paymentOption = PaymentOptionType.BANK_TRANSFER,
    paymentInstrumentReference = PaymentInstrumentReference(
        id = bankAccountId,
        instrumentType = InstrumentType.US_BANK_ACCOUNT
    ),
    merchantRefNum = "2b01127a-4929-4d0e-b9cb-a29a8d1c499c",
    paymentProperties = null
)

val withdrawalId: String
try {
    val withdrawal = withdrawals.preview(withdrawalRequest)
    withdrawalId = withdrawal.id
} catch (exception: Exception) {
    // handle exception
    return
}

// Step 2 - Create.

val withdrawalCreate = WithdrawalCreate(
    id = withdrawalId,
    paymentProperties = null
)

try {
    withdrawals.create(withdrawalCreate)
} catch (exception: Exception) {
    // handle exception
    return
}

// Step 3 - Confirm.

val withdrawalConfirm = WithdrawalConfirm(
    id = withdrawalId,
    paymentProperties = null,
    scaDetails = null
)
try {
    withdrawals.confirm(withdrawalConfirm)
} catch (exception: Exception) {
    // handle exception
    return
}

Swift

// Use the id of the instrument you want to use
// Instrument id can be retrieved from PaymentInstrumentService
let bankAccountID = "11112"

// Step 1 - Preview.

let withdrawalRequest = Wallet.WithdrawalRequest(
    amount: 100,
    currencyCode: "USD",
    paymentOption: .bankTransfer,
    paymentInstrumentReference: .init(
        id: bankAccountID,
        instrumentType: .usBankAccount
    ),
    merchantRefNum: "2b01127a-4929-4d0e-b9cb-a29a8d1c499c",
    paymentProperties: nil
)

var withdrawalId: String

withdrawals.preview(withdrawalRequest: withdrawalRequest) { result in
    switch result {
    case .success(let withdrawal):
        // Handle successful withdrawal preview
        withdrawalId = withdrawal.id
    case .failure(let error):
        // Handle error
    }
}

// Step 2 - Create.
let withdrawalCreate = Wallet.WithdrawalCreate(id: withdrawalId)

withdrawals.create(withdrawalCreate: withdrawalCreate) { result in
    switch result {
    case .success(let withdrawal):
        // Handle successful withdrawal creation
    case .failure(let error):
        // Handle error
    }
}

// Step 3 - Confirm.
let withdrawalConfirm = Wallet.WithdrawalConfirm(id: withdrawalId)

withdrawals.confirm(withdrawalConfirm: withdrawalConfirm) { result in
    switch result {
    case .success(let withdrawal):
        // Handle successful withdrawal confirmation
    case .failure(let error):
        // Handle error
    }
}

warning

To perform ACH withdrawal, a VERIFIED bank account is required. If you haven't added a bank account yet, see how to do it here feature to add and verify your bank account.

Additional Methods

In addition to the main methods for initiating withdrawal, the Withdrawal API provides several other helpful features to manage and retrieve withdrawal information.

Get a Withdrawals List:

Kotlin

Use getAll method to retrieve a list of withdrawals by passing the GetWithdrawalsParameters. Details about the object can be found here. If no parameters are passed, it will return the last 10 withdrawals by default.

val getWithdrawalsParameters = GetWithdrawalsParameters(
  limit = 10,
  merchantRefNum = "19481996",
  offset = 10,
  slipId = "123"
)

try {
  val result = withdrawals.getAll(getWithdrawalsParameters)
} catch (exception: Exception) {
  // handle exception
}

Swift

Use getAll method to retrieve a list of withdrawals by passing the GetWithdrawalsParameters. If no parameters are passed, it will return the last 10 withdrawals by default.

let getWithdrawalsParameters = Wallet.GetWithdrawalsParameters(limit: nil,
                                                               merchantRefNum: "19481996",
                                                               offset: nil,
                                                               slipID: nil)

withdrawals.getAll(getWithdrawalsParameters: getWithdrawalsParameters, completion: { result in
  switch result {
  case .success(let withdrawals):
    // Handle withdrawals
  case .failure(let error):
    // Handle error
  }
})

Get a Single Withdrawal:

To retrieve details of a specific withdrawal use get method with its id. Ensure that the withdrawal id is valid to receive the correct data.

Kotlin

val withdrawalId = "123"

try {
  val withdrawal = withdrawals.get(withdrawalId)
} catch (exception: Exception) {
  // handle Exception
}

Swift

let withdrawalId = "123"

withdrawals.get(id: withdrawalId, completion: { result in
  switch result {
  case .success(let withdrawal):
    // Handle withdrawal
  case .failure(let error):
    // Handle error
  }
})