Tokenize

This tokenize function returns a Promise, which will resolve to a single-use payment handle representing the user's sensitive card data. This handle can be used by the Payments API to take payments. Single-use handles are valid for only 15 minutes and are not consumed by verification. See Payments with a Handle for more details.

The tokenize function has the following signature:

instance.tokenize(options)

     .then(result => {

        ...

     })

    .catch(error => {

        ...

    });

Async Await

try {

    const result = await instance.tokenize(options);

    ...

} catch(error) {

    ...

};

The function signature contains the following parameters:

Parameter	Required	Type	Description
options	true	object	Optional tokenization settings, that contain information about the 3D Secure (3DS) flow and additional customer data sent to Customer Vault.
{return}	false	promise	Resolves to the result of the tokenization
options
amount	true	number	The payment amount is 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.
transactionType	true	string	This specifies the transaction type for which the Payment Handle is created. Possible values are: PAYMENT - Payment Handle is created to continue the Payment. STANDALONE_CREDIT - Payment Handle is created to continue the standalone credit. ORIGINAL_CREDIT - Payment Handle is created to continue the original credit. VERIFICATION - Payment Handle is created to continue the verification request.
paymentType	true	string	This is the payment type associated with this Payment Handle. Possible values are: CARD APPLEPAY
merchantRefNum	true	string	A unique identifier is provided by the merchant for every transaction from Paysafe JS.
customerDetails	true	object	Additional customer data associated with the single-use handle from the Customer Vault.
merchantDescriptor	false	object	This is a merchant descriptor that is displayed on a customer’s card statement.
accountId	false	number	The id of the selected merchant account to use to process the payment. 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. If an account is provided on setup, this one will override it.
threeDS	false	object	An object representing the 3DS parameters. Include this object to enable 3DS.
openAs	false	string	Specify how any external authorization windows will be opened (3DS etc.) IFRAME NEW_TAB
applePay	false	object	Additional data for the Apple Pay payment method. Must be provided if paymentType = APPLEPAY
singleUseCustomerToken	false	string	This is the singleUseCustomerToken that the merchant generated using the Create a Single-Use Customer Token request.
paymentTokenFrom	false	string	This is single-use payment handle associated with the customer.
customerDetails
holderName	conditional	string	Name of the cardholder, maximum 160 characters. When using 3DS 2 (i.e. useThreeDSecureVersion2= true) and supported card brand for 3DS 2, the holder name is required and should be between 2 and 160 characters.
billingDetails	false	object	Card billing address - additional details for the billingDetails object can be found in the Payments API documentation.
profile	false	object	This is the profile of the customer - additional details for the profile object can be found in the Payments API documentation.
billingDetails
country	true	string	Country of billing address
zip	true	string	Zip code of the address
state	false	string	State/province/region of the address
city	false	string	City in which the address is located
street	false	string	The first line of the street address
street2	false	string	The second line of the street address
phone	false	string	The phone number of the customer
nickname	false	string	The nickname of the customer
profile
firstName	false	string	This is the customer’s first name.
lastName	false	string	This is the customer’s last name.
locale	false	string	This is the customer’s locale. Possible values: ca_en en_US fr_CA en_GB
dateOfBirth	false	string	This is the customer’s date of birth.
email	false	string	This is the customer’s email address.
phone	false	string	This is the customer’s phone number.
dateOfBirth
day	false	number	The day on which the customer is born.
year	false	number	The year in which the customer is born.
month	false	number	The month in which the customer is born.
merchantDescriptor
dynamicDescriptor	true	string length<=20	This is a merchant descriptor that is displayed on a customer’s card statement
phone	false	string length<=13	This is the merchant’s phone number, which is appended to the merchant descriptor on a customer’s card statement.
threeDS
merchantUrl	true	string	This is the fully qualified URL of the merchant's commercial or customer care websit
deviceChannel	true	string	This is the type of channel interface used to initiate the transaction. Possible values are: BROWSER SDK 3RI
useThreeDSecureVersion2	false	boolean	Specifies whether this instance of Paysafe.js 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	string	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.
electronicDelivery	false	object	This is the electronic delivery information.
profile	false	object	This is the customer profile.
messageCategory	false	string	This is the category of the message for a specific use case. Possible values are: PAYMENT NON_PAYMENT If omitted, defaults to PAYMENT.
requestorChallengePreference	false	string	This indicates whether a challenge is requested for this transaction. Possible values are: CHALLENGE_MANDATED CHALLENGE_REQUESTED NO_PREFERENCE
transactionIntent	conditional	string	This identifies the type of transaction being authenticated. This element is required only in certain markets, e.g., Brazil. Possible values are: GOODS_OR_SERVICE_PURCHASE CHECK_ACCEPTANCE ACCOUNT_FUNDING QUASI_CASH_TRANSACTION PREPAID_ACTIVATION
initialPurchaseTime	conditional	string	This is the date and time of the purchase. The ISO 8601 date format is expected i.e., YYYY-MM-DD-THH:MM:SSZ. Note: This element is required only if messageCategory=NON_PAYMENT and authenticationPurpose=INSTALMENT_TRANSACTION or RECURRING_TRANSACTION.
orderItemDetails	false	object	These are the details of a previously made purchase or preorder.
purchasedGiftCardDetails	false	object	These are the details of a previously made gift card purchase.
userAccountDetails	false	object	These are the user account details from the merchant website.
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.
frequency	true	number	This is the minimum number of days between authorizations. Min = 1 Max = 999
electronicDelivery
isElectronicDelivery	true	boolean	This indicates whether there is an electronic delivery for the product. The electronicDelivery object is optional; however, if the object is used, this element is required.
email	false	string length <= 240 chars	This is the email address to which the merchandise was delivered.
profile
email	false	string length <= 255 chars	This is the email address of the customer.
phone	false	string length <= 40 chars	This is the customer's primary phone.
cellphone	false	string length <= 40 chars	This is the customer's cell phone.
orderItemDetails
preOrderItemAvailabilityDate	false	string	For a pre-ordered purchase, this is the date that the merchandise is expected to be available. The ISO 8601 date format is expected, i.e., YYYY-MM-DD.
preOrderPurchaseIndicator	false	string	This indicates whether the cardholder is placing an order for available merchandise or merchandise with a future availability or release date. Possible values are: MERCHANDISE_AVAILABLE FUTURE_AVAILABILITY
reorderItemsIndicator	false	string	This indicates whether the cardholder is reordering merchandise. Possible values are: FIRST_TIME_ORDER REORDER
shippingIndicator	false	string	This is the shipping method for the transaction. Possible values are: SHIP_TO_BILLING_ADDRESS SHIP_TO_VERIFIED_ADDRESS SHIP_TO_DIFFERENT_ADDRESS SHIP_TO_STORE DIGITAL_GOODS TRAVEL_AND_EVENT_TICKETS OTHER
purchasedGiftCardDetails
amount	false	number	This is the amount of the gift card, in minor units. Max = 99999999999
count	false	number	This is the total count of individual prepaid or gift cards or codes purchased. Max = 99
currency	false	string	Three character code for the currency of the gift card – for example, USD for US dollars.
userAccountDetails
createdDate	false	string	This is the date when the cardholder opened the account with the 3DS Requestor. The ISO 8601 date format is expected, i.e., YYYY-MM-DD.
createdRange	false	string	This is the length of time between the cardholder opening the account with the 3DS Requestor and the API call of the current transaction. Possible values are: DURING_TRANSACTION NO_ACCOUNT LESS_THAN_THIRTY_DAYS THIRTY_TO_SIXTY_DAYS MORE_THAN_SIXTY_DAYS
changedDate	false	string	This is the date that the cardholder’s account with the 3DS Requestor was last changed. The ISO 8601 date format is expected, i.e., YYYY-MM-DD.
changedRange	false	string	This is the length of time between the most recent change to the cardholder’s account information and the API call of the current transaction. Possible values are: MORE_THAN_SIXTY_DAYS DURING_TRANSACTION LESS_THAN_THIRTY_DAYS THIRTY_TO_SIXTY_DAYS
passwordChangedDate	false	string	This is the date when the cardholder’s account was reset or the password was changed. The ISO 8601 date format is expected, i.e., YYYY-MM-DD.
passwordChangedRange	false	string	This is the length of time between the most recent password change or cardholder account reset and the API call of the current transaction. Possible values are: MORE_THAN_SIXTY_DAYS NO_CHANGE DURING_TRANSACTION LESS_THAN_THIRTY_DAYS THIRTY_TO_SIXTY_DAYS
totalPurchasesSixMonthCount	false	number	This is the total number of purchases from this cardholder account in the previous six months. Max = 9999
addCardAttemptsForLastDay	false	number	This is the number of Add Card attempts in the last 24 hours. Max = 999
transactionCountForPreviousDay	false	number	This is the number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours. Max = 999
transactionCountForPreviousYear	false	number	This is the number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year. Max = 999
suspiciousAccountActivity	false	boolean	This indicates whether the 3DS Requestor has experienced suspicious activity, including previous fraud, on the cardholder account.
shippingDetailsUsage	false	object	This is the shipping usage information.
paymentAccountDetails	false	object	These are the details of the current payment account of the cardholder.
userLogin	false	object	This is the cardholder login information.
priorThreeDSAuthentication	false	object	This is the previous authentication information used with current merchant, cardholder, and card.
travelDetails	false	object	These are the Amex-specific travel details.
shippingDetailsUsage
cardHolderNameMatch	false	boolean	This indicates whether the cardholder name on the account is identical to the shipping name used for this transaction.
initialUsageDate	false	string	This is the date when the shipping address for this transaction was first used with the 3DS Requestor. The ISO 8601 date format is expected, i.e., YYYY-MM-DD.
initialUsageRange	false	string	This is the length of time between the first use of this shipping address and the current transaction. Possible values are: MORE_THAN_SIXTY_DAYS CURRENT_TRANSACTION LESS_THAN_THIRTY_DAYS THIRTY_TO_SIXTY_DAYS
paymentAccountDetails
createdDate	false	string	This is the date that the cardholder opened the account with the 3DS Requestor. The ISO 8601 date format is expected, i.e., YYYY-MM-DD.
createdRange	false	string	This indicates the length of time that the payment account was enrolled in the cardholder’s account with the 3DS Requestor. Possible values are: MORE_THAN_SIXTY_DAYS NO_ACCOUNT DURING_TRANSACTION LESS_THAN_THIRTY_DAYS THIRTY_TO_SIXTY_DAYS
userLogin
data	false	string	This field is reserved for future iterations of 3D Secure 2. length <= 2048 chars
authenticationMethod	false	string	This is the mechanism used by the cardholder to authenticate to the 3DS Requestor. Possible values are: THIRD_PARTY_AUTHENTICATION NO_LOGIN INTERNAL_CREDENTIALS FEDERATED_ID ISSUER_CREDENTIALS FIDO_AUTHENTICATOR
time	false	string	This is the date and time of the cardholder authentication. The ISO 8601 date format is expected, i.e., YYYY-MM-DD-THH:MM:SSZ.
priorThreeDSAuthentication
data	false	string	This field is reserved for future iterations of 3D Secure 2. length <= 2048 chars
method	false	string	This is the mechanism used previously by the cardholder to authenticate to the 3DS Requestor. Possible values are: FRICTIONLESS_AUTHENTICATION ACS_CHALLENGE AVS_VERIFIED OTHER_ISSUER_METHOD
id	false	string	This is a previous authentication ID for the cardholder. length <= 36 chars
time	false	string	This is the date and time of the cardholder authentication. The ISO 8601 date format is expected, i.e., YYYY-MM-DD-THH:MM:SSZ.
travelDetails
isAirTravel	false	boolean	This indicates whether the transaction is an air travel related purchase, e.g., a ticket purchase. If omitted, defaults to false.
airlineCarrier	conditional	string	This is the selected airline carrier. Note: This element is required only if isAirTravel=true. length <= 256 chars
departureDate	conditional	string	This is the date of departure in the time zone of the departure location. The ISO 8601 date format is expected, i.e., YYYY-MM-DD. Note: This element is required only if isAirTravel=true.
destination	conditional	string	This is the airport code of the destination airport. Note: This element is required only if isAirTravel=true. length <= 5 chars
origin	conditional	string	This is the airport code of the originating airport. Note: This element is required only if isAirTravel=true. length <= 5 chars
passengerFirstName	conditional	string	This is the first name of the cardholder from the billing details. Note: This element is required only if isAirTravel=true. length <= 99 chars
passengerLastName	conditional	string	This is the last name of the cardholder from the billing details. Note: This element is required only if isAirTravel=true. length <= 99 chars
applePay
country	true	string	The two-uppercase-character ISO 3166 country code.
requestBillingAddress	false	boolean	This indicates whether the customer's billing address should be added to the payment token.

