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

Transfer steps:

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

1. Preview Transfer

The preview method is the first step in the transfer process. It allows you to validate the transfer parameters before actually creating the transfer. 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).

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

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

note

The customer must have enough balance in the requested currency to complete the transfer. The recipient customer must exist in the system and must not be restricted.

Kotlin

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

val transferPreview = transferService.preview(transferRequest)

Swift

let transferRequest = Wallet.CustomerTransferRequest(amount: 100,
                                                     currencyCode: "USD",
                                                     recipient: .init(email: "user@example.com"),
                                                     merchantRefNum: "2b01127a-4929-4d0e-b9cb-a29a8d1c499c",
                                                     fxQuote: "404679be-ccbf-4528-b880-e14cc5041753",
                                                     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. Create Transfer

Once the transfer has been previewed, the create method is called 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
  }
})

3. Confirm Transfer

After the transfer has been successfully created and validated, the confirm method is used 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
            }
        })

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
  }
})