Setup Function

The setup function creates and initializes the Paysafe Checkout in an overlay. It 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 only be used to generate single-use tokens for use with the Card Payments and Direct Debit APIs, and has no other API access rights, such as those required for taking payments. Consequently, this key can be exposed publicly in the user's browser.
An options object containing the environment to use (Test or Live), the payment amount, currency, and several parameters to personalize the payment form and customize its appearance.
A resultCallback function you provide to receive the Paysafe checkout instance, handle successful tokenization (by sending the token to your merchant server), or respond to any errors caused by a failed tokenization.
An optional closeCallback function you provide to handle the customer closing the payment overlay.

The function signature is as follows:

Javascript

paysafe.checkout.setup(apikey,options,resultsCallback,closeCallback);

Environment

The options object contains a string to select the environment to use for tokenization, either 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

Javascript

paysafe.checkout.setup("my Merchant test Base 64 encoded single-use-token API key", {
    environment: "TEST"
  },
  function(instance, error, result) {...});

Live

Javascript

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

If you omit the environment object, by passing an empty or null value for this parameter, the Live environment will be used.

Setup Function and Objects

Here is a full list of the setup function parameters, 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	true	object
resultCallback	true	function	Callback function invoked with the result or error from the payment. Returns an instance for flow control.
closeCallback	false	function	Callback function invoked when the modal overlay is closed.
{return}	false	any
options
amount	true	number	Payment amount in minor units to charge the customer's card. Use the correct minor units amount for the merchant account currency. For example, to process US $10.99, this value should be 1099. To process 1000 Japanese Yen, this value should be 1000. To process 10.139 Tunisian dinar, this value should be 10139.
currency	true	string	Three character code for the payment currency – for example, USD for US dollars.
companyName length <= 60 chars	true	string	Merchant name for display on the payment form.
holderName length <= 160 chars	false	string	Name of the card holder. This parameter is used to personalize the payment form and to associate the customer's name with the payment token.
environment	false	string/object	Environment to use for all tokenization and logging calls. Possible values are: LIVE – used for Production TEST – used for the Merchant test or sandbox environment
imageUrl length <= 2000 chars	false	string	URL for the logo to display on the payment form. Must be a publicly accessible URL using the HTTPS protocol. The logo is resized for display. Any browser supported format is permitted. Paysafe recommends a size of 56 x 56 pixels or a 1:1 aspect ratio (for vector images) for best results.
locale	false	string	Language locale for the checkout: en_US fr_CA If omitted, defaults to en_US.
accounts	false	object	Information regarding merchant processing accounts for 3D Secure. Add this object to support 3D Secure. If the customer's card supports 3D Secure, they may be shown an additional page from their card issuer within the overlay to authorize the payment. In the merchant Test environment, a simulator is used instead to simulate different 3DS responses. 3D Secure is supported only for Visa and Mastercard. 3D Secure 2 is supported only for Visa, Mastercard, and American Express.
billingAddress	false	object	Billing address for Card and Direct Debit payments. Additional details of the Customer Vault BillingAddress object are given in the Customer Vault documentation. For Direct Debit, the billing address is used to populate the Checkout form when the currency and country match. For example, if the country is USA and the currency is USD, the billing address fields in the Direct Debit Checkout form are automatically populated.
buttonColor	false	string	Hex color for the payment form buttons. For example, buttonColor: "#ff0000",
buttonLabel length <= 40 chars	false	string	The text displayed in the Pay button.
preferredPaymentMethod	false	string	The payment method selected when Paysafe Checkout is opened. Possible values are: Cards DirectDebit Interac This is case-insensitive.
displayPaymentMethods	false	string	This determines which available payment methods will be displayed to the consumer. The values in the array are shown in the Checkout in the order they are passed. Possible values are: Cards DirectDebit Interac Paysafecard This is case-insensitive. If this parameter is not included, then all payment methods available for the consumer will be displayed in the Checkout.
hideAmount	false	boolean	Specifies whether to show the Order Total label. If omitted, defaults to false.
threeDS	false	object	This optional object contains parameters used for 3D Secure 2.
accounts
CC	true	number	The ID of the merchant account to use for 3DS processing of the payment. For information about how to select the correct accountId, see Multiple Currencies.
billingAddress
country	true	string	Country in which the address is located.
zip	true	string	Zip or postal code for the address.
city	false	string	City in which the address is located.
state	false	string	This is the state/province/region in which the customer lives. This field is ignored with Direct Debit.
street	false	string	First line of the customer's street address.
street2	false	string	Second line of the customer's street address. This field is ignored with Direct Debit.
threeDS
useThreeDSecureVersion2	false	boolean	Specifies whether this instance of Paysafe Checkout should implement 3DS 2. If true and accountId is not configured for 3DS 2, an error will be returned in the callback. If omitted, defaults to false.
authenticationPurpose	false	enum	Indicates the type of Authentication request. This data element provides additional information to the ACS to determine the best approach for handing an authentication request. Possible values are: PAYMENT_TRANSACTION INSTALMENT_TRANSACTION If omitted, defaults to PAYMENT_TRANSACTION.
maxAuthorizationsForInstalmentPayment	conditional	number	Indicates the maximum number of authorizations permitted for installment payments. Min = 1 Max = 999 Required when authenticationPurpose = INSTALMENT_TRANSACTION.
billingCycle	conditional	object	Billing cycle information for recurring payments. Required when authenticationPurpose = INSTALMENT_TRANSACTION.
billingCycle.endDate	true	string	This is the date after which no further authorizations will be performed. The ISO 8601 date format is expected, i.e., YYYY-MM-DD.
billingCycle.frequency	true	number	This is the minimum number of days between authorizations. Min = 1 Max = 999

