Search Overlay

Overview

  • Payments
  • Canada
  • Europe & UK
  • United States

Paysafe.js enables merchants to create a customized payment form that complies with the least demanding level of PCI compliance, SAQ-A. All the sensitive payment fields (card number, cvv, and expiry date or expiry year and month) are displayed in an iframe hosted on Paysafe Group's servers, and the user input and storage of the data is handled by Paysafe Group. Paysafe.js makes use of the Customer Vault and Card Payments REST APIs to handle the payment.

Advantages

  • Complies with PCI SAQ-A, because Paysafe Group handles security for the sensitive fields.
  • Extensive customization options enable you to create your own payment form that matches your website.
  • Create as many translated or localized versions of your payment form as required.
  • Fast page load times.
  • No redirection required.
  • Embeds naturally and remains invisible.
  • Supports processing payments with 3D Secure-enabled cards.

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.

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.js 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 Base64 encoding. See Authentication for details.

Try in CodePen

You can see a brief demonstration of Paysafe.js in CodePen.

Enter a test card number (for example, 4111 1111 1111 1111), a valid future expiry date, a random three digit CVV, and then click Pay.

The following cURL example 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, we recommend that you add the following to the end of the cURL request to format the JSON response clearly:

| python -mjson.tool

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

How to Use the SDK

  1. Create your custom HTML payment form with the content (text and images) and style you require. The video below describes how to create such a form.
  2. Include the Paysafe.js JavaScript SDK (paysafe.min.js) <script> tag in the <head> element of your HTML payment form.
  3. Add empty container elements (typically <div>) to your HTML for each of the sensitive payment fields: card number, cvv, and expiry date.
  4. Call the SDK fields.setup function with your single-use token API key. The setup function inserts iframes hosted on Paysafe Group's servers inside these containers. These iframes contain input fields to capture the payment data.
  5. Finally, add the instance.tokenize function to the Pay button's click event. This returns a single-use payment token (the token representing the card data entered by the user is stored in the Customer Vault). Single-use tokens are valid for only 5 minutes and are not consumed by verification.
  6. Send the token to your merchant server, where the standard Card Payments API authorization endpoint can be used to make payment.

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 or create a "remember me" feature.

  • 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.

Enhancing the Payment Form

You can enhance the Payment form in these ways:

  • You can style the payment fields by passing certain CSS commands as part of the style section of the options object in the fields.setup function.
  • By using the SDK on function to subscribe to events inside the hosted field iframes that correspond to user actions, such as entering an invalid card number or selecting the field (focus); you can then respond to these events in your payment form.

Including the SDK

When you include the SDK <script> tag in the <head> element, either:

  • Include the latest version
  • Include a specific version

Paysafe Group recommends including the latest version of the SDK as you will automatically receive all the latest updates and bugfixes.

Include the Latest Version

To include the latest version of the SDK, use the following:

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

Include a Specific Version

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

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

Paysafe Group 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 is a simple Paysafe.js code sample that creates a payment form with three sensitive data fields: Card number, Expiry date and CVV; it contains a payment button that triggers tokenization of the user-entered data and (if tokenization was successful) displays the token in the browser console.

<!-- Basic Paysafe.js example -->
<html>
<head>

<!-- include the Paysafe.js SDK -->
<script src = "https://hosted.paysafe.com/js/v1/latest/paysafe.min.js"></script>

<!-- external style for the payment fields.internal style must be set using the SDK -->
<style>
.inputField {
border: 1px solid #E5E9EC;
height: 40px;
padding - left: 10px;
}
</style>

</head>
<body>

<!-- Create divs for the payment fields -->
<div id = "cardNumber" class="inputField" ></div>
<p></p>
<div id = "expiryDate" class="inputField"></div>
<p></p>
<div id = "cvv" class="inputField"></div>
<p></p>

<!-- Add a payment button -->
<button id = "payNow" type = "button"> Pay now </button>

<script type = "text/javascript">

// Base64-encoded version the Single-Use Token API key.
// Create the key below by concatenating the API username and password
// separated by a colon and Base 64 encoding the result
var apiKey = "Your Base64-encoded Single-use-Token Api Key";

