Search Overlay
Searchbox clear search filters ESC
Filter PreferencesClear

No results found

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.

Consumer experience - first payment

Consumer chooses to pay Consumer redirected to Venmo Consumer scans QR code Consumer authorizes payment Consumer sees a success message Consumer redirected back to merchant

NOTE: This shows the consumer experience on a desktop. The experience on a cell phone is different as there is no QR code.

Implementation

Call the following endpoints in sequence:

  1. /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.

  2. /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.

STEP 1: Call paymenthandles

  • 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 Code    		 Paysafe
    Error
    Code    		 Paysafe
    Error
    Message    		 APM
    Error
    Code    		 Can be
    simulated?    		 Magic
    Value
    (Amount)

    The request succeeds.

     

    N/A

    N/A

     

    YES

     

    Negative outcomes: Unhappy path - the request fails

    Outcome Paysafe
    HTTP
    Status Code    		 Paysafe
    Error
    Code    		 Paysafe
    Error
    Message    		 APM
    Error
    Code    		 Can 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 Code    		 Paysafe
    Error
    Code    		 Paysafe
    Error
    Message    		 APM
    Error
    Code    		 Can 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.

     

STEP 3: Call payments

  • 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 Code    		 Paysafe
    Error
    Code    		 Paysafe
    Error
    Message    		 APM
    Error
    Code    		 Can 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 Code    		 Paysafe
    Error
    Code    		 Paysafe
    Error
    Message    		 APM
    Error
    Code    		 Can 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:

  1. 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.
  2. 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.

Next steps

 

On this Page