Overview

Paysafe.js allows merchants to create a customized payment form while still complying with the least demanding level of PCI compliance, SAQ-A. Each of the sensitive payment fields (card number, cvv, and expiry date or expiry year and month) are displayed in their own small iframe hosted on Paysafe's servers. The user input and storage of these fields is handled by Paysafe. Paysafe.js makes use of the Customer Vault and Card Payments REST APIs.

Advantages

  • Complies with PCI SAQ-A.
  • Paysafe handles security for the sensitive fields.
  • Extensive customization options allow 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 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.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 base 64 encoding. See authentication for more details.

Try Now

Enter a test card value below 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

Payment Details

Link to codepen for the above example

How to Use the SDK

  1. Create an HTML payment form with the content (text, images, etc.) and style you require. You can view a video describing how to create a custom payment form here.
  2. Include the Paysafe.js JavaScript SDK in the header of your HTML payment form.
  3. Add empty container elements (typically divs) to your HTML for each of the sensitive payment fields, e.g., card number, cvv, and expiry date.
  4. Call the SDK setup function with your single-use token API key. The setup function inserts iframes hosted on Paysafe's servers inside these containers. These iframes contain input fields to capture the payment data.
  5. Finally, add a 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 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.

Enhancing the Payment Form

You can enhance the Payment form in two ways:

  • Styling the payment fields by passing any of the supported subset of CSS commands as part of the styles section of the setup function.
  • By using the SDK on function to subscribe to a defined set of events inside the hosted field iframes. These correspond to user actions while using these fields such as entering an invalid card number, selecting the field (focus), etc. You can then respond to these events in your payment form.

Including the SDK

There are two ways to include the SDK:

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

Include a Specific Version

The SDK is located at https://hosted.paysafe.com/js/version/paysafe.min.js. Replace version with the specific version of the SDK you wish to use.

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.

Include the Latest Release of a Specific Major Version

If you want to include the last version 1 release for example rather than including the latest version you can use the following:

Paysafe recommends this approach as you will automatically receive updates and bugfixes.

Example Payment Form

The following code sample shows a simple Paysafe.js example that creates a payment form with three sensitive fields: Card number, Expiry date and CVV. The example contains a payment button that tokenizes the data entered by the user and displays the token (if successful) in the browser console.

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 random CVV and click Pay for a successful tokenization. Codepens 2 and 3 show additional Paysafe.js features such as styling and basic event handling.

  1. Simple example (the example above)

    https://codepen.io/paysafe/pen/KvyMeE/

  2. Simple example with basic styling

    https://codepen.io/paysafe/pen/rzYLgO/

  3. Simple example with basic styling and event handling

    https://codepen.io/paysafe/pen/yoPJmB/

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

Further Details

The SDK consists of the setup and a number of instance functions. Finally, there are a number of fields functions. Click on the links below to view detailed information about each function.

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 or not.
instance.fields.<fieldname>.isValid Checks if the named field is valid.
instance.areAllFieldsValid Checks if all fields are valid.

Changelog

Version Description
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.2.0 Added support for assigning billing address and holder name to the issued token.
Did you find this page useful?