resultCallback

The result callback is invoked when a token is issued or a tokenization error occurs.

The signature is as follows:

Parameter	Required	Type	Description
instance	true	object	Paysafe Checkout instance.
error	false	object	Object containing information for the error. This field is present if tokenization fails. The contents of this object are described below.
result	false	object	Result containing payment token. The contents of this object are described below.
{return}	false	undefined
instance
isOpen	true	function	Checks if the overlay is still open.
close	true	function	Closes the overlay without displaying result from payment.
showSuccessScreen	true	function	Changes checkout layout to success screen.
showFailureScreen	true	function	Changes checkout layout to failure screen.
error
code	true	string	Short error code identifying the error type.
displayMessage	true	string	Provides an error message that can be displayed to users.
detailedMessage	true	string	Provides a detailed error message that can be logged.
correlationId	true	string	Unique ID that can be provided to the Paysafe Support team as a reference for investigation.
result
token	true	string	Payment token representing the sensitive card and bank account details in case of successful tokenization. You will need to send this token securely to your server to make payment using the Card Payments, Direct Debit, or Alternate Payments API.
paymentMethod	true	string	The payment method used by the customer: Cards DirectDebit Interac

An example is shown below:

Javascript

function(instance, error, result) {        
if (result.token) {

	// Successfully tokenized card, use result.token to process a payment
             
	console.log(result.token);

	// add AJAX code to send token to your merchant server

	instance.showSuccessScreen("Your goods are now purchased. Expect them to be delivered in next 5 business days.");         
} else {

	// tokenization failed

	instance.showFailureScreen("The payment was declined. Please, try again with the same or another payment method.");          
}

}

closeCallback

Invoked when the checkout overlay is closed by the customer. This function has the following signature:

Parameter	Required	Type	Description
stage	true	string	Stage during which the checkout overlay is closed. Possible values are: BeforePayment DuringPayment AfterPayment
{return}	false	any

Parameter

Required

Type

Description

stage

true

string

Stage during which the checkout overlay is closed. Possible values are:

BeforePayment
DuringPayment
AfterPayment

{return}

false

any

Example usage:

Javascript