Tokenization Example

<html>

    ...

    <body>

        ...

        <script>

            let instance;

            paysafe.fields.setup("my Base64 encoded single-use-token API key", {

                currencyCode: 'USD'

            }).then(hostedInstance => {

                instance = hostedInstance;

                return instance.show();

            }).then(paymentMethods => {

                if(paymentMethods.card && !paymentMethods.card.error) {

                    var payButton = document.getElementById("payButton");

                    payButton.addEventListener("click", function (event) {

                        instance.tokenize({

                            amount: 1000,

                            transactionType: "PAYMENT",

                            paymentType: "CARD",

                            merchantRefNum: 'merchant-ref-num',

                        }).then(result => {

                            // handle result

                        }).catch(error => {

                            console.log(error);

                        });

                    });

                }

            }).catch(error => {

                console.log(error);

            });

        </script>

    </body>

</html>

Tokenize Example with 3D Secure

For 3DS2 authentication with Visa cards, you need to include email, phone, or cellPhone parameters in the profile object as part of the threeDS setup. If this information is not provided during setup or is not available in the stored profile, email and phone fields will be displayed on the 3DS screen. The customer will be required to populate one of these fields to initiate a transaction.

<html>

    ...

    <body>

        ...

        <script>

            let instance;

            paysafe.fields.setup("my Base64 encoded single-use-token API key", {

                currencyCode: 'USD'

            }).then(hostedInstance => {

                instance = hostedInstance;

                return instance.show();

            }).then(paymentMethods => {

                if(paymentMethods.card && !paymentMethods.card.error) {

                    var payButton = document.getElementById("payButton");

                    payButton.addEventListener("click", function (event) {

                        instance.tokenize({

                            amount: 1000,

                            threeDs: {

                                profile: {

                                    email: "johnsmith@paysafe.com",

                                    phone: "023456789",

                                    cellPhone: "0888112233"

                                } 

                                deviceChannel: "BROWSER"

                            },

                            transactionType: "PAYMENT",

                            paymentType: "CARD",

                            merchantRefNum: 'merchant-ref-num',

                        }).then(result => {

                            // handle result

                        }).catch(error => {

                            console.log(error);

                        });

                    });

                }

            }).catch(error => {

                console.log(error);

            });

        </script>

    </body>

