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: environment, fields, 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 as 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 CVV field is optional.

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
<html>
	...
	<body>
		<div id="cardNumber"></div>
		<div id="cvv"></div>
		<div id="expiryDate"></div>
		<script>
			paysafe.fields.setup("my Base64 encoded single-use-token API key", {
				fields: {
					cardNumber: {
						selector: "#cardNumber",
						placeholder: "Card number"
					},
					cvv: {
						selector: "#cvv",
						placeholder: "Cvv",
						optional: false
					},
					expiryDate: {
						selector: "#expiryDate",
						placeholder: "Expiry date"
					}
				}
			}, function (instance, error) {...});
		</script>
	</body>
</html>

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.
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 the CVV field only. Defaults to "false". If the value is "true", the CVV will not be required for making a tokenization, but will be validated if it is not empty.

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. environment.url 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).
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 cardNumber, cvv and expiryDate, but there are selectors only for cardNumber and cvv.
9078 There was an error (9078), please contact our support. Invalid optional cvv 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.
Did you find this page useful?