How Checkout Works

Paysafe's Checkout JS library enables a simple integration process allowing you to easily deploy Checkout to your website. With just a few lines of code, you can load the Checkout interface and start collecting payments. The library handles all of the complexities of payment processing, securely transmitting payment details to our server for transaction completion. In addition, you can easily customize the look and feel of Checkout to match your brand identity.

To set up a test account, email our Integration Support team - include the supported payment methods you'd like to add to your test account.

Integrating Checkout

How to use the SDK

Include the Paysafe Checkout SDK in your HTML payment form.
Call the Checkout setup function with your Public API key.
The callback uses AJAX to send the payment handle token (containing tokenized customer payment details) to your (merchant) website.
Write your own logic to send the token to your (merchant) server to make a payment or process a payout using the Paysafe Payments API.

Including the SDK

The SDK is located here:

https://hosted.paysafe.com/checkout/v2/paysafe.checkout.min.js

Include it in your HTML form by adding a <script> element in either the header or body.

<html>

    <head>       

        <script src="https://hosted.paysafe.com/checkout/v2/paysafe.checkout.min.js"></script>

    </head>

 

</html>

The Setup Function

The setup function creates an iframe overlay containing the secure payment/withdrawal form hosted on Paysafe’s servers. You will need to pass a callback function as part of your setup to manage paymentHandle success and failure. It has the following parameters:

The Base64-encoded version of the API key.
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 which receives the Paysafe Checkout instance and paymentHandle successful tokenization (by sending the token to your merchant server). It also responds to any errors caused by a failed tokenization.
An optional closeCallback function to handle the customer closing the payment overlay.
An optional riskCallback function to receive the amount and payment method selected by the customer, and run your risk checks before the paymentHandle is created. Depending on the riskCallback response, the paymentHandle will be created and returned in the resultCallback.

Parameter	Required	Type	Description
apiKey	Yes	string	Your Public API key, available in the Business Portal.
options	Yes	object	Your merchant configuration for rendering the Checkout.
resultCallback	Yes	function	Callback function invoked with the result or error from the payment, when the paymentHandle must be passed to your server. Returns an instance for flow control.
closeCallback	No	function	Callback function that notifies your script when the Checkout is closed - invoked when a customer closes the Checkout without making a payment.
riskCallback	No	function	Callback function invoked when you want to run your own risk rule using the amount and payment method. Depending on the callback response, the paymentHandle is created and returned in the resultCallback.

Setup function specification

Setup function example

<html>

    <head>       

        <script src="https://hosted.paysafe.com/checkout/v2/paysafe.checkout.min.js"></script>

    </head>

 

    <body>

    </body>

 

    <script>

        function checkout()

            {paysafe.checkout.setup( apikey, options, resultCallback, closeCallback, riskCallback);}

    </script>

</html>

The base64apikey

Use your public API Key.

Construct the Authorization header as follows:

Combine the Key Username and Key Password into a string separated by a colon, e.g. “Key Username:Key Password”.
Encode the resulting string literal using Base64.

Your API key will have the following format :

Key Username: MerchantXYZ
Key Password: B-tst1-0-51ed39e4-312d02345d3f123120881
base64apikey : TWVyY2hhbnRYWV

Callbacks

resultCallback

The resultCallback function is invoked when the payment handle is successfully created and is in the PAYABLE state or when there is an error in the Checkout. It also passes an instance of the Checkout object. Using the functions provided in the instance object, you can control the Checkout experience.

resultCallback contains the following elements:

Parameter	Type	Required	Description
instance	object	Yes	The Paysafe Payments Checkout instance.
error	object	No	Contains error information, present if payment handle creation fails.
result	object	Yes	Result that contains the payment token.

instance object

Parameter	Type	Description
isOpen	function	Checks if the overlay is still open.
close	function	Closes the overlay without displaying the payment result.
showSuccessScreen	function	Changes the Checkout layout to the success screen.
showFailureScreen	function	Changes the Checkout layout to the failure screen.

error object

Parameter	Type	Description
message	string	Provides an error that can be displayed to customers.
detailedMessage	string	Provides a detailed error message that can be logged.
correlationId	string	Unique ID that can be provided to the Paysafe Support team as a reference for investigation.

result object

Parameter	Type	Description
paymentHandleToken	string	The Payment Handle token to be included in the Payments API call.
paymentMethod	string	The payment method used by the customer.
customerOperation	string	The customer operation for the card. Possible values are: ADD EDIT DELETE
amount	number	The amount used to create the Payment Handle. Required because the customer might change the amount in the Checkout.
transactionType	string	The transaction type of the operation that was carried out: PAYMENT ORIGINAL_CREDIT STANDALONE_CREDIT

resultCallback function example

<html>

    <head>       

        <script src="https://hosted.paysafe.com/checkout/v2/paysafe.checkout.min.js"></script>

    </head>

 

    <body>

    </body>

 

    <script>

        function checkout()

            {   paysafe.checkout.setup( apikey, options,

 

 

                function(instance, error, result) {       

                        if (result && result.paymentHandleToken) {

                                                // Successfully Tokenized transaction, use result.paymentHandleToken to process a payment

                                console.log(result.paymentHandleToken);

                                                // 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 {

                                console.log(error);

                                                // Tokenization failed and Payment Handled moved to failed Status

                                if(instance) {

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

                                }

                    }

 

                }, closeCallback, riskCallback);

             

            }

     

    </script>

