Transfers

Introduction

The Transfer Service offers a streamlined solution for handling transfers within your mobile application. It enables efficient transfer management, facilitates Strong Customer Authentication (SCA) when required, and allows you to review applicable fees. This simplifies the process of integrating and managing transfer transactions, making it easy to maintain a smooth and secure experience within your app.

Key Features:

• Simulate a transfer to check fees and validate transfer details without creating an actual transaction.
• Perform necessary validations and initiate a transfer process.
• Confirm the transfer and move it to the processing stage, finalizing the payment flow.
• Retrieve a list of past transactions or view details of a specific transaction.

Prerequisites

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

Kotlin

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

val transferService = Wallet.getInstance().getTransferService()

Swift

import PaysafeWallet

let transferService = Wallet.instance.transferService

Transfer Workflow Overview

Sender Workflow

Recipient Workflow

1. Preview transfer

The transfer process starts with the preview method, which serves as the first step in validating the transfer details before proceeding further. This step creates a transfer in PREVIEW state, which does not perform any transaction in the Paysafe Wallet system. Instead, it checks the transfer's configuration, such as recipient, fees and FX (currency exchange) amount (if applicable). You could transfer money via email, mobile number or customerID.

note

The customer must have enough balance in the requested currency to complete the transfer.

Kotlin

The preview method is called with a CustomerTransferRequest object, which contains all the necessary information for the transfer.

val transferRequest = CustomerTransferRequest(
  amount = 200,
  currencyCode = "USD",
  recipient = CustomerTransferRecipient(
    customerId = null,
    email = "user@example.com"
  ),
  merchantRefNum = "2b01127a-4929-4d0e-b9cb-a29a8d1c499c",
  transferDetails = TransferDetails(
    reason = TransferReason.PEER_TRANSFER,
    description = "Transfer money"
  )
)

val transferPreview = transferService.preview(transferRequest)

Swift

The preview method is called with a CustomerTransferRequest object, which contains all the necessary information for the transfer.

let transferRequest = Wallet.CustomerTransferRequest(amount: 100,
                                                     currencyCode: "USD",
                                                     recipient: .init(email: "user@example.com"),
                                                     merchantRefNum: "2b01127a-4929-4d0e-b9cb-a29a8d1c499c",
                                                     transferDetails: .init(reason: .peerTransfer,
                                                                            description: "Transfer money"))

transferService.preview(transferRequest: transferRequest, completion: { result in
  switch result {
  case .success(let transferPreview):
    // Handle transferPreview
  case .failure(let error):
    // Handle error
  }
})

2. Complete transfer

To move forward and complete the transfer, different steps are required based on whether the nextStatus of the preview response is SCHEDULED or PENDING.

Handle PENDING status

Step 1: Once the transfer has been previewed, you need to use the create method to validate and move the transfer to the PENDING state. At this point, all necessary checks are performed, and the system prepares the transfer for processing.

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

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

Kotlin

val transferCreate = TransferCreate(transferId = "urn:transfer:01HNDA4FJJTN4TK66WK4251SWH")

val transfer = transferService.create(transferCreate)

Swift

let transferCreate = Wallet.TransferCreate(id: "urn:transfer:01HNDA4FJJTN4TK66WK4251SWH")

transferService.create(transferCreate: transferCreate, completion: { result in
  switch result {
  case .success(let transfer):
    // Handle transfer
  case .failure(let error):
    // Handle error
  }
})

Step 2: After the transfer has been successfully created and validated, the second step is using the confirm method to transition the transfer into the PROCESSING state. This state indicates that the payment is being processed and the transfer is actively moving through the system.

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

Outcome: The transfer moves to PROCESSING state. However, if Strong Customer Authentication (SCA) is required, the transfer 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 Transfer 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 TransferConfirm parameter.

Kotlin

val transferId = "urn:transfer:01HNDA4FJJTN4TK66WK4251SWH"
val transferConfirm = TransferConfirm(transferId)

runCatching {
    transferService.confirm(transferConfirm)
}.onSuccess { transfer ->
    transfer.scaDetails?.let { scaDetails ->
        // solve SCA challenge with these details
        // as described in https://docs.paysafe.com/docs/embedded-wallets/strong-customer-authentication
        // repeat the confirm call once the SCA challenge is solved

        val scaDetailsRequest = ScaAuthenticationEventRequest(
            eventId = scaDetails.eventId,
            walletOperationId = scaDetails.walletOperationId,
        )

        transferService.confirm(
            TransferConfirm(
                transferId = transferId,
                paymentProperties = null,
                scaDetails = scaDetailsRequest
            )
        )
    } ?: // If the received transfer does not contain SCA details, the transfer is confirmed
}

Swift

let transferService = Wallet.instance.transferService
        let transferConfirm = Wallet.TransferConfirm(id: "urn:transfer:01HNDA4FJJTN4TK66WK4251SWH")

        transferService.confirm(transferConfirm: transferConfirm, completion: { result in
            switch result {
            case .success(let transfer):
                if transfer.action == .sca, let scaDetails = transferConfirm.scaDetails {
                    // solve SCA challenge with these details
                    // as described in https://docs.paysafe.com/docs/embedded-wallets/strong-customer-authentication
                    // repeat the confirm call once the SCA challenge is solved
                    let scaDetailsRequest = Wallet.SCAAuthenticationEventRequest(
                        eventID: scaDetails.eventID,
                        walletOperationID: scaDetails.walletOperationID
                    )

                    transferService.confirm(transferConfirm: Wallet.TransferConfirm(id: transferConfirm.id,
                                                                                    scaDetails: scaDetailsRequest),
                                            completion: { result in
                        // Handle result
                    })


                } else {
                    // Handle transfer
                }

            case .failure(let error):
                // Handle error
            }
        })

