Search Overlay

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 VaultCard 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:

  1. SIGN UP to get a Test account, if you haven't already done so.
  2. 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.
  3. In the Single-Use Token area, click the Create button.
  4. 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.
  5. 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

  1. Include the Paysafe Checkout SDK in your HTML payment form.
  2. 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.
  3. 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:
  • 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.

Including the SDK

The SDK is located at https://hosted.paysafe.com/checkout/version/paysafe.checkout.min.js. You include it in your HTML form by adding a <script> element in either the header or body.

There are two ways to include the SDK:

  • Include the latest official version – Paysafe strongly recommends this approach.
  • Include a specific version.

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.

Include a Specific Version

Each specific version of the SDK is located at https://hosted.paysafe.com/checkout/version/paysafe.checkout.min.js. To include one of these, replace version with the version of the SDK you wish to use, for example:

<head>
<script src="https://hosted.paysafe.com/checkout/<version>/paysafe.checkout.min.js"></script>
</head>

Paysafe maintains compatibility between minor versions. For example, version 1.X.Y is compatible with version 1.V.W, but version 2.A.B would not be compatible with any version 1 release.

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
  • Paysafe Checkout launched.
1.0.1
  • Fixed "Failed to initialize Paysafe Checkout iframe." error incorrectly returned by setup function.
1.1.0
  • Added support for issuing Direct Debit tokens.
1.2.0
  • Added a correlationId in the error object returned from the Paysafe Checkout. The correlationId represents a unique ID that can be provided to the Paysafe Support team as a reference for investigation.
  • Fixed a bug related with the displaying of card brand logo for some Discover and Maestro cards.
  • Minor user interface improvements and bug fixes.
1.2.1
  • Added more strict validation for the merchant API key.
1.2.2
  • User interface improvements for Direct Debit on MacOS and iOS devices.
1.2.3
  • Fix holderName parameter validation for "setup" function.
  • Return "Invalid apiKey parameter." error on setup callback instead of "Failed to initialize Paysafe Checkout." when a not configured API Key is used.
1.3.0
  • Added support for issuing Interac Online single-use payment tokens.
1.3.1
  • Fixed small UI glitches under Internet Explorer.
  • Fixed an issue with error being thrown when "preferredPaymentMethod" is Interac Online.
1.4.0
  • Added stricter validation for amount.
  • Paysafe rebranding – default button color changed.
  • Improved performance under Internet Explorer 11 and Edge.
1.5.0
  • Added support for ThreatMetrix.
1.6.0
  • Added support for issuing PayPal single-use payment tokens.
  • Added Payment Method Management functionality. User can express intention to have the card saved in their profile. User can edit the card expiry date or delete the card.
  • Added more strict validation for the "billingAddress.country" and "currency".
  • Added property to control the visibility of "Order Total" label.
  • Added support for specifying the payment button label.
1.7.0
  • Added support for specifying title of the success/failure screen.
  • Added support for specifying shipping address options for PayPal.
1.8.0
  • Added support for 3D Secure Version 2 with minimum required fields.
1.9.0
  • Added support for all fields related with 3D Secure Version 2.
  • Improved expiry date validation.
  • Improved card brand recognition.
  • Added support for formatting the amount according to the set locale.
  • Updated Canadian French translations.
1.10.0
1.10.1
  • Performance and Stability updates.
  • Improve tracing.
1.10.2
  • Bug fixes on MS Edge
1.10.3
  • Bug fixes
1.10.4
1.10.5
  • Add force3DS1 flag.
1.10.6
  • Added newly supported currencies
1.10.8
  • Update Interac French Translation
1.11.0
  • Extend Accessibility
1.12.0
  • Create the ability for PS Checkout v1 to route 3DS2 requests to an Amex-dedicated account.
1.12.1
  • Accessibility improvements.
1.12.2
  • Improved Error Tracing
1.12.3
  • Bug Fixes
1.12.4
  • Add initialization timeout
1.13.0
  • Security and Performance improvements

To download a PDF copy of this document in French, click here.