Use Case 1: Payments
This use case enables your consumer to choose Venmo as a payment option on your webstore and to make a payment using their Venmo wallet.
For the first payment, you redirect your consumer to Venmo to authorize the payment and grant permission for subsequent payments. For subsequent payments there is no redirect - you simply send us an identifier for the consumer when you want to take a payment.
Implementation
Call the following endpoints in sequence:
- /paymenthub/v1/paymenthandles
Initializes the payment process and provides you with a URL to redirect the consumer.
Redirect the consumer to the provided URL so that they can authorize payment from their Venmo wallet. The funds are ring-fenced inside the wallet. -
/paymenthub/v1/payments
You can decide whether to complete (“capture”) the payment based on the response from the payment handle (such as the identity of the consumer wallet that was used).
Call the payments endpoint to capture the payment within 15 minutes - after this, the money rolls back to the consumer.
NOTE: For code examples and detailed explanations of the parameters, refer to the Payments API Reference.
-
Call endpoint /paymenthub/v1/paymenthandles
- transactionType: PAYMENT
- paymentType: VENMO
-
Pass the required parameters in the venmo object.
-
Paysafe creates a payment handle and returns our standard gateway response, indicating either a positive or negative outcome:
Positive outcome: Happy path
Outcome Paysafe
HTTP
Status CodePaysafe
Error
CodePaysafe
Error
MessageAPM
Error
CodeCan be
simulated?Magic
Value
(Amount)The request succeeds.
N/A
N/A
YES
Negative outcomes: Unhappy path - the request fails
Outcome Paysafe
HTTP
Status CodePaysafe
Error
CodePaysafe
Error
MessageAPM
Error
CodeCan be
simulated?Magic
Value
(Amount)A system error has occurred, indicating a problem between Paysafe and Venmo.
A text string in the response provides more details about the error.
400 5042/ 5068 NO A setup error has occurred, indicating that you haven't been set up properly with Venmo.
401
5040
Venmo accounts are not accepted by this merchant account
Your merchant account is not configured for the transaction you attempted.
NO
The transaction was declined.
402
3047/ 3048/ 3049
For declines and amounts in the 3000s for failed transactions
The transaction was declined because the amount exceeds the floor limit.
YES
(internal)3000.00 to 3000.99
-
The payment handle status depends on the outcome of the request:
- For positive scenarios, the payment handle is created with status INITIATED.
- For negative scenarios, the payment handle is created with status FAILED.
STEP 2: Redirect consumer
-
Redirect the consumer to the URL provided in the payment handle response.
- The payment handle status changes to PROCESSING.
-
The consumer authorizes the payment with Venmo and agrees to connect their account with you.
- The payment handle status changes to PAYABLE.
-
Paysafe returns our standard gateway response, indicating either a positive or negative outcome:
Positive outcome: Happy path
Outcome Paysafe
HTTP
Status CodePaysafe
Error
CodePaysafe
Error
MessageAPM
Error
CodeCan be
simulated?Magic
Value
(Amount)The consumer has authorized the payment and agreed to create a ‘mandate’.
N/A
N/A
YES
-
The payment handle status depends on the outcome:
- For positive scenarios, the status changes to PAYABLE.
- For negative scenarios, the status changes to FAILED.
-
Webhooks provide the following Venmo specific data within the gatewayResponse object. You can use the data to decide whether to complete the payment:
Parameter Description and handling Example brainTreeCustomerId
A unique identifier for the consumer account held by Venmo.
A numeric 9 digit string.
The consumer cannot change their brainTreeCustomerId, so this field always contains the same value for the same payer.
Use this identifier to match against the consumer identifier in your system to identify cases such as:
- One consumer trying to pay with multiple Venmo wallets.
- Multiple consumers trying to pay from a single Venmo wallet.
Based on this analysis, you can decide whether to proceed with the payment.
657970850
profile.email
The email address that Venmo holds on file for the owner of this wallet.
profile.firstName
The first name of the consumer that Venmo holds on file.
Use this to ensure that the name of the consumer in your system matches the name of the payer on the Venmo wallet.
profile.lastName
The last name of the consumer that Venmo holds on file.
Use this to ensure that the name of the consumer in your system matches the name of the payer on the Venmo wallet.
username
The username that the consumer uses to identify themself to Venmo, and to log into their Venmo wallet.
It contains between 4 and 29 characters preceded by @.The consumer can change their username in their Venmo app, so this may not be consistent between payments.
processor
Always set to Braintree.
-
Use the profile data returned in the response to the payment handles request to decide whether to proceed with the payment.
NOTE: If you decide not to proceed with the payment, the ring-fenced funds in the consumer’s wallet are released after 15 minutes.
-
Call endpoint /paymenthub/v1/payments using the paymentHandleToken.
-
Paysafe returns our standard gateway response, indicating either a positive or negative outcome:
Positive outcome: Happy path
Outcome Paysafe
HTTP
Status CodePaysafe
Error
CodePaysafe
Error
MessageAPM
Error
CodeCan be
simulated?Magic
Value
(Amount)Venmo settles the payment.
N/A
N/A
YES
(external)0.01 to 1999.99
Negative outcomes: Unhappy path - the request fails
Outcome Paysafe
HTTP
Status CodePaysafe
Error
CodePaysafe
Error
MessageAPM
Error
CodeCan be
simulated?Magic
Value
(Amount)The Paysafe token is not used within 15 minutes. PAYMENT_HANDLE_EXPIRED YES
(external)Auto triggered after 15 mins
(when token is not used). -
The payment handle status depends on the outcome of the request:
- For positive scenarios, the status changes to COMPLETED.
- For negative scenarios, the status changes to FAILED.
- For negative scenarios where the token expires after 15 minutes, the status changes to EXPIRED.
Subsequent payments
You can make subsequent payments without the consumer being in session, and without the consumer needing to authorize the payment each time.
Subsequent payments are identical to the first payment apart from the following differences when calling the paymenthandles endpoint:
- As long as the agreement that the consumer has “signed” with Venmo remains in force (if the consumer has not revoked permission in the Venmo app, for example), the response won't contain a redirect URL.
NOTE: If the consumer has invalidated the agreement with you (i.e. they have revoked permission in the Venmo app), the response contains a redirect URL that prompts the consumer to recreate the agreement. - The payment handle status changes from INITIATED to PROCESSING to PAYABLE without further intervention from you (as there is no need to redirect the consumer).
All other aspects of payment processing are completely identical.