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. 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 |
expiryDate uses the mm/yy format |
| Card details with multiple date fields |
|
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 valid) | <empty> | null |
| 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:
|
| 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:
|
| 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:
List of classes:
|
| cssSelectorName | |||
| cssStyleName | false | string | Name of the CSS style that should be applied and the corresponding value. Supported CSS style names:
|
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 cardNumber, cvv 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. |