Skip to main content

Deposits

Introduction​

The Deposit Service enables seamless integration for managing deposits within your mobile application. Whether you're developing a wallet app, e-commerce platform, or payment gateway, this service allows you to handle various deposit-related activities in a secure and efficient manner. Key features include flexible payment methods, supporting a variety of options such as bank transfers, cards, and alternative methods like Paysafecash and Pago Efectivo. It ensures secure transactions by leveraging Paysafe’s robust infrastructure. The service also offers customizable workflows, allowing you to adapt deposit flows to fit your application's requirements, including handling redirects, fees, and 3DS authentication. Furthermore, it provides efficient management, enabling you to easily manage deposits with comprehensive APIs.

Key Features:​

  • Simulate a deposit to check fees and validate deposit details without creating an actual transaction.
  • Perform necessary validations and initiate a deposit process.
  • Confirm the deposit and move it to the processing stage, finalizing the payment flow.
  • Access a list of available deposit methods for the customer (e.g., bank cards or bank accounts).

Prerequisites​

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

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

val deposits = Wallet.getInstance().getDepositService()

Deposit Workflow Overview​

Deposit mobile overviewDeposit mobile overviewDeposit mobile overviewDeposit mobile overview

1. Get Deposit Options:​

The getOptions endpoint retrieves a list of all available deposit options for the customer. These options refer to different methods by which a deposit can be made, such as using a bank card, bank account, or alternative methods like Paysafecash.

try {
    val depositOptions = deposits.getOptions()
    // Handle depositOptions
} catch (exception: Exception) {
    // handle error
}

2. Get payment instruments (optional):​

To create a deposit, you may need to specify the paymentInstrumentReference if the chosen deposit option requires it. After retrieving the available deposit options via the getOptions endpoint, which provides a list of PaymentOptionDetails, identify whether the deposit method requires a payment instrument. If so, use the PaymentInstrumentService and call the getAll method with the corresponding instrument type to retrieve the user's payment instruments. After selecting an instrument, save its details to be used when initiating the deposit. For deposit methods that don't require a payment instrument, proceed directly with the selected option.

3. Deposit steps:​

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

1. Preview Deposit

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

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

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

2. Create Deposit

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

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

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

3. Confirm Deposit

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

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

Outcome: The deposit moves to the PROCESSING state, and depending on the payment method, you may need to handle redirection or 3DS authentication.

Deposit types:​

The Paysafe Wallet SDK supports multiple types of deposits to cater to different user preferences and payment methods. Below are the primary deposit types you can integrate into your application:

ACH Deposits​

Automated Clearing House (ACH) deposits allow customers to transfer funds directly from their bank account to the Paysafe Wallet. This method is ideal for larger transactions and for users who prefer using their bank accounts rather than cards.

ACH Deposit

Steps for creating ACH deposit:

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

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

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

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

// Step 1 - Preview.

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

val depositId: String
try {
    val customerDeposit = deposits.preview(depositRequest)
    depositId = customerDeposit.id
} catch (exception: Exception) {
    // handle exception
    return
}

// Step 2 - Create.

val depositCreate = DepositCreate(
    depositId = depositId,
    paymentProperties = null,
    paymentInstrument = null
)

try {
    deposits.create(depositCreate)
} catch (exception: Exception) {
    // handle exception
    return
}

// Step 3 - Confirm.

val depositConfirm = DepositConfirm(
    depositId = depositId,
    paymentProperties = null
)
try {
    deposits.confirm(depositConfirm)
} catch (exception: Exception) {
    // handle exception
    return
}
warning

To perform ACH deposits, a VERIFIED bank account is required. If you haven't added a bank account yet, see how to do it here.

Pago Efectivo Deposits​

Pago Efectivo is a popular payment method in Latin America that allows customers to generate a voucher, which can then be paid at authorized payment locations such as banks or convenience stores.

Pago Efectivo Deposit

Steps for creating Pago deposit:

Step 1. Begin by calling the preview method and supplying the necessary information. Ensure to include a valid ReturnLink to facilitate redirection back to the client application in the event of a redirect action. Additionally, save the deposit id from the response to proceed with the next steps.

Step 2. Then call the create method with the saved deposit id.

Step 3. Finally call the confirm method with the same deposit id. After the deposit is confirmed, you will receive an action REDIRECT / .redirect in CustomerDeposit response object. To complete the deposit, you should use redirectUrl to redirect the user to the payment provider's page.

A CustomerDeposit object.

// Step 1 - Preview.