</html>

closeCallback

The closeCallback function notifies your merchant script when the Checkout is closed. closeCallback is invoked when:

The customer closes the Checkout.
You close the Checkout using the instance.close() method in the result callback after the payments call.

closeCallback contains the following elements:

Parameter	Type	Required	Description
stage	string	Yes	Stage during which the Checkout overlay is closed. Possible values are: PAYMENT_HANDLE_NOT_CREATED: Checkout did not initiate a session with Paysafe or PSP. PAYMENT_HANDLE_CREATED: Checkout initiated a session with Paysafe/PSP and obtained the details required to initiate a payment. PAYMENT_HANDLE_REDIRECT: Checkout successfully redirected the customer to the PSP hosted page and is waiting for the callback from the hosted page. This is applicable only for flows where the customer is redirected to a different page. Indicates the payment is in progress in the redirected page. PAYMENT_HANDLE_PAYABLE: The customer completed the payment, and either the customer closes the Checkout after seeing the success/failure screen (this can be initiated by your script in result callback using instance.showSuccessScreen() /instance.showFailureScreen() methods) or your merchant script closes the Checkout after the payments call from resultCallback by calling the instance.close() method.
expired	boolean	Yes	Indicates if the close event was triggered after the Checkout expired.

Parameter

Type

Required

Description

stage

string

Yes

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

PAYMENT_HANDLE_NOT_CREATED: Checkout did not initiate a session with Paysafe or PSP.
PAYMENT_HANDLE_CREATED: Checkout initiated a session with Paysafe/PSP and obtained the details required to initiate a payment.
PAYMENT_HANDLE_REDIRECT: Checkout successfully redirected the customer to the PSP hosted page and is waiting for the callback from the hosted page. This is applicable only for flows where the customer is redirected to a different page. Indicates the payment is in progress in the redirected page.
PAYMENT_HANDLE_PAYABLE: The customer completed the payment, and either the customer closes the Checkout after seeing the success/failure screen (this can be initiated by your script in result callback using instance.showSuccessScreen() /instance.showFailureScreen() methods) or your merchant script closes the Checkout after the payments call from resultCallback by calling the instance.close() method.

expired

boolean

Yes

Indicates if the close event was triggered after the Checkout expired.

closeCallback function example

