Overview
- Payments
- Canada
- Europe & UK
- United States
Paysafe Checkout allows merchants to take payment from credit cards, bank accounts, and alternate payment methods using a secure overlay while providing the least demanding level of PCI compliance: SAQ-A. The user input and storage of credit card and bank account data are handled by Paysafe. Paysafe Checkout uses Paysafe's Customer Vault, Card Payments, Alternate Payments, and Direct Debit REST APIs.
Advantages
- Complies with PCI SAQ-A
- Simple integration
- Paysafe handles security for credit card and bank account details
- Supports processing payments with 3D Secure–enabled cards
- No redirection from the merchant's website required
Before You Begin
Before you begin, you need to obtain your standard server-to-server API key and a single-use token-generating API key from the Merchant Back Office. If you want to use the Direct Debit, Interac, or PayPal flow, you will have to contact Paysafe Group support to enable the API key for the Direct Debit and/or Alternate Payments API. You will also have to contact Paysafe Group support to configure your account so that Direct Debit, Interac and/or PayPal are visible as payment methods in the Paysafe Group Checkout form.
The single-use token-generating API key is used in your JavaScript code on the client to generate single-use tokens from customer credit cards and bank accounts. Unlike the server-to-server API key, this key has no ability to take payment or carry out any other operation, and can therefore be safely exposed in your client side code.
To obtain a single-use token–generating key:
- SIGN UP to get a Test account, if you haven't already done so.
- Log in to the Test back office with the user name and password you used when signing up for the Test account. You should now be able to view the Settings > API Key page.
- In the Single-Use Token area, click the Create button.
- You will receive a security token by email. Enter this token and click Next.
The Single-Use Token area in the API Key page updates to show the user name and password for the single-use token API key. - If you haven't already done so, take a copy of the user name and password for the server-to-server API key as well. You will need this (and your account ID in your sign-up email) for taking payments with the generated tokens.
Paysafe Checkout uses the Base64-encoded version of the single-use token API key constructed by concatenating the user name and password separated by a colon and Base64 encoding the result. You can use a site like https://www.base64encode.org/ to do the base 64 encoding. See authentication for more details.
How to Use the SDK
- Include the Paysafe Checkout SDK in your HTML payment form.
- Call the checkout setup function with your single-use token API key. The setup function creates an iframe overlay containing the secure payment form hosted on Paysafe's servers. You will need to pass a callback function as part of the setup to handle successful tokenization success and failure.
- The callback should use AJAX to send the token representing the customer's payment details to your merchant server to make payment, the exact endpoint depending on the payment method:
- Credit card uses the Card Payments API authorization endpoint – for more details, see this topic.
- Direct Debit uses the Direct Debit API Purchase endpoint – for more details, see this topic.
- Interac uses the Alternate Payment Methods endpoint – for more details, see this topic.
- PayPal uses the Alternate Payment Methods endpoint – for more details, see this topic.
- At present, Paysafe supports the following currencies:
- for PayPal: USD, CAD, GBP, EUR
- for Interac: CAD only
Try Now
Click the button below to show the checkout demo overlay. In the overlay, select one of the following payment options:
- CARD – If you select this, enter a test card value (for example, 4111 1111 1111 1111), a valid future expiry date, a random three-digit CVV, and then click Pay to generate a single-use token.
- DIRECT DEBIT – If you select this, enter an address, city, and ZIP code, and then click NEXT: Account Details; type a valid Account Number and Routing Number (not all routing numbers will work in the TEST environment, so we recommend you use 021000021); select the Account Type; and then click Pay to generate a single-use token.
- INTERAC – If you select this you are prompted to complete the payment. In the production (LIVE) environment the consumer would be redirected to Interac Online to authorize the payment. In the TEST environment you are taken to the Alternate Payments Redirect Simulator, where you can submit either SUCCESS or ERROR to mimic the response from Interac and then generate the Paysafe single-use token.
- PAYPAL – If you select this you are prompted to complete the payment.
The token will be displayed below and in the corresponding example cURL request, which shows how you can take payment on your server.
Card Payment Example Request
curl -X POST https://api.test.paysafe.com/cardpayments/v1/accounts/1001134830/auths \
-u test_vniezsai:B-qa2-0-59564dfa-0-302c021426a55dde98dc2a052cccc1ddc8daa776a7a4fe2e0214080388fded986767abc445e58af123c01003cb8b \
-H 'Content-Type: application/json' \
-d ' {
"merchantRefNum" : "payment-token-demo-1",
"amount" : 5000,
"settleWithAuth":true,
"card" : {
"paymentToken" : "CARDS PAYMENT TOKEN RECEIVED FROM CLIENT BROWSER"
}
} '
Direct Debit Payment Example Request
curl -X POST https://api.test.paysafe.com/directdebit/v1/accounts/1001134830/purchases \
-u test_vniezsai:B-qa2-0-59564dfa-0-302c021426a55dde98dc2a052cccc1ddc8daa776a7a4fe2e0214080388fded986767abc445e58af123c01003cb8b \
-H 'Content-Type: application/json' \
-d ' {
"merchantRefNum" : "payment-token-demo-2",
"amount" : 5000,
"ach": {
"paymentToken": "DD PAYMENT TOKEN RECEIVED FROM CLIENT BROWSER",
"payMethod": "WEB",
"paymentDescriptor": "Transaction"
}
} '
Interac Payment Example Request
curl -X POST https://api.test.paysafe.com/alternatepayments/v1/accounts/1001134830/payments \
-u test_vniezsai:B-qa2-0-59564dfa-0-302c021426a55dde98dc2a052cccc1ddc8daa776a7a4fe2e0214080388fded986767abc445e58af123c01003cb8b \
-H 'Content-Type: application/json' \
-d ' {
"merchantRefNum":"payment-token-demo-3",
"amount":5000,
"settleWithAuth": false,
"returnLinks":[
{
"rel":"default",
"href":"https://mysite.com/return"
}
],
"paymentType":"INTERAC",
"paymentToken":"INTERAC PAYMENT TOKEN RECEIVED FROM CLIENT BROWSER"
}
} '
PayPal Payment Example Request
curl -X POST https://api.test.paysafe.com/alternatepayments/v1/accounts/1001134830/payments \
-u test_vniezsai:B-qa2-0-59564dfa-0-302c021426a55dde98dc2a052cccc1ddc8daa776a7a4fe2e0214080388fded986767abc445e58af123c01003cb8b \
-H 'Content-Type: application/json' \
-d ' {
"merchantRefNum":"payment-token-demo-4",
"amount":5000,
"settleWithAuth": false,
"returnLinks":[
{
"rel":"default",
"href":"https://mysite.com/return"
}
],
"paymentType":"PAYPAL",
"paymentToken":"PAYPAL PAYMENT TOKEN RECEIVED FROM CLIENT BROWSER"
}
} '
Try out the cURL in a Unix/Cygwin terminal to see the API response. If you have python installed, we recommend that you add the following to the end of the request to format the JSON response | python -m json.tool
Single-use tokens are valid for 5 minutes before they expire. You can convert them to re-usable, permanent payment tokens, which enable you to do things like recurring billing, e.g., pay a subscription.
- For information on converting a credit card single-use token to a permanent token, see Converting a Single-Use Token to a Permanent Token.
- For information on converting a Direct Debit single-use token to a permanent token, see Converting a Single-Use Token to a Permanent Token.
Including the SDK
You include the SDK in your HTML form by adding a <script> element in either the header or body.
Include the Latest Official Version
To include the latest official version of the SDK, use the following:
<head>
<script src="https://hosted.paysafe.com/checkout/v1/latest/paysafe.checkout.min.js"></script>
</head>
Paysafe recommends this approach as you will automatically receive all the latest updates and bug fixes.
Example Payment Form
The following code sample shows a minimal Paysafe Checkout example for card payments that creates a payment overlay for the user to enter their card number, expiry date, and CVV. The overlay contains a payment button that tokenizes the data entered by the user and displays the token (if successful) in the browser console.
<html>
<head>
<script src="https://hosted.paysafe.com/checkout/v1/latest/paysafe.checkout.min.js"></script>
</head>
<body>
<button onclick="checkout()">Create Token</button>
...
<script>
function checkout() {
paysafe.checkout.setup("my Base64 encoded single-use-token API key", {
amount: 5000,
currency: "USD",
environment: "TEST",
companyName: "Example Inc."
}, function(instance, error, result) {
if (result.token) {
console.log(result.token);
console.log(result.paymentMethod);
if (result.paymentMethod=="Cards") {
// use AJAX to send result.token to your merchant server to take CC payment
}
if (result.paymentMethod=="DirectDebit") {
// use AJAX to send result.token to your merchant server to take DD payment
}
if (result.paymentMethod=="Interac") {
// use AJAX to send result.token to your merchant server to take Interac payment
}
if (result.paymentMethod=="PayPal") {
// use AJAX to send result.token to your merchant server to take PayPal payment
}
} else {
// error handling
}
});
}
</script>
</body>
</html>
See more Paysafe Checkout code examples, including 3DS support and close screen handling, on the More Examples page.
Enhancing the Payment Form
You can enhance the payment form in the following ways:
- Supply your store logo using the imageUrl parameter, and your store name using the companyName parameter.
- Supply the customer's name using the holderName parameter to personalize the payment form and associate the customer's name with the single-use token.
- Change the color of the payment buttons to match your website's color scheme using the buttonColor parameter.
- Change the text of the payment button to match your website's business needs using the buttonLabel parameter.
- Hide the "Order total" label and the amount using the hideAmount parameter.
- Mask the CVV in all payment screens to match your website's business needs using the maskCvv parameter.
- Add handling for success and failure with in-overlay success and failure pages showing appropriate messages. See showSuccessScreen and showFailureScreen. Alternatively, you can redirect users to success or failure pages on your site using code similar to window.location.href = "success.html". You should check the payment status before releasing goods or services – do not entirely rely on a redirect.
Paysafe Checkout errors are numbered in the range 9nnn. Errors in the range 7nnn are generated by the Customer Vault, and may be caused by using an invalid single-use token API key, or by using your server-to-server API key rather than the single-use token API key. Errors in the range 3xxx are caused by the Cards API. Errors in the range 2nnn are caused by the Direct Debit API.
Changelog
Version | Description |
---|---|
1.0.0 |
|
1.0.1 |
|
1.1.0 |
|
1.2.0 |
|
1.2.1 |
|
1.2.2 |
|
1.2.3 |
|
1.3.0 |
|
1.3.1 |
|
1.4.0 |
|
1.5.0 |
|
1.6.0 |
|
1.7.0 |
|
1.8.0 |
|
1.9.0 |
|
1.10.0 |
|
1.10.1 |
|
1.10.2 |
|
1.10.3 |
|
1.10.4 |
|
1.10.5 |
|
1.10.6 |
|
1.10.8 |
|
1.11.0 |
|
1.12.0 |
|
1.12.1 |
|
1.12.2 |
|
1.12.3 |
|
1.12.4 |
|
1.13.0 |
|
To download a PDF copy of this document in French, click here.