val depositRequest = DepositRequest(
    amount = 100,
    currencyCode = "PEN",
    paymentOption = PaymentOptionType.PAGO_EFECTIVO,
    paymentInstrumentReference = null,
    merchantRefNum = "2b01127a-4929-4d0e-b9cb-a29a8d1c499c",
    returnUrls = listOf(
        ReturnLink(
            rel = ReturnUrl.Rel.DEFAULT_REL,
            href = "https://example.com",
            method = ReturnUrl.Method.GET
        )
    ),
    paymentProperties = null
)

val depositId: String
try {
    val customerDeposit = deposits.preview(depositRequest)
    depositId = depositPreview.id
} catch (exception: WalletException) {
    // handle exception
    return
}

// Step 2 - Create.

val depositCreate = DepositCreate(
    depositId = depositId,
    paymentProperties = null,
    paymentInstrument = null
)

try {
    deposits.create(depositCreate)
} catch (exception: WalletException) {
    // handle exception
    return
}

// Step 3 - Confirm.

val depositConfirm = DepositConfirm(
    depositId = depositId,
    paymentProperties = null
)

try {
    val deposit = deposits.confirm(depositConfirm)
    val redirectUrl = deposit.redirectUrl?.href
    // Handle redirect by open it in WebView or external browser
} catch (exception: WalletException) {
    // handle exception
    return
}

Card Deposits​

Card deposits allow customers to deposit funds using debit or credit cards (such as Visa or Mastercard). The Paysafe Wallet supports both stored card information and new card entries, making it easy for returning and new customers alike to fund their accounts.

warning

To make card deposits, you must be PCI DSS compliant, which allows access to cardholder data. If you are not PCI DSS compliant, you should use CardDeposit service, which provides native flow for processing card deposits.

Card Deposit With New Card

Steps for creating deposit with existing card:

Step 1. Begin by calling the preview method and supplying the necessary information, paymentInstrumentReference should be null/nil since we will add new card in next step. Ensure to include a valid ReturnLink to facilitate redirection back to the client application in the event of a redirect action. Additionally, save the deposit id from the response to proceed with the next steps.

Step 2. Collect the card details (PAN, Expiration date and CVV) from the client, then invoke the create method using the saved deposit ID, new card instrument and CVV. If you want to save the card, you can add CARD_SAVE_INSTRUMENT/.cardSaveInstrument property with value true in the paymentProperties.

Step 3. Call the confirm method with the deposit ID. After confirming the deposit, the response may include a redirect action to complete a 3DS challenge. To finalize the deposit, use the redirectUrl to direct the user to the appropriate 3DS page.

// Step 1 - Preview.

val depositRequest = DepositRequest(
 amount = 100,
 currencyCode = "USD",
 paymentOption = PaymentOptionType.CARD,
 paymentInstrumentReference = null,
 merchantRefNum = "2b01127a-4929-4d0e-b9cb-a29a8d1c499c",
 returnUrls = listOf(
     ReturnLink(
         rel = ReturnLinkType.DEFAULT,
         href = "https://www.example.com",
         method = HttpRequestMethod.GET
     )
 ),
 paymentProperties = null
)

val depositId: String
try {
 val customerDeposit = deposits.preview(depositRequest)
 depositId = depositPreview.id
} catch (exception: WalletException) {
 // handle exception
 return
}

// Step 2 - Create.

val cardPaymentInstrument = CardPaymentInstrument(
 pan = "4111111111111111",
 cardHolderName = null,
 bankName = null,
 expiryDate = CardExpiryDate(year = 28, month = 9),
 description = null
)

val depositCreate = DepositCreate(
 depositId = depositId,
 paymentProperties = listOf(
     PaymentProperty(
         key = PaymentPropertyKey.CARD_CVV,
         value = "245"
     ),
     PaymentProperty(
         key = PaymentPropertyKey.CARD_SAVE_INSTRUMENT,
         value = "true"
     )
 ),
 paymentInstrument = cardPaymentInstrument
)

try {
 customerDeposit = deposits.create(depositCreate)
} catch (exception: WalletException) {
 // handle exception
 return
}

// Step 3 - Confirm.

val depositConfirm = DepositConfirm(
 depositId = depositId,
 paymentProperties = null
)
try {
 val customerDeposit = deposits.confirm(depositConfirm)
 // Handle successful deposit confirmation
} catch (exception: WalletException) {
 // handle exception
 return
}
Card Deposit With Existing Card

Steps for creating deposit with existing card:

Step 1. Begin by calling the preview method and supplying the necessary information. Ensure to include a valid ReturnLink to facilitate redirection back to the client application in the event of a redirect action. Additionally, save the deposit id from the response to proceed with the next steps.

Step 2. Collect the card CVV from the client, then invoke the create method using the saved deposit id and CVV.