</html>

For 3D Secure enrolled cards, the customer may be shown an overlay window from their card issuer to authorize the payment. 3D Secure 2 is supported only for Visa, Mastercard, and American Express.

Tokenize with 3D Secure 2

3D Secure 2 provides an improved, seamless way to authenticate customers while adding support for mobile applications and for biometric and token validation, and streamlining the checkout experience using “frictionless” authentication. See the 3D Secure 2 documentation for full details on implementing 3D Secure 2.

The merchant must first be configured by Paysafe Group in order to use 3D Secure 2. 3D Secure 2 is supported only for Visa, Mastercard, and American Express.

With 3D Secure 2, the merchant can pass in some additional optional parameters in the threeDS object for Paysafe.js:

authenticationPurpose – Only two values are permitted: PAYMENT_TRANSACTION (default value) and INSTALMENT_TRANSACTION
maxAuthorizationsForInstalmentPayment
billingCycle

See the authentications object in the 3D Secure 2 API documentation for a description of these parameters.

The holderName parameter is mandatory in order to use 3D Secure 2.

Tokenize Example with ApplePay

To tokenize applePay data, you need to pass the paymentType="APPLEPAY" type and additional applePay data in the tokenization options.

This tokenize function accepts an options object and is a promise, that resolves to a single-use payment handle. The payment handle represents the user's sensitive apple pay card data. This handle can be used by the Payments API to take payments. The single-use payment handle is valid for 15 minutes. See setup signature.

