Use Case 2: Linked 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.

Call the following endpoints in sequence:

/paymenthub/v1/paymenthandles
(transactionType: VERIFICATION)

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

Returns the list of bank accounts linked to the consumer.
/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.
/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.

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.

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.

Call endpoint /paymenthub/v1/paymenthandles
- transactionType: STANDALONE_CREDIT
- paymentType: PAY_BY_BANK
Pass the required parameters in the payByBank 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	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 payment handle is created with status PAYABLE.
- For negative scenarios, the payment handle is created with status FAILED.

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.

On this Page