Search Overlay
Searchbox clear search filters ESC
Filter PreferencesClear

No results found

Use Case 2: Withdrawals

This use case allows you to pay money to a consumer who has already made a payment on your webstore using Pay by Bank.

Consumer experience

This is the journey for a consumer making a withdrawal.

Select Pay by Bank Select bank account The withdrawal is completed

Implementation

Call the following endpoints in sequence:

  1. /paymenthub/v1/paymenthandles

    (transactionType: VERIFICATION)

    Initializes the verification process, which is a mandatory step in order to complete the subsequent steps. 

  2. /paymenthub/v1/verifications

    Returns the list of bank accounts linked to the consumer.

  3. /paymenthub/v1/paymenthandles

    (transactionType: STANDALONE_CREDIT)

    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.

  4. /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 for verifications

  • Call endpoint /paymenthub/v1/paymenthandles

    • transactionType:  VERIFICATION
    • paymentType:  PAY_BY_BANK

  • Pass the required parameters in the payByBank object.

  • If this is a new consumer, pass the required parameters in the billingDetails and profile objects.

    NOTE: This step is identical to the paymenthandles for verifications call used when making a Pay by Bank payment. For more information about the payment handle status and potential call outcomes, see Pay by Bank Payments - STEP 1: Call paymenthandles for verifications.

STEP 2: Call verifications

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

    • The payment handle status changes to COMPLETED.

  • Paysafe returns our verifications response, indicating that the request status is COMPLETED and providing a paymentHandleToken for each registered bank account.

    NOTE: This step is identical to the verifications call used when making a Pay by Bank payment. For more information about the paymentHandleToken, see Pay by Bank Payments - STEP 2: Call verifications.

STEP 3: Call paymenthandles for withdrawals

Paymenthandles withdrawal flow

  • Call endpoint /paymenthub/v1/paymenthandles

    • transactionType: STANDALONE_CREDIT
    • paymentType: PAY_BY_BANK

  • Pass the required parameters:

    • If this is a new consumer, pass the required parameters in the payByBank, profile and billingDetails objects.
    • If this is a returning consumer, pass the required parameters in the payByBank object only.

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

    Happy path: the returning consumer initiates a withdrawal

    Outcome Paysafe
    HTTP
    Status Code    		 LPM Error
    Code/ Message    		 Can be
    simulated?    		 How to
    simulate?    		 Payment
    handle
    status    		 Next
    action

    The returning
    consumer initiates a
    withdrawal with
    Pay by Bank,
    using their linked
    bank account.

    201

    N/A

    YES
    (external)

    Submit consumerId and
    ach.paymentHandleToken,
    which you have already
    linked.

    PAYABLE

    Go to step 5 to
    process the
    withdrawal.

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

    • For positive scenarios where this is either a new consumer or a returning consumer who is adding a new bank account, the payment handle is created with status INITIATED.
    • For positive scenarios where an existing consumer is using an existing bank account, the payment handle is created with status PAYABLE.
    • For negative scenarios, the payment handle is created with status FAILED.

STEP 4: Redirect consumer

  • Redirect the consumer to the URL provided in the payment handle response.

    • The payment handle status changes to PROCESSING.

  • The consumer accepts the Terms & Conditions (T&Cs), selects the bank they want to add, and provides the credentials of the bank account to confirm linking it.

    • The payment handle status changes to PAYABLE.

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

    Happy path: the consumer is enrolled and the bank account is successfully added

    Outcome Paysafe
    HTTP
    Status Code    		 LPM Error
    Code/ Message    		 Can be
    simulated?    		 How to
    simulate?    		 Payment
    handle
    status    		 Next
    action

    The consumer is
    enrolled, and the
    bank account is
    added.

     

     

    YES

    		 Submit a
    transaction
    with a value
    of <1000 and
    select Custom
    Account Ending
    in 9828     on the
    redirection page

    PAYABLE

    Go to step 5 to
    process the
    withdrawal.

    Unhappy path: the consumer rejects the Terms & Conditions (T&Cs)

    Outcome Paysafe
    HTTP
    Status Code    		 Paysafe
    Error
    Code    		 Paysafe
    Error
    Message    		 LPM
    Error
    Code    		 Can be
    simulated?    		 How to
    simulate?    		 Payment
    handle
    status    		 Next
    action
    The consumer
    rejects the
    T&Cs, so the
    request fails.    		         YES Do not
    accept the
    T&Cs on the
    redirection
    page.    		 FAILED  

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

    • For positive scenarios, the payment handle status changes to PAYABLE.
    • For negative scenarios, the payment handle status changes to FAILED.

STEP 5: Call standalonecredits

Pay by Bank standalonecredits flow

  • 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

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

    The request succeeds.

     

    N/A

    N/A

     

    YES
    (external)

     

    Negative outcomes: Unhappy path - the request fails

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

  • 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.

  • Following a successful withdrawal, the consumer receives email confirmation of the payout.

If Overdraft Threshold Protection is enabled during onboarding, withdrawal requests will be set to a PENDING status if your account balance is insufficient. The transaction will be processed automatically once there is sufficient balance. Pending transactions will remain in this status for up to 7 days, after which they will be marked as FAILED if the balance remains inadequate.

Delayed withdrawal processing

If you need to trigger delayed withdrawals for regulatory compliance, risk checks, or to build a backend process around withdrawals, follow these steps:

  1. When calling the endpoint /paymenthub/v1/standalonecredits/during step 5, include the onHold object with the value set to true in the request body. This will set the standalonecredit status to HELD, with the statusReason as HELD_BY_MERCHANT.
  2. When you have completed your checks and are ready with your final decision about the withdrawal, call the following endpoint:
    PATCH: /paymenthub/v1/standalonecredits/{standaloneCreditId}
    Depending on how you want to proceed, include one of the following options in the request body:
    • To proceed with the withdrawal, set onHold to false.
    • To cancel the withdrawal request, set status to CANCELLED.
On this Page