Setup

The setup function creates and initializes the Paysafe.js payment methods inside the selected HTML element containers (typically div elements) on your payment page.

This function has the following parameters:

    1. The Base64-encoded version of the single-use token API key is used to authenticate with the Payment Hub REST API.

      Note that this key can be used only to generate single-use tokens for use with the Payments API and has no other API access rights (such as for taking payments). Consequently, it can be exposed publicly in the user's browser.

    2. An options object containing the environment to use (Test or Live), details of the fields you wish to create (including CSS selectors for the container elements on your payment page), and style for the hosted fields.

The function signature is as follows:

paysafe.fields.setup(apikey,options)
    .then((instance) => {/** Continue with instance.show() */})
    .catch((error) => {/** Process any errors during the setup*/})

or you can use Async-await:

async function setupPaysafeJS() {
    try {
        const instance = await paysafe.fields.setup(apikey,options)
        /** Continue with instance.show() */
    } catch(error) {
        /** Process any errors during the setup*/
    }
}

The options object contains four main sections: currencyCode, environment, fields, and style, described below.

Currency Code

The currencyCode string is used to enable the Payment API integration and promises interface in Paysafe JS.

The currencyCode accepts 3 letter abbreviations of any of the ISO standard currencies.

When a currencyCode is not provided, Paysafe JS integration will not create Payment Handle, but Single Use Payment tokens, which are processable only directly through the Cards API. Refer to Paysafe JS callback SDK documentation for integration guideness.

const instance = await paysafe.fields.setup(
    "my Base64 encoded single-use-token API key",
    {
        currencyCode: "USD",
        fields: {...}
    }
);

paysafe.fields.setup(
    "my Base64 encoded single-use-token API key",
    {
        currencyCode: "USD",
        fields: {...}
    }
).then(instance => {
    /** Continue with instance.show() */
}).catch(error => {
    /** Process any errors during the setup*/
});

Environment

The environment string is used to select the environment to use for tokenization. The accepted environments are LIVE (the Paysafe Production environment) and TEST (the Paysafe Merchant Test or Sandbox environment).

Do not use real card numbers or other payment instrument details in the Merchant Test environment. It is not compliant with Payment Card Industry Data Security Standards (PCI-DSS) and does not protect cardholder/payee information. Any upload of real cardholder data is strictly prohibited, as described in the Terms of Use.

Test

const instance = await paysafe.fields.setup(
    "my Base64 encoded single-use-token API key",
    {
        environment: "TEST",
        currencyCode: ...,
        fields: {...}
    }
);

paysafe.fields.setup(
    "my Base64 encoded single-use-token API key",
    {
        environment: "TEST",
        currencyCode: ...,
        fields: {...}
    }
).then(instance => {
    /** Continue with instance.show() */
}).catch(error => {
    /** Process any errors during the setup*/
});

Live

const instance = await paysafe.fields.setup(
    "my Base64 encoded single-use-token API key",
    {
        environment: "LIVE",
        currencyCode: ...,
        fields: {...}
    }
);

paysafe.fields.setup(
    "my Base64 encoded single-use-token API key",
    {
        environment: "LIVE",
        currencyCode: ...,
        fields: {...}
    }
).then(instance => {
    /** Continue with instance.show() */
}).catch(error => {
    /** Process any errors during the setup*/
});

If you omit the environment object—by passing an empty or null value for this parameter—the Live environment is used.

Fields

The fields object specifies the hosted fields to create. The following options are available for each field:

  • selector – the CSS selector to use to locate the container for this field on your payment page.
  • placeholder – the placeholder text to insert in this field to tell the customer what to insert.
  • the separator character used between groups of digits in the card number field.
  • optional - specifies whether the field is optional.
  • masked - specifies whether the CVV field should be masked.
  • accessibilityLabel - specifies a field title, which will be read by the Screen Readers.
  • iframeTitle - specifies an iframe title, which will be read by the Screen Readers.
  • accessibilityErrorMessage - specifies an error message, which will be read by the Screen Readers on validation error.

