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. Returns an instance for flow control.
closeCallback false function This notifies the merchant script when the Checkout gets closed.
{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.

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:

  • en_US
  • fr_CA

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.
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 In case the customer is a first-time user and has no customer profile, the merchant can choose to pass an existing customer profile 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-insensitive.

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 Paysafecash, Paysafecard, Skrill, Instant ACH, Paypal, Play+ (Sightline) 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.
instantach conditional object These are additional parameters for Instant ACH. Required for Instant ACH 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.
paypal

consumerId

length<=50

true string The source of funds for the payment, the email address of the consumer or payer.

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'.
recipientType true string Type of payout recipient. The only supported value is 'PAYPAL_ID'.
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.

payoutConfig

maximumAmount

length=1-9

true number This specifies the maximum amount that a user is allowed to withdraw from checkout in the current session.
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 that the merchant has stored 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 that the merchant has stored 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 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.
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

true 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 pay_to_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.
instantach

consumerId

length <= 50

true string

This is the consumer's email ID. Required for withdrawal checkout.

paymentId

length <= 36

true 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 Instant ACH payment page in the logo area if there is no logo_url parameter. If no value is submitted and there is no logo, the pay_to_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 Instant ACH 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.

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.
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.

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.
fieldErrors false array Details of any parameter value errors (optional). Currently only being supplied when a 9003 error is thrown.
fieldError
field true string Field name. Example: threeDS.userAccountDetails.userLogin.time.
message true string Error in the field.
result
token true string Payment token representing 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
  • PayPal
saveInstrument false boolean Flag representing if payment instrument should be saved.
setInstrumentAsDefault false boolean Flag representing if payment instrument should be set as default.

An example is shown below:

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
Did you find this page useful?