Paysafe.js, powered by Payments API, 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.


  • 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

Paysafe will provide you with the credentials in the Business Portal. To access your Public API key, sign in to the Business Portal.

Contact your business relationship manager or reach out to integrations@paysafe.com for your credentials to the Business Portal.

To obtain the Public API key from the Business Portal:

  1. Go to Integrate>API Keys
  2. For Public Key, click the Copy icon to copy the API key.

Your API key will have the following format:

  • Key Username – MerchantXYZ
  • Key Password – B-tst1-0-51ed39e4-312d02345d3f123120881dff9bb4020a89e8ac44cdfdcecd702151182fdc952272661d290ab2e5849e31bb03deede7e

Paysafe.js uses the Base64-encoded version of the 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 More about Authentication for details.

How to Use the SDK

  1. Create your custom HTML payment form with the content (text and images) and style you require.
  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.createPaymentHandle function to the Pay button's click event. This returns a single-use payment token. Single-use tokens are valid for only five minutes.
  6. Send the payment handle token to your merchant server, where the standard Paysafe Payments API https://api.paysafe.com/paymenthub/v1/payments can be used to make payment.

The following diagram illustrates interaction between the Paysafe server and the merchant:

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:

  • Include the latest version or
  • Include a specific version

Include the Latest Version

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

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

Include a Specific Version

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

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

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 creates a payment handle from the user-entered data and (if create payment handle is successful) displays the token in the browser console.

            var options_new = {
        "amount": 123,
        "paymentType": "CARD",
        "holderName": "John Smith",
        "billingDetails": {
            "nickName": "John Dee",
            "street": "20735 Stevens Creek Blvd",
            "street2": "Montessori",
            "city": "Cupertino",
            "zip": "95014",
            "country": "US",
            "state": "CA"
          "shippingDetails": {
            "recipientName": "John",
            "street": "20735 Stevens Creek Blvd",
            "street2": "Montessori",
            "city": "Cupertino",
            "zip": "95014",
            "country": "US",
            "state": "CA"
        "merchantRefNum": "1608104239085",
        "merchantDescriptor": {
            "dynamicDescriptor": "Test Description",
            "phone": "123456"
        "profile": {
            "firstName": "Vishnu",
            "lastName": "Vardhan",
            "email": "vishnu@paysafe.com",
            "phone": "1231231231",
            "dateOfBirth": {
              "day": 1,
              "month": 7,
              "year": 1990
        "threeDs": {
            "deviceChannel": "BROWSER"
            paysafe.fields.setup("my Base64 encoded single-use-token API key", options, function(instance, error) {
                if (error) {
                } else {
                    var payButton = document.getElementById("payButton");
                    payButton.addEventListener("click", function (event) {
                        instance.createPaymentHandle(options_new,function(instance, error, result) {
                            if (error) {
                            } else {
                                // handle result

SDK Functions

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 the setup is complete.

Triggers the single use payment handle API call that provides a single-use payment handle token for use with the Paysafe Payments API.

instance.on Subscribe to events thrown by the instance.
instance.fields.<fieldname>.on Subscribe to events thrown 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.
Did you find this page useful?