function(stage) {
if (stage === "BeforePayment") {
	// No payment have been made
} else if (stage === "DuringPayment") {
	// Token have been issued, but the checkout overlay was closed from the user before instance flow control method was invoked
} else if (stage === "AfterPayment") {
	// Closed either via instance.close method or by the user from the success screen
}

Setup Errors

Code	Display Message	Detailed Message	Description
9004	There was an error (9004), please contact our support.	Callback should be function.
9012	There was an error (9012), please contact our support.	Invalid number of arguments.	Used when the supplied number of arguments is neither 3 nor 4.
9062	There was an error (9062), please contact our support.	Paysafe Checkout already opened.	Setup function has been invoked and Paysafe Checkout is already opened or is loading at the moment.

Errors Passed to resultCallback

Code	Display Message	Detailed Message	Description
9013	There was an error (9013), please contact our support.	Invalid apiKey parameter.	Used when the supplied apiKey parameter is not a string, is in invalid format, or is not configured for Paysafe Checkout.
9014	There was an error (9014), please contact our support.	Unhandled error occurred.	Used when an error unhandled by the Paysafe Checkout SDK is thrown.
9015	There was an error (9015), please contact our support.	Invalid options argument.	Used when the supplied options parameter is not an object.
9017	There was an error (9017), please contact our support.	Environment options is not a string or an object.	Used when 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}).
9043	There was an error (9043), please contact our support.	HolderName should be valid.	Used when the supplied holderName parameter is not a string.
9044	There was an error (9044), please contact our support.	billingAddress country should be valid country code.	Used when the supplied billingAddress.country parameter is not a string.
9045	There was an error (9045), please contact our support.	billingAddress zip should be valid zip code.	Used when the supplied billingAddress.zip parameter is not a string.
9046	There was an error (9046), please contact our support.	billingAddress state should be valid state.	Used when the supplied billingAddress.state parameter is not a string.
9047	There was an error (9047), please contact our support.	billingAddress city should be valid city.	Used when the supplied billingAddress.city parameter is not a string.
9048	There was an error (9048), please contact our support.	billingAddress street should be valid street.	Used when the supplied billingAddress.street parameter is not a string.
9049	There was an error (9049), please contact our support.	billingAddress street2 should be valid street.	Used when the supplied billingAddress.street2 parameter is not a string.
9052	There was an error (9052), please contact our support.	billingAddress should be object.	Used when the supplied billingAddress parameter is not an object.
9053	There was an error (9053), please contact our support.	Invalid companyName parameter.	Used when the supplied companyName parameter is not a string.
9054	There was an error (9054), please contact our support.	Invalid amount parameter.	Used when an amount is not supplied, is not a number, is not positive, or is longer than 9 digits.
9055	There was an error (9055), please contact our support.	Invalid currency parameter.	Used when the supplied currency parameter is not a string.
9057	There was an error (9057), please contact our support.	Invalid locale parameter.	Used when the supplied locale parameter does not match the supported values.
9059	There was an error (9059), please contact our support.	Accounts should be object.	Used when the supplied accounts parameter is not an object.
9060	There was an error (9060), please contact our support.	Close callback should be function.	Used when the provided closeCallback is not a function.
9061	There was an error (9061), please contact our support.	Invalid account ID for ${paymentMethod}.	Used when the supplied accountId for a specific payment method is not a number or is not positive.
9063	There was an error (9063), please contact our support.	Invalid buttonColor parameter.	Used when the supplied color is not a valid hex color, e.g., '#ee33ee'.
9064	There was an error (9064), please contact our support.	Failed to initialize Paysafe Checkout iframe.	Used when the checkout iframe has failed to initialize within 5 seconds – the reason could be that the server that serves the HTML for the iframe is not available at the moment.
9065	There was an error (9065), please contact our support.	Invalid payment method: ${paymentMethod}.	Used when the supplied preferredPaymentMethod is not one of the following: Cards DirectDebit Interac
9073	There was an error (9073), please contact our support.	Account not configured correctly.	Used when account ID or account currency was incorrectly configured.
9094	There was an error (9094), please contact our support.	Invalid displayPaymentMethods parameter.	Used for the following reasons: displayPaymentMethods parameter is not valid array of strings. The array is empty or more than 4 payment methods are passed. One or more of the passed elements in the array are not valid payment methods: Cards DirectDebit Interac Paysafecard
9095	There was an error (9095), please contact our support.	Duplicate entries in displayPaymentMethods parameter are not allowed.	Used when duplicate payment methods are passed in the displayPaymentMethods parameter.
9096	There was an error (9096), please contact our support.	Your account is not configured for the passed displayPaymentMethods. Supported payment methods: ${supportedPaymentMethods}.	Used when one or more of the provided payment methods in the displayPaymentMethods parameter do not match the payment methods configured for the merchant.
9097	There was an error (9097), please contact our support.	ThreeDS authenticationPurpose doesn't match any of the predefined values (possible: INSTALMENT_TRANSACTION, PAYMENT_TRANSACTION; actual: ${authenticationPurpose}.	Used when the supplied authenticationPurpose is string and doesn't match the supported values.
9098	There was an error (9098), please contact our support.	ThreeDS maxAuthorizationsForInstalmentPayment is required when authenticationPurpose is INSTALMENT_TRANSACTION.	Used when maxAuthorizationsForInstalmentPayment is not provided and authenticationPurpose is INSTALMENT_TRANSACTION.
9099	There was an error (9099), please contact our support.	ThreeDS maxAuthorizationsForInstalmentPayment has to be a number between 1 and 999.	Used when value for maxAuthorizationsForInstalmentPayment is invalid.
9100	There was an error (9100), please contact our support.	ThreeDS billingCycle is required when authenticationPurpose is INSTALMENT_TRANSACTION.	Used when billingCycle is not provided and authenticationPurpose is INSTALMENT_TRANSACTION.
9101	There was an error (9101), please contact our support.	ThreeDS billingCycle.endDate should be a valid ISO 8601 date format YYYY-MM-DD.	Used when the supplied billingCycle.endDate is invalid.
9102	There was an error (9102), please contact our support.	ThreeDS billingCycle.frequency has to be a number between 1 and 9999.	Used when the supplied billingCycle.frequency is invalid.
9106	There was an error (9106), please contact our support.	Invalid buttonLabel parameter.	Used when the value provided for the buttonLabel parameter exceeds 40 characters.
9109	There was an error (9109), please contact our support.	Invalid hideAmount value.	Used when the value provided for hideAmount is invalid.
9110	There was an error (9110), please contact our support.	Unable to initiate ThreeDs SDK.	Used when the ThreeDs SDK has failed to load or the ThreeDs SDK start callback is invoked with unhandled error.
9111	There was an error (9111), please contact our support.	Invalid merchant configuration setup.	Used when the merchant configuration setup is invalid.
9112	There was an error (9112), please contact our support.	Invalid threeDS useThreeDSecureVersion2 parameter.	Used when the supplied useThreeDSecureVersion2 parameter is not a boolean.
9113	There was an error (9113), please contact our support.	The accountId provided is not enabled for 3DS version 2.	Used when the supplied accountId (accounts.CC) is not enabled for 3DS version 2.
9114	There was an error (9114), please contact our support.	Unable to initiate ThreeDs SDK challenge.	Used when the when ThreeDs SDK challenge callback is invoked with error.
9125	There was an error (9125), please contact our support.	Unsupported card brand used: [...]. Supported card brands: [...].	Used when the customer is using card brand not supported by the merchant configuration.

PREV NEXT

Updated Cookies Notice – you'll see this message only once.

Create a Test
Account

Setup Function

Environment

Test

Live

Setup Function and Objects

resultCallback

closeCallback

Setup Errors

Errors Passed to resultCallback

Updated Cookies Notice – you'll see this message only once.

Create a TestAccount

Setup Function

Environment

Test

Live

Setup Function and Objects

resultCallback

closeCallback

Setup Errors

Errors Passed to resultCallback

Create a Test
Account