Venmo Integration
Prerequisites
API key
For information about how to get your API key from the Business Portal, see Before you begin.
Using the Demo app
To test the Venmo integration using the Demo app, you need to modify certain constants representing the API key and the account ID associated with the Venmo payment method:
-
open example/src/main/java/com/paysafe/example/util/Consts.kt file.
- modify API_KEY string to contain your API key.
- modify VENMO_ACCOUNT_ID string to contain the account id associated with the Venmo payment method.
Using the TEST environment
To test your Venmo integration on Android in the TEST environment, you must set up the SDK with the PSEnvironment.TEST parameter (see the Setup section below).
Note that when using the TEST environment, you must use the Venmo Test App, not the production one available on the Google Play Store. Otherwise, the authorization will fail.
The Venmo test app doesn't require any credentials - any email and any password will work.
The Android test app is available through PayPal's AppCenter - for access, contact integrations@paysafe.com.
Integrating the Android SDK
For information about integrating Paysafe's Android SDK and the SDK requirements, see Integrating the Android SDK.
To find the latest version of the SDK, check the GitHub releases.
Setup
For information about setting up the SDK, including the callback error object and setup errors, see Android SDK Setup.
Set up your app for context switching
Some configuration is required to include the Venmo module in your app.
The following steps will allow your app to open the Venmo app and then redirect back to your app.
For your app to handle Venmo, deep-linking is necessary to set up an intent in AndroidManifest.xml:
<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data android:scheme="${applicationId}.braintree" />
</intent-filter>
Example activity with intent:
<activity
android:name="com.paysafe.example.ActivitySample"
android:exported="true"
android:label="@string/sample_app"
android:screenOrientation="portrait"
android:theme="@style/Theme.PaysafeAndroidSDK.NoActionBar"
tools:ignore="LockedOrientationActivity">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data android:scheme="${applicationId}.braintree" />
</intent-filter>
</activity>
Initialize
To process a Venmo payment request, first initialize PSVenmoContext.
The initialize() method has the following signature:
/**
Initializes the Venmo integration.
@param fragment The fragment instance from which the venmo integration is initialized.
@param venmoConfig The configuration for Venmo integration.
@param callback Callback to receive the initialized Venmo context.
The callback provides a PSVenmoContext object containing the necessary context for Venmo operations.
*/
fun initialize(
fragment: Fragment,
venmoConfig: PSVenmoConfig,
callback: PSCallback<PSVenmoContext>
)
OR
/**
Initializes the Venmo integration.
@param activity The activity instance from which the venmo integration is initialized.
@param venmoConfig The configuration for Venmo integration.
@param callback Callback to receive the initialized Venmo context.
The callback provides a PSVenmoContext object containing the necessary context for Venmo operations.
*/
fun initialize(
activity: ComponentActivity,
venmoConfig: PSVenmoConfig,
callback: PSCallback<PSVenmoContext>
)
| Parameter | Required | Type | Description |
|---|---|---|---|
fragment/activity | true | Activity/ Fragment | The fragment/ activity instance from which the Venmo integration is initialized. |
venmoConfig | true | PSVenmoConfig | The configuration for the Venmo integration with the Paysafe Payments API. |
callback | true | PSCallback<PSVenmoContext> | Callback to receive the initialized Venmo context. The callback provides a PSVenmoContext object containing the necessary context for Venmo operations. |
| PSVenmoConfig | |||
currencyCode | true | String | The currencyCode accepts 3 letter abbreviations of the ISO standard currencies. |
accountId | true | String | The id of the selected merchant account to use to process the payment. If you are a merchant, this field is required only if you have more than one account configured for the same payment method and currency. If you are a partner using a shared API key, this field is mandatory. |
Usage example
PSVenmoContext.initialize(
this,
PSVenmoConfig(
currencyCode = "USD",
accountId = "<account-id>",
),
object : PSCallback<PSVenmoContext> {
override fun onSuccess(value: PSVenmoContext) {
venmoContext = value
}
override fun onFailure(exception: Exception) {
// handle exception
}
}
)
Initialize exceptions
| Error code | Display message | Detailed message | Comments |
|---|---|---|---|
9061 | There was an error (9061), please contact our support. | Invalid account id for ${paymentMethod} | AccountId is present, but it is not configured for the desired payment context. |
9101 | There was an error (9101), please contact our support. | Invalid accountId parameter | The SDK checks whether the accountId string contains only numbers. |
9055 | There was an error (9055), please contact our support. | Invalid currency parameter | The SDK checks whether the currency parameter consists of only 3 letters. This exception is thrown when the server responds with code 5001. |
9085 | There was an error (9085), please contact our support. | There are no available payment methods for this API key. |
|
9084 | There was an error (9084), please contact our support. | Failed to load available payment methods | Triggered when an internal server error is received in response to the payment methods API call. . |
9073 | There was an error (9073), please contact our support. | Account not configured correctly. | Triggered as a result of an improperly configured merchant account:
|
Tokenize
The tokenize method returns a PaymentHandle result, which resolves to a single-use payment handle representing the customer's sensitive card data. The Payments API can use this handle to take payments. Single-use handles are valid for only 15 minutes and are not consumed by verification. For more information, see Payments with a Handle.
Tokenize callback signature
The tokenize function has the following signature:
/**
Tokenization using Venmo.
@param context Any Context: Application, Activity or Fragment context
@param venmoTokenizeOptions Options for tokenizing Venmo data.
@param callback Callback to receive the tokenized vENMO data or any error encountered during the tokenization process.
The callback provides a PSVenmoTokenizeResult object containing the tokenized data or an error.
*/
suspend fun tokenize(
context: Context,
venmoTokenizeOptions: PSVenmoTokenizeOptions,
callback: PSVenmoTokenizeCallback
)
Parameters
- venmoTokenizeOptions: An instance of PSVenmoTokenizeOptions containing various parameters for tokenization, such as the payment amount, transaction type, account ID and Venmo configuration.
The callback of type PSVenmoTokenizeCallback is executed after the tokenization process is complete. The completion handler provides the single-use payment handle or any error encountered during the tokenization process.
/**
Callback interface for receiving the result of Venmo tokenization.
*/
interface PSVenmoTokenizeCallback {
/**
Called when Venmo tokenization is successful.
@param paymentHandle The payment handle representing the tokenized data.
*/
fun onSuccess(paymentHandleToken: String)
/**
Called when an error occurs during Venmo tokenization.
@param exception The exception indicating the error encountered during tokenization.
*/
fun onFailure(exception: Exception)
/**
Called when Venmo tokenization is cancelled.
@param paysafeException The Paysafe exception indicating the cancellation reason.
*/
fun onCancelled(paysafeException: PaysafeException)
}
PSVenmoTokenizeOptions
The PSVenmoTokenizeOptions structure provides a comprehensive set of options for configuring the tokenization process. These options include:
| Parameter | Required | Type | Description |
|---|---|---|---|
amount | true | Double | The payment amount is in minor units to charge the customer's card. Use the correct minor units amount for the merchant account currency. For example, to process US $10.99, this value should be 1099. To process 1000 Japanese Yen, this value should be 1000. To process 10.139 Tunisian dinar, this value should be 10139. Min = 1 Max = 999999999 |
currencyCode | true | String | The currencyCode accepts 3 letter abbreviations of the ISO standard currencies. |
accountId | true | String | The id of the selected merchant account to use to process the payment. If you are a merchant, this field is required only if you have more than one account configured for the same payment method and currency. If you are a partner using a shared API key, this field is mandatory. |
transactionType | true | TransactionType | This specifies the transaction type for which the Payment Handle is created. Possible values are:
|
merchantRefNum | true | String | A unique identifier is provided by the merchant for every transaction in Paysafe Android SDK. |
billingDetails | false | BillingDetails | Card billing address - additional details for the billingDetails object can be found in the Payments API documentation. |
profile | false | Profile | This is the profile of the customer - additional details for the profile object can be found in the Payments API documentation. |
merchantDescriptor | false | MerchantDescriptor | This is a merchant descriptor that is displayed on a customer’s card statement. |
shippingDetails | false | ShippingDetails | This is the shipping usage information. |
simulator | false | SimulatorType | The simulator only applies in the test environment and its default value is INTERNAL. In the production environment, the simulator value is disregarded even if provided, and the experience will be the same as if the simulator value was set to EXTERNAL. SimulatorType is an enum type with the following cases:
If omitted, defaults to .EXTERNAL. |
venmoRequest | true | VenmoRequest | Venmo configuration
|
VenmoRequest | |||
consumerId | true | String | The unique merchant's consumer id and must be unique per consumer. We store this after your first successful Venmo transaction for a given consumer (during this first transaction the consumer agrees to link their Venmo wallet for future transactions). When you subsequently send in the same consumerId, we debit the consumer’s wallet directly without the consumer having to agree to each transaction - so the Venmo authorization is no longer triggered. |
merchantAccountId | true | String | You can set up multiple accounts with Braintree, and each account can settle funds into a different bank account. This parameter therefore allows you to control which of your bank accounts is used to receive settlement. Only applies to pay-ins and not payouts. If you pass it for payouts the value will be ignored. |
profileId | true | String | You can set up multiple profiles with Braintree, where each profile shows the consumer a different logo and description during checkout on the Venmo app, and on the Venmo statement. This parameter therefore allows you to vary the consumer experience (for example, if you have multiple brands, you can display a different logo for each). Only applies to pay-ins and not payouts. If you pass it for payouts the value will be ignored. If not supplied for pay-ins, your default profile will be used |
Usage example
/// Payment amount in minor units
val amount = totalPrice * 100
let options = PSVenmoTokenizeOptions(
amount = amount,
currencyCode = "USD",
transactionType = TransactionType.PAYMENT,
merchantRefNum = PaysafeSDK.getMerchantReferenceNumber(),
billingDetails = BillingDetails(
nickName = "nickName",
street = "street",
city = "city",
state = "AL",
country = "US",
zip = "12345"
),
profile = Profile(
firstName = "firstName",
lastName = "lastName",
locale = ProfileLocale.EN_GB,
merchantCustomerId = "merchantCustomerId",
dateOfBirth = DateOfBirth(
day = 1,
month = 1,
year = 1990
),
email = "email@mail.com",
phone = "0123456789",
mobile = "0123456789",
gender = Gender.MALE,
nationality = "nationality",
identityDocuments = listOf(IdentityDocument(documentNumber = "SSN123456"))
),
accountId = "<account-id>",
merchantDescriptor = MerchantDescriptor(
dynamicDescriptor = "dynamicDescriptor",
phone = "0123456789"
),
shippingDetails = ShippingDetails(
shipMethod = ShippingMethod.NEXT_DAY_OR_OVERNIGHT,
street = "street",
street2 = "street2",
city = "Marbury",
state = "AL",
countryCode = "US",
zip = "36051",
),
venmoRequest = VenmoRequest(
consumerId = "cosumer@gmail.com",
merchantAccountId": "BankAccount2",
profileId": 1953896702662410200
)
)
venmoContext?.tokenize(
context,
options,
object : PSVenmoTokenizeCallback {
override fun onSuccess(paymentHandle: String) {
// handle payment handle
}
override fun onFailure(exception: Exception) {
// handle exception
}
override fun onCancelled(paysafeException: PaysafeException) {
context?.longToast("Venmo payment was cancelled")
}
}
)
Tokenization exceptions
| Error code | Display message | Detailed message | Comments |
|---|---|---|---|
9003 | There was an error (9003), please contact our support. | Invalid ${field} field value(s). | *added "field" word, *added "value(s)" instead of "value"
Thrown when merchant skips field validations and tries to tokenize invalid using fields.
Important: This exception is thrown also when the backend request fails with
5068 - Either you submitted a request that is missing a mandatory field or the value of a field does not match the format expected. 7508 - You submitted an invalid card number or brand or combination of card number and brand with your request.
|
9054 | There was an error (9054), please contact our support. | Amount should be a number greater than 0 no longer than 11 characters | The amount value should be a positive number. |
9136 | There was an error (9136), please contact our support. | Tokenization is already in progress. | Whenever merchant calls tokenize before the previous one has completed. |
9098 | There was an error (9098), please contact our support. | Invalid parameter in merchantDescriptor.dynamicDescriptor | String value should have <= 20 characters. |
9099 | There was an error (9099), please contact our support. | Invalid parameter in merchantDescriptor.phone | String value should have <= 13 characters. |
9112 | There was an error (9112), please contact our support. | Profile firstName should be valid | String value should have <= 80 characters. |
9113 | There was an error (9113), please contact our support. | Profile lastName should be valid | String value should have <= 80 characters. |
9119 | There was an error (9119), please contact our support. | Profile email should be valid | Use the following regex to check: |
5042/ 5068 | There was an error (5042/5068), please contact our support. | There was an error (5042/5068), please contact our support. | A system error has occurred, indicating a problem between Paysafe and Venmo. A text string in the response provides more details about the error. |
5040 | There was an error (5040), please contact our support. | Venmo accounts are not accepted by this merchant account | A setup error has occurred, indicating that you haven't been set up properly with Venmo. |
3047/ 3048/ 3049 | There was an error (3047/ 3048/ 3049), please contact our support. | The transaction was declined because the amount exceeds the floor limit. | The transaction was declined. For declines and amounts in the 3000s for failed transactions. |