Setup Function
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:
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.
- The Base64-encoded version of the single-use token API key is used to authenticate with the Payment Hub REST API.
- 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 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.
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:
| Option | Field |
|---|---|
Card details with a single date field |
expiryDate uses the mm/yy format |
| Card details with multiple date fields |
|
| ApplePay Integration |
|
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 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-describedby attribute (the id of the error message) |
|---|---|---|---|
| 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 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:
| 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 which is used to authenticate with the Payment Hub REST API. |
| options | true | object | Encapsulates the environment, fields, and style. |
| {return} | false | Promise | Promise that will be resolved to the hosted fields instance object |
| options | |||
| currencyCode | true | string | 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. |
| 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. |
| threshold | false | number | The threshold value is specific to transaction salvage flow. Specifies the maximum decline rate of a card bin. |
| accounts | false | object | 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. |
| supportedCountries | false | two-letter ISO 3166 country code array | Limits payments to cards from specific countries. See Integrate with ApplePay for more information. |
| accounts | |||
| default | true (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 |
| applePay | false | number | 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 | |||
| fieldName | false | string | The 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 which 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. |
| label | true (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. |
| type | false | string | Available for the applePay field only. The Apple Pay button type.Choose from:
|
| color | false | string | Available for the applePay field only. The Apple Pay button color. Choose from:
|
| 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 |
|---|---|---|---|
| 9012 | There was an error (9012), please contact our support. | Invalid number of arguments. | The supplied number of arguments is different than 2. |
| 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. |
| 9055 | There was an error (9055), please contact our support | Invalid currency parameter. | The currencyCode is not a valid ISO currency |
| 9061 | There was an error (9061), please contact our support | Invalid account ID for ${paymentMethod}. | The accounts.{account} is not a valid account id |
| 9099 | There was an error (9099), please contact our support | Invalid threshold parameter. | The threshold provided is not a valid number between 0 and 100 |
| ApplePay Specific Errors | |||