<html>

    <head>       

        <script src="https://hosted.paysafe.com/checkout/v2/paysafe.checkout.min.js"></script>

    </head>

 

    <body>

    </body>

 

    <script>

        function checkout()

            {   paysafe.checkout.setup( apikey, options, resultCallback,

         

                 function(stage, expired) {       

                        if (stage) {

                                                    // Depeding upon the stage take different actions

                                        switch (stage)           

                                            case "PAYMENT_HANDLE_NOT_CREATED" :

                                            case "PAYMENT_HANDLE_CREATED" :

                                            case "PAYMENT_HANDLE_REDIRECT" :

                                            case "PAYMENT_HANDLE_PAYABLE" :              

                                            default:  

     

                                    }

                        else {

                                        console.log(expired)                    //Add action in case Checkout is expired  

       

                    }, riskCallback);

     }

    </script>

</html>

riskCallback

The riskCallback function notifies you with the amount and selected payment method when the customer clicks the Pay/ Withdraw button in Checkout. riskCallback is invoked when:

The customer clicks the Pay/ Withdraw button in Checkout.

riskCallback contains the following elements.

Parameter		Type	Required	Description
amount		String	Yes	The amount that the customer wants to pay.
paymentMethod		String	Yes	The payment method used by the customer.
instance		Object	Yes	The Paysafe Payments Checkout instance.
	decline	function		When invoked, Checkout considers callback risk-check as failed and renders the error message which you pass as a parameter - see riskCallback example, below.
	accept	function		When invoked, Checkout considers callback risk-check as passed and proceeds with payment handle creation. See riskCallback example, below.

riskCallback function example

<html>

    <head>       

        <script src="https://hosted.paysafe.com/checkout/v2/paysafe.checkout.min.js"></script>

    </head>

 

    <body>

    </body>

 

    <script>

        function checkout()

            {   paysafe.checkout.setup( apikey, options, resultCallback, closeCallback

         

                 function(amount, paymentMethod, instance) {       

                                if (amount>1000)

                                    instance.accept();

                                else

                                    instance.decline("Amount is lower than the minimum accepted value");

     

  

                    });

         }

    </script>

</html>

Options

Here is a full list of the setup function parameters, the JavaScript objects used by the setup function, and the parameters they contain.

Mandatory parameters

NOTE: These parameters are required in all cases.

Parameter	Required	Type	Description
amount	Mandatory	number length = 1-9	The payment amount is in minor units to charge the customer's card. Use the correct minor units amount for your merchant account currency. For example: to process US $10.99, the amount should be 1099. to process 1000 Japanese Yen, the amount should be 1000. to process 10.139 Tunisian dinar, the amount should be 10139. Min = 1 Max = 999999999
currency	Mandatory	string	The payment currency of your merchant account, for example, USD for US dollars.
customer	Mandatory	object	If a customer is a first-time user and the customer profile does not exist in Paysafe, then the you can choose to pass the profile in the call to create a payment handle. PagoEfectivo payment method: Mandatory if you are offering PagoEfectivo. SafetyPay payment method: Mandatory, if you are offering one of the following payment methods: SafetyPay Bank Transfer, SafetyPay Cash, Boleto Bancário, Pix, Khipu or MACH.
merchantRefNum	Mandatory	string	A unique identifier that you provide for every Checkout transaction.

customer object

merchantCustomerId	Optional	String	Unique customer identifier used at your end.
firstName length<=80	Mandatory	string	First name of the customer.
lastName length<=80	Mandatory	string	Last name of the customer.
email length<=255	Mandatory	string	Email address of the customer.
phone	Optional	Number	Phone number of the customer
dateOfBirth	Conditional	object	Date of birth of the customer.

dateofbirth object

year

length=4 min=1900

Conditional

number

Customer's year of birth.

month

length=2 max=12

Conditional

number

Customer's month of birth.

day

length=2 max=31

Conditional

number

Customer's day of birth.

Optional/ Conditional parameters

Parameter	Required	Type	Description
singleUseCustomerToken	Conditional	string	The singleUseCustomerToken that you generated using the Create a Single-Use Customer Token request. Any saved addresses and/or payment details would be displayed in the Checkout.
canEditAmount	Conditional	boolean	If true, the customer can edit the Checkout amount before clicking Pay. If false, the amount is not editable.
amountoptions	Optional	number array	Used to populate the amount options shown in Checkout, so that the customer can choose an amount by clicking a pre-set option instead of editing the populated amount. Only available if canEditAmount is set to "true". Validation: Values are in minor units, e.g. 1099 USD equates to $10.99 in Checkout. The field must be an array of numbers. You can pass a maximum of 3 values eg: [1000, 5000, 67000]. Values can be set to a minimum of 1 and a maximum of 9999. You cannot pass decimal amounts so values should be multiples of 100. Duplicate values are not allowed.
displayPaymentMethods	Optional	array	Determines which available payment methods are displayed to the customer. Checkout displays the array values in the order in which they are passed. Case-sensitive. Sample values (varies with currency): displayPaymentMethods:[ "applePay","card", "mazooma" ,"skrill","paysafecard", "neteller", "paysafecash","instantach","sightline","vippreferred","paypal"], If this parameter is not included, Checkout dispays all payment methods available to the customer.
paymentMethodDetails	conditional	object	Additional parameters required for specific payment methods - for details refer to the individual payment methods.
payout	optional	Boolean	If true, the Withdrawal Checkout screen is launched. If false, Payment Checkout is launched. Defaults to false.
payoutConfig	conditional	object	Required for Withdrawal Checkout only. This configuration is used to specify withdrawal limitations.
maximumAmount length=1-9	conditional	number	Specifies the maximum amount that a customer is allowed to withdraw from Checkout in the current session.
locale	Optional	string	Language locale for the checkout: en_US fr_CA If omitted, defaults to en_US.
environment	Optional	string	Environment used for making the API calls and loading Checkout. Possible values are: LIVE – used for Production. TEST – used for the Merchant test or sandbox environment The default is Live.
merchantDescriptor	Optional	object	A merchant descriptor.
billingAddress	Conditional	object	The billing address of the customer that is displayed to the customer at checkout. You should include this object for first-time customers with no customer profile. If the customer entity has been created with the Payments API, then address information from the singleUseCustomerToken is used and you do not have to include the billingAddress object. NOTE: The address information in the billingAddress object is displayed in place of the address information from the singleUseCustomerToken, if both are included. Required for Interchecks.

billingAddress object

nickName length<=50	Conditional	Optional	An identifier to identify the type of address, such as "Work" or "Home".
street	Conditional	string	First line of the customer's street address.
street2	Conditional	string	Second line of the customer's street address. This field is ignored with Direct Debit.
city	Conditional	string	City in which the address is located.
zip	Conditional	string	Zip or postal code for the address.
country	Conditional	string	Country in which the address is located.
state	Conditional	string	The state/ province/ region in which the customer lives. This field is ignored with Direct Debit.

merchantDescriptor object

dynamicDescriptor

length<=20

Optional

string

A merchant descriptor.

phone

length<=13

Optional

string

Your (merchant) phone number, which is appended to the merchant descriptor.

Was this page helpful?

On this Page

Integrating Checkout
The Setup Function
The base64apikey
Callbacks
Options

Search Overlay

How Checkout Works

How to use the SDK

Including the SDK

resultCallback

Mandatory parameters

customer object

dateofbirth object

billingAddress object

merchantDescriptor object

Was this page helpful?

Thank you for your response!