Pay by Bank (US)
Pay by Bank allows consumers to make instant, real-time payments and withdrawals on merchant webstores direct from their bank account via the US-based Automated Clearing House (ACH) network.
To use Pay by Bank, a consumer simply logs into their existing bank interface to connect their account, and from that point they can use their bank account to pay with a single click.
For more details, see About Pay by Bank (US) | Payments API.
Supported use cases
You can make the following types of transaction:
- Use case 1: Payments
- Use case 2: Linked withdrawals
Use case 1: Payments
This use case enables your consumer to choose Pay by Bank as a payment option on Paysafe Checkout and to make a payment using their bank account.
New consumer experience
This is the journey for a new consumer.
Returning consumer experience
This is the journey for a returning consumer.
Implementation - payments
When a consumer clicks Pay on your webstore:
-
Invoke Checkout to show payment methods to the consumer:
- Pass core checkout parameters and the following additional mandatory objects:
customer
billingAddress
payByBank (within the paymentMethodDetails object, passing only the consumerId)
- Pass core checkout parameters and the following additional mandatory objects:
-
Create a resultCallback function to capture the status of the payment handle and the details of the transaction e.g. amount and payment type.
-
You receive webhooks to notify you about the progress of the payment (if webhooks are enabled).
Positive outcome: Happy path
Outcome Paysafe
HTTP
Status CodeLPM Error
Code/ MessageCan be
simulated?How to
simulatePayment
handle
statusNext
actionConsumer chooses their
bank and selects Pay.N/A
N/A
CREATED
Payment is sent for authorization. N/A N/A PROCESSING Payment is authorized. N/A N/A PAYABLE Call the payments
endpoint to complete
the paymentNegative outcomes: Unhappy path - the request fails
Outcome Paysafe
HTTP
Status CodePaysafe
Error
CodePaysafe
Error
MessageLPM
Error
CodePayment
handle
statusNext
actionPayment is not
authorized.400 9140 Payment handle failed with status:400 N/A FAILED -
Call payments
- Call endpoint /paymenthub/v1/payments
use the paymentHandleToken returned in the resultCallback
submit the amount and transactionType returned in the resultCallback - 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)Paysafe settles the
payment.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 payment handle
is not in PAYABLE
status.400 5283 Payment Handle
is invalidYES
(external)The Paysafe token is
not used within 15
minutes.PAYMENT_HANDLE_
EXPIREDYES
(external)Auto triggered
after 15 mins. - Call endpoint /paymenthub/v1/payments
Sample code - payments
<html>
<head>
<script src="https://api.test.paysafe.com/checkout/v2/paysafe.checkout.min.js"></script>
</head>
<body>
<button onclick="checkout()">Deposit</button>
</body>
<script>
function checkout() {
var API_key = "c3V0LTM0ODg2MDpCLXFhMi0wLTVkM2VjYjMwLTEtMzAyYzAyMTQyYTM3NjgxMmE2YzJhYzRlNmQxMjI4NTYwNGMwNDAwNGU2NWI1YzI4MDIxNDU1N2EyNGFiNTcxZTJhOWU2MDVlNWQzMjk3MjZjMmIzZWNjNjJkNWY=";
options = {
currency: "USD",
amount: 540,
merchantRefNum: "162938285366512",
customer: {
firstName: "John",
lastName: "Doe",
email: "DoeJohn.0309@gmail.com",
phone: "5464655142",
identityDocuments: [{
type: "SOCIAL_SECURITY",
documentNumber: "000000192",
}],
dateOfBirth: {
"year": 1980,
"month": 5,
"day": 3
}
},
billingAddress: {
"nickName": "Shalonda's Address",
"street": "9194 Peachtree Dunwoody Rd ",
"city": "Atlanta",
"zip": "30328",
"country": "US",
"state": "GA"
},
paymentMethodDetails: {
payByBank :{
consumerId:"112223333" //Mandatory Parameter, providing the ConsumerId will lock the consumer and load saved bank accounts.
}
}
};
paysafe.checkout.setup(
API_key,
options,
function resultCallback(instance, error, result) {
if (result && result.paymentHandleToken) {
instance.showSuccessScreen( "Your goods are now purchased. Expect them to be delivered in next 5 business days.");
if (instance.isOpen()) {
instance.close();
}
// make AJAX call to Payments API
} else {
console.error(error); // Handle the error
instance.showFailureScreen( "The payment was declined. Please, try again with the same or another payment method.");
}
},
function(stage, expired) {
if (stage) {
switch (stage) {
case "PAYMENT_HANDLE_NOT_CREATED" :
case "PAYMENT_HANDLE_CREATED" :
case "PAYMENT_HANDLE_REDIRECT" :
case "PAYMENT_HANDLE_PAYABLE" :
default:
}
}
else {
console.log(expired) //Add action in case Checkout is expired
}
}
);
}
</script>
</html>
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.
Implementation - withdrawals
When a consumer clicks Withdraw on your webstore:
-
Invoke Checkout to show payment methods to the consumer:
- Pass core checkout parameters and the following additional mandatory objects:
customer
billingAddress
payByBank (within the paymentMethodDetails object, passing only the consumerId)
- Pass core checkout parameters and the following additional mandatory objects:
-
Create a resultCallback function to capture the status of the payment handle and the details of the transaction e.g. amount, paymentHandleToken and transactionType.
-
You receive webhooks to notify you about the progress of the withdrawal (if webhooks are enabled).
-
Call standalonecredits:
- Call endpoint /paymenthub/v1/standalonecredits
use the paymentHandleToken returned in the resultCallback - Paysafe returns our standard gateway response, indicating either a positive or negative outcome:
Positive outcome: Happy path
You receive transaction and settlement details in the response that can be used for reconciliation. 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_
EXPIREDYES
(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.
- Call endpoint /paymenthub/v1/standalonecredits
Code sample - withdrawals
<html>
<head>
<script src="https://api.test.paysafe.com/checkout/v2/paysafe.checkout.min.js"></script>
</head>
<body>
<button onclick="checkout()"> Withdrawal </button>
</body>
<script>
function checkout() {
var API_key = "c3V0LTM0ODg2MDpCLXFhMi0wLTVkM2VjYjMwLTEtMzAyYzAyMTQyYTM3NjgxMmE2YzJhYzRlNmQxMjI4NTYwNGMwNDAwNGU2NWI1YzI4MDIxNDU1N2EyNGFiNTcxZTJhOWU2MDVlNWQzMjk3MjZjMmIzZWNjNjJkNWY=";
options = {
currency: "USD",
amount: 540,
merchantRefNum: "162938285366512",
payout:true,
customer: {
firstName: "John",
lastName: "Doe",
email: "DoeJohn.0309@gmail.com",
phone: "5464655142",
identityDocuments: [{
type: "SOCIAL_SECURITY",
documentNumber: "000000192",
}],
dateOfBirth: {
"year": 1980,
"month": 5,
"day": 3
}
},
billingAddress: {
"nickName": "Shalonda's Address",
"street": "9194 Peachtree Dunwoody Rd ",
"city": "Atlanta",
"zip": "30328",
"country": "US",
"state": "GA"
},
paymentMethodDetails: {
payByBank :{
consumerId:"112223333" //Mandatory Parameter, providing the ConsumerId will lock the consumer and load saved bank accounts.
}
}
};
paysafe.checkout.setup(
API_key,
options,
function resultCallback(instance, error, result) {
if (result && result.paymentHandleToken) {
instance.showSuccessScreen( "Your goods are now purchased. Expect them to be delivered in next 5 business days.");
if (instance.isOpen()) {
instance.close();
}
//Check paymentHandleToken Stage to initiate next step
} else {
console.error(error); // Handle the error
instance.showFailureScreen( "The payment was declined. Please, try again with the same or another payment method.");
}
},
function(stage, expired) {
if (stage) {
switch (stage) {
case "PAYMENT_HANDLE_NOT_CREATED" :
case "PAYMENT_HANDLE_CREATED" :
case "PAYMENT_HANDLE_REDIRECT" :
case "PAYMENT_HANDLE_PAYABLE" :
default:
}
}
else {
console.log(expired) //Add action in case Checkout is expired
}
}
);
}
</script>
</html>