Setup Function

The setup function creates and initializes the Paysafe Checkout in an overlay. It has the following parameters:

The Public API key is provided in the Business Portal. Note that this key can only be used to generate payment handle tokens for use with payments, 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 contains the environment to use (Test or Live), the payment amount, currency, and several parameters to show additional features in the payment form.
A resultCallback function receives the Paysafe checkout instance, handle a successful payment handle (by sending the payment handle to your merchant server), or respond to any errors caused by a failed payment handle creation.
An optional closeCallback function you handles the customer closing the payment overlay.
An optional riskCallback function to receive the amount and payment method which the Customer has selected and run your risk checks before the payment handle is created. Depending on the riskCallback response, Payment handle will be created and returned in resultCallback (Applicable to only Cards, PaySafe Cash, VIPP, Sightline, and Apple Pay).

The function signature is as follows:

paysafe.checkout.setup (apiKey, options, resultCallback, closeCallback, riskCallback)

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	This is your Public API key, available in the Business Portal.
options	true	object	This is the merchant's configuration for rendering the Checkout.
resultCallback	true	function	Callback function invoked with the result or error from the payment, when the payment handle needs to be passed to the merchant. Returns an instance for flow control.
closeCallback	false	function	This notifies the merchant script when the Checkout gets closed. Invoked when a customer closes the Checkout without making a payment.
riskCallback	false	function	Callback function invoked when the merchant wants to run its own risk rule using the amount and payment method. Depending on the callback response, Payment handle will be created and returned in resultCallback (Applicable only to Cards, PaySafe Cash, VIPP and Sightline).
{return}	false	any
options
amount length = 1-9	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. Min = 1 Max = 999999999 When using 3DS 2 (i.e. useThreeDSecureVersion2= true), amount with value: "0" can be passed.
amountoptions	No	number array	This parameter is used to populate the amount grid options in checkout, for the user to choose on click rather than editing the populated amount. Field will be utilized only if "canEditAmount" parameter in the options is set to "true". Validations: Field Should be a number array. Each number option should satisfy a condition of minimum 1 and maximum 9999 Merchant cannot pass the decimal amount in the Amount Grid option Duplicate values are not allowed. Maximum option merchant can pass is 3. eg: [1000, 5000, 67000]
currency	true	string	This is the payment currency of the merchant account, for example, USD for US dollars.
merchantRefNum	true	string	A unique identifier provided by the merchant for every transaction from Checkout.
environment	false	string	Environment used for making the API calls and loading the Checkout. Possible values are: LIVE – used for Production TEST – used for the Merchant test or sandbox environment Default is Live.
locale	false	string	Language locale for the checkout: English: en_US French: fr_CA Spanish: es_MX Portuguese: pt_BR If omitted, defaults to en_US.
billingAddress	false	object	This is the billing address of the customer that will be displayed to the customer at checkout. The merchant should include this object if this is a first-time customer with no customer profile. If the customer entity has been created with the Payments API, then address information from the singleUseCustomerToken will be used and the merchant does not have to include the billingAddress object. Note: The address information from this object will be displayed in place of the address information from the singleUseCustomerToken, if both are included. Billing address is required for Interchecks.
singleUseCustomerToken	false	string	This is the singleUseCustomerToken that the merchant generated using the Create a Single-Use Customer Token request. Any saved addresses and/or payment details would be displayed in the Checkout.
canEditAmount	false	boolean	If true, the customer can edit the amount in the Checkout before clicking Pay. If false, the amount is not editable.
customer	false	object	If a customer is a first-time user and the customer profile does not exist in Paysafe, then the merchant can choose to pass the profile (if the profile exists with him) in the call to create a payment handle.
displayPaymentMethods	false	array	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. This is case-sensitive. Accepted values: "applePay" "card" "pay_by_bank" "skrill" "neteller" "paysafecard" "paysafecash" "sightline" "vippreferred" "paypal" "venmo" "ach" "eft" If this parameter is not included, then all payment methods available for the consumer will be displayed in the Checkout.
paymentMethodDetails	conditional	object	These are additional parameters required for Apple Pay Card Pay by Bank Skrill paysafecard Paysafecash Play+ (Sightline) VIP Preferred PayPal Venmo ACH EFT payment types.
payout	false	boolean	If true, Withdrawal Checkout screen will be launched. If false, Payment Checkout will be launched. Defaults to false.
payoutConfig	conditional	object	Required for withdrawal checkout only. This configuration is used to specify withdrawal limitations.
merchantDescriptor	false	object	This is a merchant descriptor.
billingAddress
nickName length<=50	false	string	An identifier to identify the type of address, for example, Work or Home.
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.
city	false	string	City in which the address is located.
zip	true	string	Zip or postal code for the address.
country	true	string	Country 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.
paymentMethodDetails
card	conditional	object	Required if there are multiple card accounts for the same currency. These are additional parameters for card.
paysafecard	conditional	object	These are additional parameters for Paysafecard. Required for Paysafecard payment/withdrawal.
paysafecash	conditional	object	These are additional parameters for Paysafecash. Required for Paysafecash payment/withdrawal.
skrill	conditional	object	These are additional parameters for Skrill. Required for Skrill withdrawal only.
sightline	conditional	object	These are additional parameters for Play+ (Sightline).
vippreferred	conditional	object	These are additional parameters for VIP Preferred.
paypal	conditional	object	These are additional parameters for PayPal. Required for Paypal withdrawal only.
applePay	true	object	Required, if the merchant accepts Apple Pay.
neteller	conditional	object	These are additional parameters for NETELLER.
payByBank	conditional	object	These are additional parameters for Pay by Bank.
venmo	conditional	object	These are additional parameters for Venmo.
ach	conditional	object	These are additional parameters for ACH.
eft	conditional	object	These are additional parameters for EFT.
merchantDescriptor
dynamicDescriptor length<=20	true	string	This is a merchant descriptor.
phone length<=13	true	string	This is the merchant’s phone number, which will be appended to the merchant descriptor.
customer
firstName length<=80	true	string	The first name of the customer.
lastName length<=80	true	string	The last name of the customer.
email length<=255	true	string	The email address of the customer.
dateOfBirth	true	object	The date of birth of the customer.
dateofbirth
year length=4 min=1900	true	number	This is the year of birth.
month length=2 max=12	true	number	This is the month of birth.
day length=2 max=31	true	number	This is the day of birth.
paypal
consumerId length<=50	true	string	The source of funds for the payment, the email address of the consumer or payer.
accountID length<=10	Conditional	string	If you are a merchant, then this field is required only if you have more than one account configured for the same payment method and currency. If you are a partner using a shared API key, then this field is mandatory.
recipientDescription length<=127	false	string	A label that overrides the business name in the merchant's PayPal account on the PayPal checkout pages.
language length=2	false	string	The 2-character preferred language code for the consumer (For Example, AU, AT, BE, BR, CA, CH, CN, DE, ES, GB, FR, IT, NL, PL, PT, RU, or US.) or A five-character code is also valid for languages in these countries (For Example: da_DK, he_IL, id_ID, ja_JP, no_NO, pt_BR, ru_RU, sv_SE, th_TH, zh_CN, zh_HK, and zh_TW).
shippingPreference	false	enum	The shipping preference. The possible values are: NO_SHIPPING - Redacts the shipping address from the PayPal pages. Recommended for digital goods. GET_FROM_FILE - Uses the customer-selected shipping address on PayPal pages. SET_PROVIDED_ADDRESS. If available, uses the merchant-provided shipping address, which the customer cannot change on the PayPal pages. If the merchant does not provide an address, the customer can enter the address on PayPal pages.
consumerMessage	false	string	Note to be displayed on the PayPal page.
orderDescription	false	string	Order description to display on PayPal page. If merchant does not set this field it defaults to 'Payment for order'.
card
accountID length<=10	Conditional	string	If you are a merchant, then this field is required only if you have more than one account configured for the same payment method and currency. If you are a partner using a shared API key, then this field is mandatory.
paysafecard
consumerId length<=50	true	string	This is a consumer ID of the customer that the merchant has stored in his system for Paysafecard payments.
accountID length<=10	Conditional	string	If you are a merchant, then this field is required only if you have more than one account configured for the same payment method and currency. If you are a partner using a shared API key, then this field is mandatory.
paysafecash
consumerId length<=50	true	string	This is a consumer ID of the customer that the merchant has stored in his system for Paysafecash payments.
accountID length<=10	Conditional	string	If you are a merchant, then this field is required only if you have more than one account configured for the same payment method and currency. If you are a partner using a shared API key, then this field is mandatory.
sightline
consumerId length<=50	true	string	This is a consumer ID that the merchant has stored for Play+ (Sightline) payments. This will be used by Play+ for customer enrollment.
SSN length=9	false	string	This is the customer's Social Security Number. If provided, then the last 4 SSN field will be prefilled and locked in enrollment as well as during Payment flow. If not provided, Customer has to enter their full SSN in the enrollment and the last 4 SSN in the Payment flow.
last4ssn length=4	false	string	This is the customer’s last 4 digits of Social Security Number. If the customer is already enrolled for Sightline, then instead of sending the full ‘SSN’ field, you can send the last 4 digits of SSN which will get prefilled during Payment flow. If not provided, then the system will check if ‘SSN’ field is present to prefill the last 4 digits. If both these fields are not provided, then the customer has to enter the last 4 digits of SSN to complete the payment.
accountID length<=10	Conditional	string	If you are a merchant, then this field is required only if you have more than one account configured for the same payment method and currency. If you are a partner using a shared API key, then this field is mandatory.
applepay
accountid	true (conditional)	string	Required, if there are multiple apple pay accounts with same currency.
label	false	string	Displayed on payment sheet.
type	false	string	("plain", "buy", "addMoney", "book", "checkout", "continue", "contribute", "donate", "instore", "order", "reload", "rent", "setup", "subscribe", "support", "tip", "topup") Default: pay "Click here to view Apple Guidelines" If no or wrong value is provided then Checkout will create button with default values.
color	false	string	(white, black, white-outline) Default: white-outline "Click here to view Apple Guidelines" If no or wrong value is provided then Checkout will create button with default values.
requestShippingAddress	false	bool	Default is false. If set to true, Apple Pay will require a shipping address.
requestBillingAddress	false	bool	Default is false. If set to true, Apple pay will require a billing address.
supportedCountries	false	two-letter ISO 3166 country code array	Limits payments to cards from specific countries.
skrill
consumerId length <= 50	true	string	This is the consumer's Skrill email ID to be paid. Required for withdrawal checkout. Merchant has to have this stored prior when consumer made a Skrill payment.
paymentId length <= 36	false	string	This is the ID returned in the response to a prior Payment that the customer made using Instant ACH. Required for withdrawal checkout.
emailSubject length <= 30	true	string	This is the Subject line to use in the customer email. Required for withdrawal checkout.
emailMessage length <= 50	true	string	This is the message to use in the customer email. Required for withdrawal checkout.
recipientDescription length <= 30	false	string	A description to be shown on the Skrill payment page in the logo area if there is no logo_url parameter. If no value is submitted and there is no logo, the merchant_skrill_email value is shown as the recipient of the payment.
language length <= 2	false	string	The 2-character preferred language code for the consumer (For example: EN, FR).
logoUrl	false	string	The URL of the logo which you would like to appear in the top right of the Skrill page. The logo must be accessible via HTTPS or it will not be shown. The logo will be resized to fit. To avoid scaling distortion, the minimum size should be as follows: If the logo width > height - at least 107px wide If logo width > height - at least 65px high Avoid large images (much greater than 256 by 256px) to minimize the page loading time.
detail1Description	false	string	You can show additional details about the product in the More information section in the header of Quick Checkout.
detail1Text	false	string	The detail1Text is shown next to the detail1Description in the More Information section in the header of the payment form with the other payment details. The detail1Description combined with the detail1Text is shown in the more information field of the merchant account history CSV file.
accountID length <= 10	conditional	string	If you are a merchant, then this field is required only if you have more than one account configured for the same payment method and currency. If you are a partner using a shared API key, then this field is mandatory.
vippreferred
consumerId length=9	true	string	This is the customer's Social Security Number.
accountId length<=10	conditional	string	If you are a merchant, then this field is required only if you have more than one account configured for the same payment method and currency. If you are a partner using a shared API key, then this field is mandatory.
eft
accountId length<=10	conditional	string	This field is recommended if you have one account configured for the same payment method and currency. The field is required if you have more than one account configured for the same payment method and currency. This field also is required if you are a partner using a shared API key.
ach
accountId length<=10	Conditional	string	This field is recommended if you have one account configured for the same payment method and currency. The field is required if you have more than one account configured for the same payment method and currency. This field also is required if you are a partner using a shared API key.
venmo
consumerId	true	string	This is the id of the Venmo consumer account
paybybank
consumerId	true	string	The consumer id of the Pay by Bank account

Was this page helpful?

On this Page

Setup Function and Objects

Search Overlay

Setup Function

Was this page helpful?

Thank you for your response!