Search Overlay

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

  1. Include the Paysafe Checkout SDK in your HTML payment form.

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

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

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

<script src=""></script>


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.

  • 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

<script src=""></script>


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

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



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


resultCallback function example

<script src=""></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
// 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 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);




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.

closeCallback function example

<script src=""></script>


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

function(stage, expired) {
if (stage) {
// Depeding upon the stage take different actions
switch (stage)

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

}, 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

<script src=""></script>


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

function(amount, paymentMethod, instance) {
if (amount>1000)
instance.decline("Amount is lower than the minimum accepted value");



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





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.





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


Optional String

Unique customer identifier used at your end.



Mandatory string

First name of the customer.



Mandatory string

Last name of the customer.



Mandatory string

Email address of the customer.


Optional Number

Phone number of the customer

dateOfBirth Conditional  object

Date of birth of the customer.

dateofbirth object


length=4 min=1900

Conditional  number

Customer's year of birth.


length=2 max=12

Conditional  number Customer's month of birth.


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


  1. Values are in minor units, e.g. 1099 USD equates to $10.99 in Checkout.
  2. The field must be an array of numbers.
  3. You can pass a maximum of 3 values eg: [1000, 5000, 67000].
  4. Values can be set to a minimum of 1 and a maximum of 9999.
  5. You cannot pass decimal amounts so values should be multiples of 100.
  6. 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.


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.



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



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



Optional string A merchant descriptor.



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