Paysafe Checkout allows merchants to take payment using a secure overlay while complying with the least demanding level of PCI compliance, SAQ-A. The user input and storage of card data is handled by Paysafe. Paysafe Checkout features a simple integration and makes use of Paysafe's Customer Vault and Card Payments REST APIs.


  • Complies with PCI SAQ-A.
  • Simple integration.
  • Paysafe handles security for card details.
  • No redirection required.
  • Supports processing payments with 3-D-Secure enabled cards.

Before You Begin

Before continuing, you will need to obtain your single-use token generating API key from the merchant back office and the standard server-to-server API key.

The single-use token API key is an API key that is used in your JavaScript code on the client to generate single-use tokens from customer credit cards. 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.

The process is as follows:

  1. SIGN UP to get a Test account, if you haven't already done so.
  2. Login to the test back office. Sign in with the username and password you used when signing up for the test account. You should now see the 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.
  5. The single use token area in the API key page will now update to show the username and password for the single-use token API key.
  6. 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 signup 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 JavaScript file in the header or body of 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, tokenization failure, etc.
  3. The callback should use AJAX to send the token representing the customer's card to your merchant server, where the standard Card Payments API authorization endpoint can be used to make payment. See the following topic for more details.

Try Now

Click the button below. Enter a test card value e.g. 4111 1111 1111 1111, a valid future expiry date, a random three digit CVV, and click Pay for a successful tokenization. The token will then be shown in the Curl example below which shows how you can take payment on your server. Try this out in a Unix / Cygwin terminal to see the API response. If you have python installed, then we recommend that you add the following to the end of the Curl request to format the response | python -m json.tool

Single-use tokens are valid for 5 minutes before expiring. You can convert them to re-usable, permanent payment tokens by using them to create a profile in the Customer Vault. Paysafe recommends that you verify that the single-use token corresponds to a valid card before creating the profile. Permanent tokens make it possible to implement capabilities such as recurring billing (perhaps used to pay a subscription) or a "remember me" feature.

Including the SDK

The SDK is located at https://hosted.paysafe.com/checkout/version/paysafe.checkout.min.js.

Paysafe maintains compatibility between minor versions. For example, version 1.X.Y is compatible with version 1.V.W but version 2.12 would not be compatible with version 1.34. There are two ways to include the SDK:

  • Include the latest release of a specified major version - Paysafe recommends this approach.
  • Include a specific version.

Include the Latest Release of a Specific Major Version

If you want to include the last version 1 release you can use the following:

Paysafe recommends this approach as you will automatically receive updates / bug fixes.

Include a Specific Version

Include a specific version of the SDK as follows:

Example Payment Form

The following code sample shows a minimal Paysafe Checkout example 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.

See more Paysafe Checkout code examples including 3DS support, close screen handling, etc. in the following topic.

Enhancing the Payment Form

You can enhance the Payment form in the following ways:

  • Supply your store logo using the imageUrl parameter and 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.
  • Add handling for success and failure with in-overlay success and failure pages showing appropriate messages. See showSuccessScreen and showFailureScreen. Alternatively, you just redirect users to success or failure pages on your site using e.g. window.location.href = "success.html" . Note you should check the payment status before releasing goods or services and not just rely on a redirect.

Paysafe Checkout errors are numbered in the range 9nnn. Errors in the ranges 1nnn or 5nnn are generated by the Customer Vault (or 3D-Secure API if you have enabled 3D-Secure). Some examples or actions that could cause Customer Vault errors include using an invalid single-use token API key or using your server to server API key rather than the single-use token API key. A 3D Secure error, might be supplying an account which does not support 3D Secure.


Version Description
1.0.0 Paysafe Checkout launched.
1.0.1 Fixed "Failed to initialize Paysafe Checkout iframe." error incorrectly returned by setup function.
Did you find this page useful?