Overview

Paysafe Checkout allows merchants to take payment from credit cards, and bank accounts 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 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 web site 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 flow, you will have to contact Paysafe support to enable the API key for the Direct Debit API. You will also have to contact Paysafe support to configure your account so that Direct Debit is visible as a payment method in the Paysafe 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.

The obtain a single-use token-generating key:

  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.
    The Single-Use Token area in the API key page updates to show the username 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 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 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:

Try Now

Click the button below, and in the overlay, select either:

  • CARD
  • DIRECT DEBIT

If you select CARD, 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.

If you select DIRECT DEBIT, type an Address, City and ZIP Code, and then click NEXT: Account Details; finally, 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.

The token will be displayed below and in the example cURL request, which shows how you can take payment on your server.

Card Payment Example

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

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"
    }
   } '

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 (perhaps used to pay a subscription).

You can convert single-use tokens to permanent tokens in the following ways:

  • By using them to create a profile in the Customer Vault. If the token is for a card payment, Paysafe recommends that before you create the profile, you should verify that the token corresponds to a valid card. If the token is for a DD payment, ensure that you create the profile for the correct bank account type: ACH or EFT.
  • For DD payments, use the single-use token in a request to either the /standalonecredits or /purchases endpoint that includes "replaceWithMultiUsePaymentToken": true.

Including the SDK

The SDK is located at https://hosted.paysafe.com/checkout/version/paysafe.checkout.min.js; and 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 bugfixes.

Include a Specific Version

Each specific version of 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 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>
		...
		<script>
			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
		    	    }
	                     
				} else {

					// error handling
				}        
			});
		</script>
	</body>

</html>

See more Paysafe Checkout code examples including 3DS support and close screen handling 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 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.
  • 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" . Note, 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 which 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.4.0
  • Added stricter validation for amount.
  • Paysafe rebranding - default button color changed.
  • Improved performance under Internet Explorer 11 and Edge.
Did you find this page useful?