Feature in development

Handle SCHEDULED status

Step 1: Once the transfer has been previewed, use the schedule method to validate and move the transfer to the SCHEDULED state.

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

Outcome: The transfer moves to SCHEDULED state.

note

This operation might require Strong Customer Authentication (SCA). Please read Strong Customer Authentication for more information on the process. If the Transfer object returned by schedule 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 schedule method again, providing scaDetails in the TransferSchedule parameter.

Kotlin

val transferId = "urn:transfer:01HNDA4FJJTN4TK66WK4251SWH"
val transferSchedule = TransferSchedule(transferId)

runCatching {
    transferService.schedule(transferSchedule)
}.onSuccess { transfer ->
    transfer.scaDetails?.let { scaDetails ->
        // solve SCA challenge with these details
        // as described in https://docs.paysafe.com/docs/embedded-wallets/strong-customer-authentication
        // repeat the schedule call once the SCA challenge is solved

        val scaDetailsRequest = ScaAuthenticationEventRequest(
            eventId = scaDetails.eventId,
            walletOperationId = scaDetails.walletOperationId,
        )

        transferService.schedule(
            TransferSchedule(
                transferId = transferId,
                paymentProperties = null,
                scaDetails = scaDetailsRequest
            )
        )
    } ?: // If the received transfer does not contain SCA details, the transfer is scheduled
}

Swift

let transferService = Wallet.instance.transferService
let transferSchedule = Wallet.TransferSchedule(id: "urn:transfer:01HNDA4FJJTN4TK66WK4251SWH")

transferService.schedule(transferSchedule: transferSchedule, completion: { result in
     switch result {
     case .success(let transfer):
         if transfer.action == .sca, let scaDetails = transferSchedule.scaDetails {
             // solve SCA challenge with these details
             // as described in https://docs.paysafe.com/docs/embedded-wallets/strong-customer-authentication
             // repeat the schedule call once the SCA challenge is solved
             let scaDetailsRequest = Wallet.SCAAuthenticationEventRequest(
                 eventID: scaDetails.eventID,
                 walletOperationID: scaDetails.walletOperationID
             )

             transferService.schedule(transferSchedule: Wallet.TransferSchedule(id: transferSchedule.id,
                                                                                scaDetails: scaDetailsRequest),
                                      completion: { result in
                                          / Handle result
                                      })

             } else {
                 // Handle transfer
             }

     case .failure(let error):
          // Handle error
     }
})

Step 2: For the recipient to successfully receive the transfer, they should accept it using the accept method. If necessary, both you and the recipient have the option to cancel the scheduled transfer using the cancel method.

Purpose: To allow the recipient to accept the transfer and complete the process, or to provide the option to cancel before acceptance.

Outcome: If accepted, the funds are transferred to the recipient’s account. If canceled, the transfer is voided, and the funds return to the sender’s account.

note

Accepting transfer is a two-way operation and occurs only when money is being transferred between two accounts for the first time.

Kotlin

// Accepting a scheduled transfer
val transferAccept = TransferAccept(transferId = "urn:transfer:01HNDA4FJJTN4TK66WK4251SWH")
val transfer = transferService.accept(transferAccept)

// Canceling a scheduled transfer
val transferCancel = TransferCancel(transferId = "urn:transfer:01HNDA4FJJTN4TK66WK4251SWH")
val transfer = transferService.cancel(transferCancel)

Swift

// Accepting a scheduled transfer
let transferAccept = Wallet.TransferAccept(id: "urn:transfer:01HNDA4FJJTN4TK66WK4251SWH")
transferService.accept(transferAccept: transferAccept, completion: { result in
  switch result {
  case .success(let transfer):
    // Handle transfer
  case .failure(let error):
    // Handle error
  }
})

// Canceling a scheduled transfer
let transferCancel = Wallet.TransferCancel(id: "urn:transfer:01HNDA4FJJTN4TK66WK4251SWH")
transferService.cancel(transferCancel: transferCancel, completion: { result in
  switch result {
  case .success(let transfer):
    // Handle transfer
  case .failure(let error):
    // Handle error
  }
})

Additional Methods

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

Get Transfers List:

Kotlin

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

val getTransferParameters = GetTransferParameters(
    limit = 10,
    merchantRefNum = "2b01127a-4929-4d0e-b9cb-a29a8d1c499c",
    offset = 10,
    slipId = "123"
)

val transfersList = transferService.getAll(getTransferParameters)

Swift

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

let getTransferParameters = Wallet.GetTransferParameters(limit: 10,
                                                         merchantRefNum: "2b01127a-4929-4d0e-b9cb-a29a8d1c499c",
                                                         offset: 10,
                                                         slipID: "123")

transferService.getAll(getTransferParameters: getTransferParameters, completion: { result in
  switch result {
  case .success(let transfers):
    // Handle transfers
  case .failure(let error):
    // Handle error
  }
})

Get a Single Transfer:

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

Kotlin

val transferId = "urn:transfer:01HNDA4FJJTN4TK66WK4251SWH"

val transfer = transferService.get(transferId)

Swift

let transferId = "urn:transfer:01HNDA4FJJTN4TK66WK4251SWH"

transferService.get(id: transferId, completion: { result in
  switch result {
  case .success(let transfer):
    // Handle transfer
  case .failure(let error):
    // Handle error
  }
})