<html>

    ...

    <body>

        ...

        <script>

            let instance;

            paysafe.fields.setup("my Base64 encoded single-use-token API key", {

                currencyCode: 'USD',

                fields: {

                   applePay: {

                       selector: '#apple-pay',

                       type: 'buy',

                       label: 'Demo JS',

                       color: 'white-outline',

                   }

                },

            }).then(hostedInstance => {

                instance = hostedInstance;

                return instance.show();

            }).then(paymentMethods => {

                if(paymentMethods.applePay && !paymentMethods.applePay.error) {

                    var payButton = document.getElementById("apple-pay");

                    payButton.addEventListener("click", function (event) {

                        instance.tokenize({

                            amount: 1000,

                            transactionType: "PAYMENT",

                            paymentType: "APPLEPAY",

                            applePay: {

                                country: 'US',

                                requestBillingAddress: true

                            },

                            merchantRefNum: 'merchant-ref-num',

                        }).then(result => {

                            // handle result

                            // Close Apple Pay window

                            instance.complete('success');

                        }).catch(error => {

                            console.log(error);

                            // Close Apple Pay window

                            instance.complete('fail');

                        });

                    });

                }

            }).catch(error => {

                console.log(error);

            });

        </script>

    </body>

</html>

Tokenize Promise Signature

