Use Case 1: Payments

Call the following endpoints in sequence:

1. /paymenthub/v1/paymenthandles
   (transactionType: VERIFICATION)
   
   Initializes the verification process, which determines whether this is a new or returning consumer. This is a mandatory step in order to complete the subsequent steps.

   • Returning consumer: proceed to step 2 to get the list of bank accounts.
   • New consumer: proceed to step 3 in order to create a payment and subsequently register the new consumer.

2. /paymenthub/v1/verifications

   Returns the list of bank accounts linked to the consumer. This is a mandatory step in order to ensure that you have the most recent and up-to-date list of bank accounts to present to the consumer on your webstore. 

3. /paymenthub/v1/paymenthandles
   (transactionType: PAYMENT)
   
   Initializes the payment process.

   • New customer: provides you with a URL to redirect the consumer to link their bank account. 

   • Returning consumer: you submit the token representing the bank account chosen by the consumer (pass payByBank.ach.paymentHandleToken) when on the merchant webstore. You then redirect the consumer to a third party page to view the payment outcome.

4. /paymenthub/v1/payments

   Call the payments endpoint to capture the payment within 15 minutes - after this, the payment handle expires and the request to debit the consumer's bank account is not submitted.

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

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

  Happy path: this is a returning consumer

  Outcome	Paysafe HTTP Status Code	LPM Error Code/ Message	Can be simulated?	How to simulate?	Payment handle status	Next action
  The consumer exists in Pay by Bank.	201		YES	Submit any consumerId that you have already linked.	PAYABLE	Go to step 2 to retrieve the array of bank accounts for the consumer.

  Happy path: this is a new consumer

  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
  This is a new consumer who has not previously used Pay by Bank.	201		USER_NOT_EXIST		YES	Submit any consumerId that you have not already linked.	FAILED	Go to step 3 to link a bank account for the consumer.

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

• Store the token (payByBank.achBankAccounts.paymentHandleToken) for later use.
  
  payByBank.achBankAccounts.paymentHandleToken is a unique identifier for each bank account of the consumer and does not change. You subsequently use it to create a single-use payment handle token, which is used to make payments and withdrawals for each unique transaction.

   

  Happy path: Paysafe returns the consumer's linked bank accounts

  Outcome	Paysafe HTTP Status Code	LPM Error Code/ Message	Can be simulated?	How to simulate?	Payment handle status	Next action
  Paysafe returns a list of up to 4 linked bank accounts for the existing consumer.	201		YES	Submit any consumerId that you have already linked.	COMPLETED	Go to step 3 to initiate payment using the selected bank account.

• Call endpoint /paymenthub/v1/paymenthandles

  • transactionType:  PAYMENT
  • paymentType:  PAY_BY_BANK

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

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

  Happy path: the returning consumer initiates payment

  Outcome	Paysafe HTTP Status Code	LPM Error Code/ Message	Can be simulated?	How to simulate?	Payment handle status	Next action
  The returning consumer initiates payment with Pay by Bank, using their linked bank account.	201		YES	Submit consumerId and ach.paymentHandleToken, which you have already linked.	INITIATED	Go to step 4 to redirect and complete the payment.

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

• 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, provides credentials and authorizes the transaction.

  • The payment handle status changes to PAYABLE.

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

  Happy path: Pay by Bank/ Paysafe approves the payment

  Outcome	Paysafe HTTP Status Code	LPM Error Code/ Message	Can be simulated?	How to simulate?	Payment handle status	Next action
  The payment is risk approved.			YES	Submit a transaction with a value of <1000.	PAYABLE	Go to step 5 to process the payment.

  Unhappy path: Pay by Bank/ Paysafe declines the payment

  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 payment is declined as it is classified as high-risk.					YES	Submit a transaction with a value of >120,000.	FAILED

  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:

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

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

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

  Happy path: the payment is successfully submitted for processing

  Outcome	Paysafe HTTP Status Code	LPM Error Code/ Message	Can be simulated?	How to simulate?	Payment handle status	Next action
  The payment is guaranteed.	201		YES	Submit a transaction with a value of <1000 and select Custom Account Ending in 9828 on the redirection page.	COMPLETED

  Unhappy path: the payment is not submitted for processing

  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 payment fails as the bank details are invalid.	201			The specified bank and account information is currently under INVALID state.	YES	Submit a transaction with a value of <1000 and select ACHLink Enr App/Trans Decl - With Transaction History on the redirection page.	COMPLETED

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

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