Applepay Button Fields:

These options are applicable only for integration with Apple Pay.

  • label - specifies the label, which will be shown in the Apple Pay payment window
  • type - specifies the text of the Apple Pay button
  • color - specifies the color of the Apple Pay button

You can include either one or two date fields and an ApplePay payment button:

OptionField

Card details with a single date field

  • cardNumber
  • cvv
  • expiryDate

expiryDate uses the mm/yy format

Card details with multiple date fields
  • cardNumber
  • cvv
  • expiryYear
  • expiryMonth
ApplePay Integration
  • applePay

Improving accessibility through the options

The optional parameters accessibilityLabel, iframeTitle, and accessibilityErrorMessage are exposed in order to increase the accessibility's flexibility. These parameters affect the way Screen reader tools will present the inputs.

<html>
  ...
  <body>
    <div id="cardNumber"></div>
    <div id="cvv"></div>
    <div id="expiryDate"></div>
    <script>
     paysafe.fields.setup("my API key", {
        fields: {
          cardNumber: {
            selector: "#cardNumber",
            accessibilityLabel: "Card number",
            placeholder: "00000000000000",
            iframeTitle: "Credit card details container",
            accessibilityErrorMessage: "Invalid card number"
          },
          cvv: {
            selector: "#cvv"
          },
          expiryDate: {
            selector: "#expiryDate"
          }
        }
      }).then(instance => {...});
    </script>
  </body>
</html>

See the decision-making matrix for Screen Readers support of accessibilityLabel and placeholder:

Field PropertyHTML Result
titleaccessibilityLabelPlaceholdertitle value (this value will be read by the Screen Reader in presenting mode)arie-labelledby value (this value will be read by the Screen Reader)

Credit card number input frame

Card Num***

Credit card number input frame

Card Num
Credit card number input frame<none>Enter Card NumberCredit card number input frameEnter Card Number
<none>Card Num<none>secured (this is a default value)Card Num
<none><none><none>secured (this is a default value)Card Number (this is a default value when neither placeholder nor accessibility label is specified)

See the decision-making matrix for Screen Readers support of accessibilityErrorMessage:

accessibilityErrorMessageEventaria-describedby value (which will be read by the Screen Reader)input aria-describedby attribute (the id of the error message)
Invalidon load<empty>null
Invalidon valid<empty>null
Invalidon Invalid<empty> (except invalid events depending on the current field (CVV, Expiry month)aria-describedby
Invalidon focus (when valid)<empty>null
Invalidon focus (when invalid)Invalidaria-describedby
<none>on load<empty>null
<none>on valid<empty>null
<none>on Invalid<empty> null
<none>on focus (when invalid)<empty> null
<none>on focus (when invalid)<empty> null

Styles

The style option enables you to specify several CSS styles for your fields using JavaScript syntax. For example:

<html>
    ...
    <body>
    ...
        <script>
            paysafe.fields.setup("my Base64 encoded single-use-token API key", {
                style: {
                    input: {
                        "font-family": "robotoregular,Helvetica,Arial,sans-serif",
                        "font-weight": "normal",
                        "font-size": "14px"
                    },
                    "#card-number.valid": {
                        "color": "green"
                    },
                    ":focus": {
                        "color": "yellow"
                    }
                }
            }).then(instance => {...});
        </script>
    </body>
</html>

Ids and classes are added to the input fields, which can be used as CSS selectors; you can also include pseudo-selectors, such as :focus.

Setup Error Object

The following table describes the contents of the error object:

ParameterRequiredTypeDescription
codetruestringError code
displayMessagetruestringError message for display to customers.
detailedMessagetruestringDetailed description of the error (this information should not be displayed to customers).
correlationIdtruestringUnique error ID to be provided to Paysafe Support during investigation.

Setup Function and Objects

The following table lists the setup function parameters and the JavaScript objects used by the setup function and the parameters they contain.

ParameterRequiredTypeDescription
apiKeytruestringThe Base64-encoded version of the single-use token API key which is used to authenticate with the Payment Hub REST API.
optionstrueobjectEncapsulates the environment, fields, and style.
{return}falsePromisePromise that will be resolved to the hosted fields instance object
options
currencyCodetruestring

The payment currency of the merchant account, for example, USD for US dollars.

That currency code will be used to preload the merchant configurations like supported card brands and transaction salvage.

When there is a single account configured for that currency and payment type, it will be used for tokenization.

environmentfalsestring

Environment to use for all tokenization and logging calls; either:

  • LIVE – used for Production
  • TEST – used for the Test or sandbox environment
fieldsfalseobjectConfiguration for the specified fields.
stylefalseobjectJavascript representation of the CSS properties to apply to the fields.
initializationTimeoutfalsenumberThe maximum time (in milliseconds; default is 5000) that the SDK will wait for the iframes to get ready before returning an error.
thresholdfalsenumber

The threshold value is specific to transaction salvage flow. Specifies the maximum decline rate of a card bin.

accountsfalseobject

The accounts which will be used to preload the merchant configurations from the admin portal when the merchant is configured for multiple accounts from the same Currency.

If accounts value is not provided, Paysafe JS will try to guess the account for setup based on the merchant configuration in the admin portal.

accounts
defaulttrue (conditional)number

The account will be used for all payment types if anything else is not provided.

It is required if accounts object is provided

applePayfalsenumber

The account will be used for Apple Pay integration.

By default, if no applePay account is provided, the value from accounts.default will be used.

fields
fieldNamefalsestring

The field name to configure:

  • cardNumber
  • cvv
  • expiryDate
  • expiryYear
  • expiryMonth
  • applePay
selectortruestringCSS selector that uniquely identifies the empty container in which to insert the field iframe.
placeholderfalsestringPlaceholder for the iframe input element.
accessibilityLabelfalsestringAn accessibility label that will be read from the Screen Readers, if the client uses any (default - When no accessibility label is specified, the placeholder's value is used. If there is neither accessibilityLabel nor a placeholder, the default value is Card Number/CVV/Card expiry date/Card expiry month/Card expiry year)
accessibilityErrorMessagefalsestringAn error message which will be read from the Screen Readers when the field is invalid (if the client uses any). Empty by default.
iframeTitlefalsestringThe title that will be assigned to the iframe. The default value is 'secured'.
separatorfalsestring

Available for the card number field only. If no separator is specified the default is white space (" "). Accepted values are: null, undefined, "", " ", "-".

If the separator value is null or undefined, no separator is applied. If the separator is " " or "-", this is automatically added after every 4 digits when a card number is entered (e.g., "4532-5647-1747-9616", "4078 2050 3082 0").

optionalfalseboolean

Available for all fields only when using saved card functionality (passing of singleUseCustomerToken and paymentTokenFrom on tokenize function), otherwise available for the CVV field only.

Defaults to "false". If the value is "true", the field will not be required for making a tokenization, but will be validated if it is not empty.

maskfalseboolean

Available for the CVV field only.

Defaults to "false". If the value is "true" the CVV value will be masked.

labeltrue (when the field is applePay)string

Available for the applePay field only.

Label displayed immediately after the "Pay" button on the Apple Pay payment window.

typefalsestring

Available for the applePay field only.

The Apple Pay button type.Choose from:

  • "pay" - the default
  • "buy"
  • "donate"
colorfalsestring

Available for the applePay field only.

The Apple Pay button color. Choose from:

  • "black" - the default
  • "white"
  • "white-outline"
style
cssSelectorNamefalseobject

CSS selector that identifies the element to which that the passed styles apply.List of ids:

  • cvv
  • card-number
  • expiry-date
  • expiry-year
  • expiry-month

List of classes:

  • valid
  • invalid
cssSelectorName
cssStyleNamefalsestring

Name of the CSS style that should be applied and the corresponding value. Supported CSS style names:

  • color
  • opacity
  • letter-spacing
  • text-align
  • text-indent
  • text-decoration
  • text-shadow
  • font
  • font-style
  • font-weight
  • font-size
  • line-height
  • font-family
  • transition
  • -ms-filter

Setup Errors

CodeDisplay MessageDetailed MessageDescription
9012There was an error (9012), please contact our support.Invalid number of arguments.The supplied number of arguments is different than 2.
9013There was an error (9013), please contact our support.Invalid apiKey parameter.The supplied apiKey parameter is not a string.
9014There was an error (9014), please contact our support.Unhandled error occurred.An error that was not handled by the Paysafe.js sdk has been thrown.
9015There was an error (9015), please contact our supportInvalid options argument.The supplied options parameter is not an object.
9016There was an error (9016), please contact our supportInvalid style options.The supplied style options are not an object or an array.
9017There was an error (9017), please contact our supportEnvironment options is not a string or an object.The supplied environment is not a string or an object.
9018There was an error (9018), please contact our supportEnvironment doesn't match any of the predefined values (possible: TEST, LIVE; actual: ${environment}).
9019There was an error (9019), please contact our supportEnvironment url should be non-empty string.The environmentUrl is empty or not a string.
9021There was an error (9021), please contact our supportCSS selector value for ${styleName} is not an object.The selector value is not an object or array.
9022There was an error (9022), please contact our supportThe CSS property ${styleName}.${propertyName} should be string or number.The supplied styles contain a property with a value that is not a string or number.
9023There was an error (9023), please contact our supportNo container element was found using ${fieldName} selector.
9024There was an error (9024), please contact our supportMore than one container element was found using ${fieldName} selector.
9025There was an error (9025), please contact our supportThe same container was found for both ${firstField} and ${secondField}
9026There was an error (9026), please contact our supportWrong expiry date field configuration! Either expiryDate or both expiryMonth and expiryYear should be set.
9028There was an error (9028), please contact our supportFailed to initialize Paysafe.js iframes.The iframes used for the sensitive payment fields failed to initialize within 5 seconds. This could occur if the server that generates the HTML for the iframe is not available.
9029There was an error (9029), please contact our support${fieldName} placeholder should be string.
9030There was an error (9030), please contact our supportCard number separator should be string.
9031There was an error (9031), please contact our supportInvalid card number separator.The value specified for the card number separator is not null, undefined, "" (empty string), " " (white space) or "-" (dash).
9032There was an error (9032), please contact our support${fieldName} accessibilityLabel should be string.Used when accessibilityLabel is not a valid string.
9033There was an error (9033), please contact our supportSelector should be set either on all fields or on none.The selector was set on only some of the fields. For example, the setup options specified cardNumber, cvv and expiryDate, but there are selectors only for cardNumber and cvv.
9072There was an error (9072), please contact our support${fieldName} accessibilityErrorMessage should be string.Used when accessibilityErrorMessage is not a valid string.
9078There was an error (9078), please contact our supportInvalid optional ${fieldName} parameter.
9079There was an error (9079), please contact our support${fieldName} cannot have optional parameter.
9082There was an error (9082), please contact our supportinitializationTimeout should be number greater than zero.
9097There was an error (9097), please contact our support${fieldName} iframeTitle should be string.Used when iframeTitle is not a valid string.
9055There was an error (9055), please contact our supportInvalid currency parameter.The currencyCode is not a valid ISO currency
9061There was an error (9061), please contact our supportInvalid account ID for ${paymentMethod}.The accounts.{account} is not a valid account id
9099There was an error (9099), please contact our supportInvalid threshold parameter.The threshold provided is not a valid number between 0 and 100
ApplePay Specific Errors
Did you find this page useful?