Step 3. Call the confirm method with the deposit ID. After confirming the deposit, the response may include a redirect action to complete a 3DS challenge. To finalize the deposit, use the redirectUrl to direct the user to the appropriate 3DS page.

val existingCardId = "11123"

// Step 1 - Preview.

val depositRequest = DepositRequest(
    amount = 100,
    currencyCode = "USD",
    paymentOption = PaymentOptionType.CARD,
    paymentInstrumentReference = PaymentInstrumentReference(
        id = existingCardId,
        instrumentType = InstrumentType.CARD
    ),
    merchantRefNum = "2b01127a-4929-4d0e-b9cb-a29a8d1c499c",
    returnUrls = listOf(
        ReturnLink(
            rel = ReturnLinkType.DEFAULT,
            href = "https://www.example.com",
            method = HttpRequestMethod.GET
        )
    ),
    paymentProperties = null
)

val depositId: String
try {
   val customerDeposit = deposits.preview(depositRequest)
   depositId = customerDeposit.id
} catch (exception: WalletException) {
    // handle exception
    return
}

// Step 2 - Create.

val depositCreate = DepositCreate(
    depositId = depositId,
    paymentProperties = listOf(
        PaymentProperty(
            key = PaymentPropertyKey.CARD_CVV,
            value = "245"
        )
    ),
    paymentInstrument = null
)

try {
    deposits.create(depositCreate)
} catch (exception: WalletException) {
    // handle exception
    return
}

// Step 3 - Confirm.

val depositConfirm = DepositConfirm(
    depositId = depositId,
    paymentProperties = null
)
try {
   val customerDeposit = deposits.confirm(depositConfirm)
    // Handle successful deposit confirmation
} catch (exception: WalletException) {
    // handle exception
    return
}

Paysafecash Deposits​

Paysafecash is an innovative alternative deposit method for customers who prefer to pay with cash. This method allows customers to initiate an online deposit and then complete the payment by visiting a physical location where Paysafecash is accepted.

Paysafecash Deposit

Steps for creating Paysafecash deposit:

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

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

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

// Step 1 - Preview.

val depositRequest = DepositRequest(
    amount = 100,
    currencyCode = "USD",
    paymentOption = PaymentOptionType.PAYSAFECASH,
    paymentInstrumentReference = null,
    merchantRefNum = "2b01127a-4929-4d0e-b9cb-a29a8d1c499c",
    returnUrls = null,
    paymentProperties = null
)

val depositId: String
try {
   val customerDeposit = deposits.preview(depositRequest)
   depositId = customerDeposit.id
} catch (exception: WalletException) {
    // handle exception
    return
}

// Step 2 - Create.

val depositCreate = DepositCreate(
    depositId = depositId,
    paymentProperties = null,
    paymentInstrument = null
)

try {
    deposits.create(depositCreate)
} catch (exception: WalletException) {
    // handle exception
    return
}

// Step 3 - Confirm.

val depositConfirm = DepositConfirm(
    depositId = depositId,
    paymentProperties = null
)
try {
    val deposit = deposits.confirm(depositConfirm)
    deposit.paymentDetails.forEach {
        when (it) {
            is PaymentDetailsKey.PAYSAFECASH_BARCODE_TYPE -> {
               val barcodeType = it.value
               // Handle barcode type
            }
            is PaymentDetailsKey.PAYSAFECASH_BARCODE_VALUE -> {
                val barcodeValue = it.value
               // Handle barcode value
            }
        }
    }
} catch (exception: WalletException) {
    // handle exception
}
Paysafecash Locations

Use getPaysafecashLocations method to retrieve a list of physical locations where Paysafecash can be used.

To retrieve the list of locations you should use PaysafecashLocationRequest object.

val paysafecashRequest = PaysafecashLocationRequest(
    latitude = 30.249,
    longitude = -81.529,
    radius = 1000, // in meters
    limit = 100
)

try {
   val paysafeLocations = deposits.getPaysafecashLocations(paysafecashRequest)
   // Display locations
} catch (exception: Exception) {
    // Handle error
}

Additional Methods​

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

Get Deposits List​

Use getAll method to retrieve a list of deposits by passing the GetDepositsParameters. If no parameters are passed, the last 10 deposits will be returned by default.

val getDepositsParameters = GetDepositsParameters(
    limit = 10,
    merchantRefNum = "2b01127a-4929-4d0e-b9cb-a29a8d1c499c",
    offset = 10,
    slipId = "123"
)
try {
    val result = deposits.getAll(getDepositsParameters)
} catch (exception: Exception) {
    // handle error
}

Get Single Deposit​

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

val depositId = "123"
try {
    val deposit = deposits.get(depositId)
} catch (exception: Exception) {
    // handle error
}