Venmo Integration - iOS

API key

For information about how to get your API key from the Business Portal, see Before you begin.

In order to test the Venmo integration using the Demo app, you have to modify some constants representing the API key and the account id associated with the Venmo payment method.

• Open Example/LotteryTicket/LotteryTicket/Managers/PaymentManager.swift file. 

• Modify apiKey string to contain your API key
• Modify venmoAccountId string to contain the account id associated with the Venmo payment method. 

To test the Venmo integration on iOS mTest environment, you have to setup the SDK with the .test parameter. 

Also, keep in mind that testing in mTest environment requires the Venmo Test app, and not the production one (the one from AppStore). Otherwise, the authorization will fail. The Venmo test app doesn't require any credentials - any email and any password will work.

The iOS test app is available through PayPal's AppCenter and you need to reach out to integrations@paysafe.com for access. 

Swift Package Manager 

In Xcode, select File > Add Packages… and enter https://github.com/paysafegroup/paysafe_sdk_ios_payments_api as the repository URL and select the latest version number.

Tick the checkboxes for the specific Paysafe libraries you wish to include. In this case, PaysafeVenmo.

If you look at your app target, you will see that the Paysafe libraries you chose are automatically linked as a frameworks to your app (see General > Frameworks, Libraries, and Embedded Content). 

// In your Swift file
import PaysafeVenmo

Cocoapods

// Add in your Podfile

pod 'PaysafePaymentsSDK'

// Or you can import only a single module

pod 'PaysafePaymentsSDK/PaysafeVenmo'

// In your Swift file
import PaysafePaymentsSDK

You can check the Github releases to see what is the latest version: https://github.com/paysafegroup/paysafe_sdk_ios_payments_api. 

After Paysafe iOS package is integrated into your project, setup PaysafeSDK on application start.

import PaysafeVenmo
PaysafeSDK.shared.setup(  
apiKey: apiKey,   
environment: .test
)
{ result in
    switch result {
    case .success:
        print("[Paysafe SDK] initialized successfully")
    case let .failure(error):
        print("[Paysafe SDK] initialize failure \(error.displayMessage)")
    }
}

The setup function creates and initializes the Paysafe iOS SDK. Pass the following parameters during its initialization from the application:

API Key

The Base64-encoded version of the single-use token API key is used to authenticate with the Payment Hub REST API. Please refer “Before You Being” on how to obtain the API Keys

Note that this key can be used only to generate single-use tokens for use with the Payments API and has no other API access rights (such as for taking payments). Consequently, it can be exposed publicly in the user's browser.

Environment

The environment string is used to select the environment to use for tokenization. The accepted environments are LIVE (the Paysafe Production environment) and TEST (the Paysafe Merchant Test or Sandbox environment).

Do not use real card numbers or other payment instrument details in the Merchant Test environment. It is not compliant with Payment Card Industry Data Security Standards (PCI-DSS) and does not protect cardholder/payee information. Any upload of real cardholder data is strictly prohibited, as described in the Terms of Use.

Callback error object

The following table describes the contents of the error object:

Setup errors

Setup your app for context switching

To include Venmo module in your App, it is necessary to include add some configuration in your app.

The following steps will enable your App to open the Venmo app, and Venmo app to redirect to your App.

1. In Xcode, click on your project in the Project Navigator and navigate to App Target > Info> URL Types
2. Click [+] to add a new URL type
3. Under URL Schemes, enter your app switch return URL scheme. This scheme must start with your app's Bundle ID and be dedicated to Braintree app switch returns.
   • For example, if the app bundle ID is com.your-company.your-app, then your URL scheme could be com.your-company.your-app.payments.

Set your return URL

To set the return URL call the setURLScheme in willConnectTo method in the UISceneDelegate.

For example, if the app bundle ID is com.your-company.your-app, then your URL scheme could be com.your-company.your-app.payments.

func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {       
    PSVenmoContext.setURLScheme(scheme: "com.your-company.your-app.payments")
}

Set your URL Contexts

To set the url contexts call the openURLContexts in openURLContexts method in the UISceneDelegate

func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        PSVenmoContext.setURLContexts(contexts: URLContexts)
}

Location Permissions

The Paysafe iOS SDK uses device and browser location data for fraud detection, Apple requires a NSLocationWhenInUseUsageDescription key in your Info.plist if your app contains code referencing location APIs.

Even If your app does not request location data directly, you will still need to include a NSLocationWhenInUseUsageDescriptionplist entry.

<key>NSLocationWhenInUseUsageDescription</key>
<string>Your location is required for our App</string>

Allowlist Venmo URL scheme

You must add the following to the query schemes allowlist in your app's info.plist:

<key>LSApplicationQueriesSchemes</key>
<array>
  <string>com.venmo.touch.v2</string>
</array>

Initialize

When you want to process a Venmo payment request, you would first initialize PSVenmoContext.

The initialize() method signature is the following:

/// Initializes the PSVenmoContext.
///
/// - Parameters:
///   - currencyCode: Currency code
///   - accountId: Account id
///   - completion: PSVenmoContextInitializeBlock
public static func initialize(
        currencyCode: String,
        accountId: String,
        completion: @escaping PSVenmoContextInitializeBlock
    )

This tokenize method returns a PaymentHandle result, which will resolve to a single-use payment handle representing the user's sensitive card data. This handle can be used by the Payments API to take payments. Single-use handles are valid for only 15 minutes and are not consumed by verification. See Payments with a Handle for more details.

Tokenize callback signature

The tokenize function has the following signature:

/// Paysafe Core Venmo tokenize method. 
///
/// - Parameters:
///   - options: PSVenmoTokenizeOptions
///   - completion: PSTokenizeBlock
public func tokenize(
    using options: PSVenmoTokenizeOptions,
    completion: @escaping PSTokenizeBlock
)

The tokenize() function provides a convenient method for tokenizing sensitive card data, allowing secure payment processing. Upon invocation, this function returns a completion handler that resolves to a single-use payment handle, which represents the user's sensitive card data. This handle can be utilized by the Payments API for payment transactions. It's important to note that single-use handles are valid for only 15 minutes and are not consumed during verification.

Parameters:

• options: An instance of PSVenmoTokenizeOptions containing various parameters for tokenization, such as the payment amount, transaction type, account ID and Venmo configuration.
• completion: A completion handler of type PSTokenizeBlock, which is executed once the tokenization process is complete. The completion handler provides the single-use payment handle or any error encountered during the tokenization process.

PSVenmoTokenizeOptions

The PSVenmoTokenizeOptions structure provides a comprehensive set of options for configuring the tokenization process. These options include:

Usage example

/// Payment amount in minor units
let amount = totalPrice * 100
let options = PSVenmoTokenizeOptions(
    amount: amount,
    currencyCode: "USD",
    transactionType: .payment,
    merchantRefNum: PaysafeSDK.shared.getMerchantReferenceNumber(),
    accountId: "<account-id>",
    venmo: VenmoAdditionalData(
        consumerId = "cosumer@gmail.com",|
        merchantAccountId": "BankAccount2",
        profileId": 1953896702662410200
     )
)
venmoContext.tokenize(
    using: options
) { [weak self] tokenizeResult in
    DispatchQueue.main.async { [weak self] in
        guard let self else { return }
        switch tokenizeResult {
        case let .success(paymentHandleResponse):
          /// handle paymentHandleResponse
        case let .failure(error):
            alertTexts = ("Error", "\(error.localizedDescription)")
            presentAlert = true
        }
    }
}
 

Tokenization exceptions