Client-Side Implementation
If you do not decommission your app versions that include the older SDK versions or force upgrade your app with the updated certificates by the expiration date, 100% of your customer traffic will fail.
Choose an integration method
You can set up your client-side either with our Drop-in UI or with a custom integration.
Drop-in integration
To support Pay with Venmo on modern Android devices, we always recommend using the latest version of the Android Drop-in SDK. If you are unable to upgrade from your major version at this time, Pay with Venmo requires at least version 6.0.0-beta2 of major version 6, version 5.3.0 of major version 5, and version 4.7.0 of major version 4.
Our Drop-in UI is the fastest way to set up your client-side integration.
For full details, see Drop-in Setup and Integration.
Custom integration
To support Pay with Venmo on modern Android devices, we always recommend using the latest version of the Android SDK. If you are unable to upgrade from your major version at this time, Pay with Venmo requires at least version 4.6.0 of major version 4 and version 3.18.0 of major version 3.
Alternatively, you can add Venmo to your current custom integration. Keep in mind, for compliance purposes, we require you to present the customer with an order summary before and after purchase.
The pre-purchase summary should include:
- The items ordered
- The total order price
- An indication of Venmo as the payment method
The post-purchase summary can either be shown in the UI or sent via email. It should include:
- The items purchased
- The total purchase price
- The customer's name
- The customer's Venmo username
Failing to comply with these guidelines can lead to an interruption of your Venmo service.
Click here to download Venmo's brand guidelines, and be sure to follow them when configuring the Venmo button or making any other references to Venmo in your app.
Get the SDK
Add the following in your app-level build.gradle
:
- Kotlin
- Groovy
dependencies {
implementation("com.braintreepayments.api:venmo:5.8.0")
}
Invoking the Venmo flow
Create an instance of VenmoClient
and VenmoLauncher
. When ready to launch the Venmo flow, make a call to venmoClient.createPaymentAuthRequest()
- see
startVenmoFlow()
for an example in the code sample below. Store the VenmoPendingRequest
obtained from a call to venmoLauncher.launch()
to use later.
In your onResume()
method, call venmoLauncher.handleReturnToApp()
. Once you have a successful result, complete the Venmo flow by calling venmoClient.tokenize()
.
See individual methods for detailed docs.
- Kotlin
class VenmoActivity : AppCompatActivity() {
private lateinit var venmoClient: VenmoClient
private lateinit var venmoLauncher: VenmoLauncher
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// must be initialized on onCreate()
venmoLauncher = VenmoLauncher()
// can be initialized outside onCreate() if desired
venmoClient = VenmoClient(
context = requireContext(),
authorization = "TOKENIZATION_KEY or CLIENT_TOKEN",
appLinkReturnUrl = Uri.parse("https://merchant-app.com") // Merchant App Link
)
}
// ONLY REQUIRED IF YOUR ACTIVITY LAUNCH MODE IS SINGLE_TOP
override fun onNewIntent(intent: Intent) {
super.onNewIntent(intent)
handleReturnToApp(intent)
}
// ALL OTHER ACTIVITY LAUNCH MODES
override fun onResume() {
super.onResume()
handleReturnToApp(intent)
}
private fun handleReturnToApp(intent: Intent) {
super.onResume()
val pendingRequest: VenmoPendingRequest.Started = pendingRequest
pendingRequest?.let {
val paymentAuthResult: VenmoPaymentAuthResult =
venmoLauncher.handleReturnToApp(
pendingRequest = it,
intent = intent
)
if (paymentAuthResult is VenmoPaymentAuthResult.Success) {
// complete the venmo flow with the successful paymentAuthResult
completeVenmoFlow(paymentAuthResult)
} else {
// handle error - user did not complete Venmo flow
}
// clear pendingRequest
}
}
private fun startVenmoFlow(venmoRequest: VenmoRequest) {
venmoClient.createPaymentAuthRequest(
context = requireActivity(),
request = venmoRequest
) { paymentAuthRequest ->
if (paymentAuthRequest is VenmoPaymentAuthRequest.Failure) {
// handle paymentAuthRequest.error
} else if (paymentAuthRequest is VenmoPaymentAuthRequest.ReadyToLaunch) {
val pendingRequest: VenmoPendingRequest = venmoLauncher.launch(
activity = requireActivity(),
paymentAuthRequest = paymentAuthRequest
)
if (pendingRequest is VenmoPendingRequest.Started) {
// store pendingRequest for future use
} else if (pendingRequest is VenmoPendingRequest.Failure) {
// handle pendingRequest.error
}
}
}
}
private fun completeVenmoFlow(paymentAuthResult: VenmoPaymentAuthResult.Success) {
venmoClient.tokenize(paymentAuthResult) { result: VenmoResult ->
this.handleVenmoResult(result)
}
}
private fun handleVenmoResult(result: VenmoResult) {
when (result) {
is VenmoResult.Success -> { /* handle result.nonce) */ }
is VenmoResult.Failure -> { /* handle result.error */ }
is VenmoResult.Cancel -> { /* handle user canceled */ }
}
}
private fun storePendingRequest(request: VenmoPendingRequest.Started) {
// store pending request
}
private val pendingRequest: VenmoPendingRequest.Started
get() = { /* fetch stored pending request */ }
private fun clearPendingRequest() {
// clear/reset pending request
}
}
It's best practice to display the customer's Venmo username alongside their Venmo payment method in your checkout UI – like you would the last 4 digits of a credit card number.
Payment method usage
You must specify how you will use the customer's Venmo account by passing the VenmoPaymentMethodUsage
into your VenmoRequest
:
MULTI_USE
: Request authorization for future payments (vaulting allowed)SINGLE_USE
: Request authorization for a one-time payment (vaulting not allowed)
The payment method usage will affect the customer flow by:
- Displaying different phrases to the customer on the transaction consent page (e.g. "Authorize
Business Name
to pay with Venmo" vs. "AuthorizeBusiness Name
to pay with Venmo for future purchases" whereBusiness Name
is the business name submitted in the Venmo application form). - Not displaying a merchant connection on the Connected Businesses page in the Venmo app when the
paymentMethodUsage
property isSINGLE_USE
. - Allowing customers to update their funding instrument on the Connected Businesses page in the Venmo app when the
paymentMethodUsage
property isMULTI_USE
.
If VenmoPaymentMethodUsage
is set to SINGLE_USE
:
- A validation error will be returned if attempting to vault via PaymentMethod.create or Customer.create.
- The transaction will be processed normally but the nonce will not be vaulted if
store-in-vault
orstore-in-vault-on-success
is passed during transaction.sale.
- Kotlin
- Java
val request = VenmoRequest(VenmoPaymentMethodUsage.MULTI_USE)
venmoClient.tokenizeVenmoAccount(this, request)
Multiple profiles
If you have a custom integration and have onboarded multiple apps for Venmo processing with a single Braintree gateway, you'll need to pass the profile_id
to specify which Venmo profile to present during the payment flow.
You'll also need to pass the profile_id
when creating the transaction on the server side.
If you have multiple business profiles, the profile_id
for each profile can
be found by logging into the Control
Panel, clicking the gear icon in the
top right corner, selecting Processing from the drop-down menu, scrolling
to Venmo, and clicking the Options link.
Collect device data
You must collect information about the customer's device before creating each transaction.
- Kotlin
- Java
dataCollector.collectDeviceData(this@MyActivity) { deviceData, dataCollectorError ->
// send venmoAccountNonce.string and deviceData to server
}
You'll need to pass this deviceData
when creating the Venmo transaction from your server.
Be sure to pass device data as close to the transaction creation as possible. Doing so will help reduce decline rates.
Shipping and Billing Address collection
collectCustomerBillingAddress
and collectCustomerShippingAddress
flags into your VenmoRequest
.
When these flags are enabled, Venmo will collect the required addresses from the consumer and send them back in the reponse object.
- Java
- Kotlin
VenmoRequest request = new VenmoRequest(VenmoPaymentMethodUsage.MULTI_USE);
request.setProfileId("your-profile-id");
request.setCollectCustomerBillingAddress(true);
request.setCollectCustomerShippingAddress(true);
venmoClient.tokenizeVenmoAccount(this, request)
You will only be able to collect customer addresses if you have Enriched Customer Data (ECD) enabled in the Control Panel. Details about how to enable ECD can be found in this support article. A validation error will be returned if attempting to collect customer addresses without enabling ECD.
- Java
- Kotlin
@Override
public void onVenmoSuccess(@NonNull VenmoAccountNonce venmoAccountNonce) {
PostalAddress billingAddress = venmoAccountNonce.getBillingAddress();
String streetAddress = billingAddress.getStreetAddress();
String extendedAddress = billingAddress.getExtendedAddress();
String locality = billingAddress.getLocality();
String region = billingAddress.getRegion();
String postalCode = billingAddress.getPostalCode();
PostalAddress shippingAddress = venmoAccountNonce.getShippingAddress();
// ...
}
Amounts and Line Items
- Java
- Kotlin
VenmoRequest request = new VenmoRequest(VenmoPaymentMethodUsage.MULTI_USE);
request.setProfileId("your-profile-id");
request.setTotalAmount('10.00');
// Set optional amounts & line items
request.setSubTotalAmount('8.00');
request.setTaxAmount('1.00');
request.setDiscountAmount('1.00');
request.setShippingAmount('2.00');
ArrayList<VenmoLineItem> lineItems = new ArrayList<>();
lineItems.add(new VenmoLineItem(VenmoLineItem.KIND_DEBIT, "item-name", 2, "5.00"));
lineItems.add(new VenmoLineItem(VenmoLineItem.KIND_CREDIT, "credited-item-name", 1, "2.00"));
request.setLineItems(lineItems);
venmoClient.tokenizeVenmoAccount(this, request)
All amount and line-item fields are optional except for totalAmount
, which is required in the context of purchase. If the tokenize call is for vaulting only, totalAmount
can be omitted.
The following validations will be performed on the provided transaction details:
- All amounts are expected to be in USD
- All amounts must be non-negative
- All amounts must be of string type and must contain either a whole number or a number with two decimal places
- Line-item should have four properties: item name, quantity, unit amount and type
- Line-item
type
must be eitherCREDIT
orDEBIT
- The amounts for all individual line items present must add up to the total amount, or sub-total when present
- All individual amounts (discount, shipping, tax, sub-total) must add up to the total amount
- The
VenmoLineItem
constructor takes in paramters in a specific order: type, name, quantity, unitAmount