instance.tokenize() function returns a Promise, which contains the tokenization result.

The Promise resolves to the parameters that are described below.

Parameter	Required	Type	Description
result	false	object	Result containing the payment token.
errorResponse	throws	object	If an error occurs, the tokenized will be rejected with the errorResponse object.
errorResponse
code	true	string	Short error code identifying the error type.
displayMessage	true	string	An error message that can be displayed to users.
detailedMessage	true	string	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	false	string	Payment token representing the sensitive card details following successful tokenization.

List of Tokenize Callback Errors

Code	Display Message	Detailed Message	Description
9001	No connection to server.	No connection to server.	The request to the server was unsuccessful. HTTP status code 0 with no response body.
9002	Error communicating with server.	Error communicating with server.	The response from the server cannot be handled. Response format is not JSON. HTTP status code is 200, but no payment token is present. HTTP status code is different from 200, but no error code and description are present.
9003	Invalid fields: ${fields}.	Invalid fields: ${fields}.E.g., Invalid fields: card number,cvv,expiry date,threeDS.authenticationPurpose.	One or more fields have invalid values. The error for invalid fields comes from the front-end validations or when Customer Vault API or 3D Secure 2 returns 5068 or 7508 errors. The possible values are as follows (note the spaces): card number cvv expiry date expiry year expiry month All 3D Secure 2 fields as well. E.g. threeDS.billingCycle.endDate.
9015	There was an error (9015), please contact our support.	Invalid options argument.	The options parameter is not an object.
9037	Error communicating with 3DS server.	Error communicating with 3DS server.	There is an error communicating with the 3DS API.
9039	Enrollment is not accepted. Try again with the same or another card.	Enrollment result is not accepted for the provided account.	The customer's card is not enrolled for 3DS.
9040	Authentication not accepted. Try again with the same or another card.	Authentication result is not accepted for the provided account.	The authentication of the 3DS payment was not successful.
9041	There was an error (9041), please contact our support.	There was an error (9041), please contact our support.	No PaRes is returned from the ACS server
9042	User aborted authentication.	User aborted authentication.	The customer aborted the 3DS authentication process on the issuing bank site.
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 an unhandled error.
9111	There was an error (9111), please contact our support.	Invalid merchant configuration setup.	Used when the merchant configuration setup is invalid
9114	There was an error (9114), please contact our support.	Unable to initiate ThreeDs SDK challenge.	Used when the ThreeDs SDK challenge callback is invoked with error.
9125	There was an error (9125), please contact our support.	Unsupported card brand used: [...].	Used when the customer is using a card brand not supported by the merchant 3D Secure 2 configuration.
9073	There was an error (9073), please contact our support.	Account not configured correctly.	The merchant account used for tokenization is not configured or missing in the admin portal
9131	There was an error (9131), please contact our support.	Status of the payment handle is FAILED	Payment handle Creation failed. For further details, please check Error code in Business portal
ApplePay Specific Errors
9072	There was an error (9072), please contact our support.	The domain name is not verified in developer apple account for merchant id: ${apple_merchant_id}	The domain name is not verified for the developer account for the specified Apple merchant ID.
9083	There was an error (9083), please contact our support.	There was a problem while parsing Apple Pay payment data. Please try again.	Unable to process the Apple Pay data returned by the Apple session.
9089	There was an error (9089), please contact our support.	Merchant validation at Apple failed	The merchant validation against the apple pay servers failed.

Was this page helpful?

On this Page

Async Await
Tokenization Example
Tokenize Example with 3D Secure
Tokenize with 3D Secure 2
Tokenize Example with ApplePay
Tokenize Promise Signature
List of Tokenize Callback Errors

Search Overlay

Tokenize

Was this page helpful?

Thank you for your response!