Search Overlay
Searchbox clear search filters ESC
Filter PreferencesClear

No results found

Use Case 2: Linked Withdrawals

This use case allows you to pay money to a consumer who has already made a payment in your webstore using Venmo. We use the consumerId that you submit in order to send money to the correct Venmo wallet.

Implementation

Call the following endpoints in sequence:

  1. /paymenthub/v1/paymenthandles

    Initializes the withdrawal by validating whether the request can be actioned (by checking if you have sufficient balance for example). It provides you with a payment handle token that you can then use to complete the payment.

  2. /paymenthub/v1/standalonecredits

    Moves money to the consumer and debits your balance.

NOTE: For code examples and detailed explanations of the parameters, refer to the Payments API Reference.

STEP 1: Call paymenthandles

Venmo paymenthandles sequence diagram

  • Call endpoint /paymenthub/v1/paymenthandles

    • transactionType: STANDALONE_CREDIT
    • 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
    (internal)

     

    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)

    Your merchant account is not set up correctly with PayPal.

    403

    1001

    An error occurred with the external processing gateway.

    SENDER_RESTRICTED

     

    YES
    (external)

    45.11

    Your email address is not authorized with Paypal.

    403

    1001

    Authorization error occurred

     

    SENDER_EMAIL_UNCONFIRMED

    YES
    (external)

    45.21

    An authorization error occurred.

    403

    1001

    Authorization error occurred

     

    AUTHORIZATION_ERROR

     

    YES
    (external)

    45.31

    You don't have enough funds to pay the requested amount to the consumer.

    502

    1001

    An internal service error has occurred

     

    INSUFFICIENT_FUNDS

     

    YES
    (external)

    45.41

    An internal server error occurred.

    502

    1001

    An internal service error has occurred

    INTERNAL_ERROR

     

    YES
    (external)

    45.51

     

    The payload is invalid.

    400

    1001

    Invalid Request - Invalid Payload

    VALIDATION_ERROR

    YES
    (external)

    45.61

    Required scope is missing.

    403

    1001

    REQUIRED_SCOPE_MISSING

    Access token does not have required scope.

    YES
    (external)

    45.71

     

    Your PayPal account is restricted.

    403

    1001

    SENDER_LOCKED

    Authorization error – Sender locked

    YES
    (external)

    45.81

     

    The provided sender batch_id already exists.

    400

    1001

    USER_BUSINESS_ERROR

    User business error.

     

    YES
    (external)

    45.91

    The server timeout limit was exceeded.

    504

    1001

    REQUEST_TIMEOUT_EXCEEDED

    Server did not receive a timely response from a system it needed to access to process the request.

    Please retry after some time.

    YES
    (external)

    46.31

    You did not set the application synchronous mode in the config.

    403

    1001

    SYNC_MODE_NOT_APPLICABLE

    Synchronous mode will soon be deprecated and is no longer available for new integrations.

    You can use the asynchronous mode by specifying sync_mode= false in the request.

    YES
    (external)

    46.41

    Your currency type is different to the required currency used for the withdrawal request.

    400

    1001

    NON_HOLDING_CURRENCY

     

    As your PayPal balance is not held in this currency, you'll not be able to send Payouts.

    YES
    (external)

    46.51

    You must wait until the previous batching process completes before a new payout request can be completed.

    400

    1001

    PREVIOUS_REQUEST_IN_PROGRESS

    A previous with the same sender batch id is in progress.

    Please try after some time.

    YES
    (external)

    46.61

    The consumer did not properly pass the customer identification process.

    400

    1001

    CIP_NOT_VERIFIED

    Your account is not CIP verified. Please verify your PayPal account and retry the payout.

    YES
    (external)

    46.71

  • The payment handle status depends on the outcome of the request:

    • For positive scenarios, the payment handle is created with status PROCESSING and changes to PAYABLE.
    • For negative scenarios, the payment handle is created with status FAILED.

STEP 2: Call standalonecredits

Venmo standalonecredits sequence diagram

  • Call endpoint /paymenthub/v1/standalonecredits using the paymentHandleToken.

  • Paysafe returns our standard gateway response, indicating either a positive or negative outcome:

    Positive outcome: Happy path - the request succeeds

    Outcome Paysafe
    HTTP
    Status Code    		 Paysafe
    Error
    Code    		 Paysafe
    Error
    Message    		 APM
    Error
    Code    		 Can be
    simulated?    		 Magic
    Value
    (Amount)

    Venmo authorizes the payment.

     

    N/A

    N/A

     

    YES
    (internal)

     

    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 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 first changes to PROCESSING and then 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.
On this Page