var options = {

// select the Paysafe test / sandbox environment
environment: "TEST",

// set the CSS selectors to identify the payment field divs above
// set the placeholder text to display in these fields
fields: {
cardNumber: {
selector: "#cardNumber",
placeholder: "Card number",
separator: " "
},
expiryDate: {
selector: "#expiryDate",
placeholder: "Expiry date"
},
cvv: {
selector: "#cvv",
placeholder: "CVV",
optional: false
}
}
};

// initalize the hosted iframes using the SDK setup function
paysafe.fields.setup(apiKey, options, function(instance, error) {

// When the customer clicks Pay Now,
// call the SDK tokenize function to create
// a single-use payment token corresponding to the card details entered
document.getElementById("payNow").addEventListener("click", function(event) {
instance.tokenize(function(instance, error, result) {
if (error) {
// display the tokenization error in dialog window
alert(JSON.stringify(error));
} else {
// write the Payment token value to the browser console
console.log(result.token);
}
});
}, false);
});
</script>
</body>
</html>

You can try out the HTML code example above using the first CodePen below. Enter a test card value, a valid future expiry date, and a random CVV, and then click Pay to trigger tokenization. CodePens 2 and 3 include basic form styling and event handling.

1. Simple example

    Refer to the example code.

2. Simple example with basic styling

    Refer to the example code.

3. Simple example with basic styling and event handling

    Refer to the example code.

Paysafe.js 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.

Further Details

The SDK consists of the setup function, several instance functions (including several field functions). Click the links below for full details.

Function Purpose
Main Functions
setup Populates the specified containers (typically div containers) on your payment form with iframes for each of the sensitive fields. Sets the style and placeholder text (e.g., Card number) for these fields along with an optional card number separator. Provides access to the instance object used by the functions below in a callback once setup is complete.
instance.tokenize

Triggers the tokenization process that provides a single-use payment token for use with the Card Payments API.

instance.on Subscribe to events emitted by the instance.
instance.fields.<fieldname>.on Subscribe to events emitted by a particular field.
Additional Functions
instance.fields.<fieldname>.<event type> Shorthand event registration—a shorthand method of registering for events. This is an alternative to the on function.
instance.getCardBrand Retrieves the current card brand.
instance.cardBrandRecognition Subscribe to the cardBrandRecognition event.
instance.submit Subscribe to the submit event.
instance.fields.<fieldname>.isEmpty Checks if the named field is empty.
instance.fields.<fieldname>.isValid Checks if the named field is valid.
instance.areAllFieldsValid Checks if all fields are valid.
instance.resetCardDetails Clears previously inserted card data in all fields. Optionally expiry date can be prefilled by passing it as argument.

Version Description
1.0.0 Paysafe.js launched.
1.1.0 Added support for processing payments for cards (Visa and Mastercard) enrolled in 3D Secure.
1.1.1
  • Dragging and dropping text into payment fields now triggers events.
  • Added support for mobile device browsers: Mozilla Firefox and Google Chrome.
1.1.2 Security improvements.
1.2.0 Added support for assigning billing address and holder name to the issued token.
1.2.1 Redesign of 3DS overlay.
1.3.0 Added a correlationId in the error object returned from Paysafe Group. The correlationId represents a unique ID which can be provided to the Paysafe Group Support team as a reference for investigation.
1.3.1 Fixed emitting focus and blur events in Safari under MacOS and iOS.
1.3.2 Added more strict validation for the merchant API key.
1.4.0
1.4.1 Fixed support for screen reader sofware (NVDA) under Internet Explorer 11.
1.5.0 Added support for 
1.6.0 Added more strict validation for the amount.
1.7.0 Added support for autocomplete of card numbers.
1.8.0 Added support for ThreatMetrix.
1.9.0 Added more strict validation for the "billingAddress.country" and "currency".
1.10.0 Added support for 3D Secure Version 2 with minimum required fields.
1.10.1 Fixed autocomplete issue, expiry date was not being filled in by browser.
1.11.0
  • Added support for all fields related with 3D Secure Version 2.
  • Improved expiry date validation.
  • Improved card brand recognition.
1.12.0 Added support for masking the CVV.
1.14.0 Added Saved Cards functionality.