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.
Implementation
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 CodePaysafe
Error
CodePaysafe
Error
MessageLPM
Error
CodeCan 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 CodePaysafe
Error
CodePaysafe
Error
MessageLPM
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. -
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.
-
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 CodePaysafe
Error
CodePaysafe
Error
MessageLPM
Error
CodeCan 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 CodePaysafe
Error
CodePaysafe
Error
MessageLPM
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. -
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.