Search Overlay

Setup

The setup function creates and initializes the Paysafe.js frames inside the selected HTML element containers (typically div elements) on your payment page. This function has the following parameters:

  • The Base64-encoded version of the single-use token API key used to authenticate with the Customer Vault REST API. Note that this key can be used only to generate single-use tokens for use with the Card 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.
  • 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 styling for the hosted fields.
  • A callback to notify your code of any errors and receive the Paysafe.js instance.

The function signature is as follows:

paysafe.fields.setup(apikey,options,callback);
                                

The options object contains three main sections: environmentfields, and styles, described below.

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

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

Live

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

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.

You can include either one or two date fields:

Option Fields
Card details with single date field
  • cardNumber
  • cvv
  • expiryDate

expiryDate uses the mm/yy format

Card details with multiple date fields
  • cardNumber
  • cvv
  • expiryYear
  • expiryMonth

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"
}
}
}, function (instance, error) {...});
</script>
</body>
</html>

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

Field property HTML result
title accessibilityLabel placeholder title 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 Number Credit card number input frame Enter 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:

accessibilityErrorMessage Event aria-describedby value (which will be read by the Screen Reader) input aria-descibedby attribute (the id of the error message element)
Invalid on load <empty> null
Invalid on valid <empty> null
Invalid on invalid <empty> (except invalid events depending on the current field (CVV, Expiry month) aria-describedby
Invalid on focus (when invalid) Invalid aria-describedby
Invalid on focus (when invalid) Invalid aria-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 valid) <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"
}
}
}, function (instance, error) {...});
</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.

Callback

Finally, the setup function must contain a callback function used to handle any errors during the initialization along with any special code to execute on successful initialization. The callback has the following signature:

function callback(instance, error) {
if (error) {
// error handling
} else {
// instance manipulation
}
}

An example showing how this function can be used is shown below:

<html>
...
<body>
<script>
paysafe.fields.setup("my Base64 encoded single-use-token API key", function (instance, error) {
if (error) {
...
} else {
...
}
});
</script>
</body>
</html>

The callback function parameters are described below:

Parameter Required Type Description
instance false object Paysafe.js instance passed when setup succeeds, providing access via the API to events in the sensitive payment fields.
error false object Error returned if setup fails.
{return} false any  
{context}   object The options object passed to the setup function.

Callback Error Object

The following table describes the contents of the error object:

Parameter Required Type Description
code true string Error code
displayMessage true string Error message for display to customers.
detailedMessage true string Detailed description of the error (this information should not be displayed to customers).
correlationId true string Unique 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.

Parameter Required Type Description
apiKey true string The Base64-encoded version of the single-use token API key used to authenticate with the Customer Vault REST API.
options false object Encapsulates the environment, fields, and style.
callback false function Used to handle any errors during initialization, and to provide any special code to execute on successful initialization.
{return} false any  
options
environment false string

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

  • LIVE – used for Production
  • TEST – used for the Test or sandbox environment
fields false object Configuration for the specified fields.
style false object Javascript representation of the CSS properties to apply to the fields.
initializationTimeout false number The maximum time (in milliseconds; default is 5000) that the SDK will wait for the iframes to get ready before returning an error.
fields
fieldName false string

Field name to configure:

  • cardNumber
  • cvv
  • expiryDate
  • expiryYear
  • expiryMonth
selector true string CSS selector that uniquely identifies the empty container in which to insert the field iframe.
placeholder false string Placeholder for the iframe input element.
accessibilityLabel false string An 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)
accessibilityErrorMessage false string An error message that will be read from the Screen Readers when the field is invalid (if the client uses any). Empty by default.
iframeTitle false string The title that will be assigned to the iframe. The default value is 'secured'.
separator false string

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").

optional false boolean

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.

mask false boolean

Available for the CVV field only. Defaults to "false". If the value is "true" the CVV value will be masked.

style
cssSelectorName false object 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
cssStyleName false string

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

Code

Display Message

Detailed Message

Description

9004 There was an error (9004), please contact our support. Invalid callback parameter.  
9012 There was an error (9012), please contact our support. Invalid number of arguments. The supplied number of arguments is neither 2 nor 3.

Callback Errors

Code

Display Message

Detailed Message

Description

9013 There was an error (9013), please contact our support. Invalid apiKey parameter. The supplied apiKey parameter is not a string.
9014 There 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.
9015 There was an error (9015), please contact our support. Invalid options argument. The supplied options parameter is not an object.
9016 There was an error (9016), please contact our support. Invalid style options. The supplied style options are not an object or an array.
9017 There was an error (9017), please contact our support. Environment options is not a string or an object. The supplied environment is not a string or an object.
9018 There was an error (9018), please contact our support. Environment doesn't match any of the predefined values (possible: TEST, LIVE; actual: ${environment}).  
9019 There was an error (9019), please contact our support. Environment url should be non-empty string. The environmentUrl is empty or not a string.
9021 There was an error (9021), please contact our support. CSS selector value for ${styleName} is not an object. The selector value is not an object or array.
9022 There was an error (9022), please contact our support. The 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.
9023 There was an error (9023), please contact our support. No container element was found using ${fieldName} selector.  
9024 There was an error (9024), please contact our support. More than one container element was found using ${fieldName} selector.  
9025 There was an error (9025), please contact our support. The same container was found for both ${firstField} and ${secondField}.  
9026 There was an error (9026), please contact our support. Wrong expiry date field configuration! Either expiryDate or both expiryMonth and expiryYear should be set.  
9028 There was an error (9028), please contact our support. Failed 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.
9029 There was an error (9029), please contact our support. ${fieldName} placeholder should be string.  
9030 There was an error (9030), please contact our support. Card number separator should be string.  
9031 There was an error (9031), please contact our support. Invalid card number separator. The value specified for the card number separator is not null, undefined, "" (empty string), " " (white space) or "-" (dash).
9032 There was an error (9032), please contact our support. ${fieldName} accessibilityLabel should be string. Used when accessibilityLabel is not a valid string.
9033 There was an error (9033), please contact our support. Selector 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 cardNumbercvv and expiryDate, but there are selectors only for cardNumber and cvv.
9072 There was an error (9072), please contact our support. ${fieldName} accessibilityErrorMessage should be string. Used when accessibilityErrorMessage is not a valid string.
9078 There was an error (9078), please contact our support. Invalid optional ${fieldName} parameter.  
9079 There was an error (9079), please contact our support. ${fieldName} cannot have optional parameter.  
9082 There was an error (9082), please contact our support. initializationTimeout should be number greater than zero.  
9097 There was an error (9097), please contact our support. ${fieldName} iframeTitle should be string. Used when iframeTitle is not a valid string.