Search Overlay
Searchbox clear search filters ESC
Filter PreferencesClear

No results found

Tokenize

This tokenize function accepts a callback that receives a single-use token representing the user's sensitive card data. This token can be used by the Card Payments API to take payments. Single-use tokens are valid for only 5 minutes and are not consumed by verification. See Card Payments with a Token for more details.

The tokenize function has the following signature:

instance.tokenize(options, function(instance, error, result) {

  ...

});

Tokenize Function parameters

Parameter Required Type Description
options false object Optional tokenization settings, that contain information about the 3D Secure (3DS) flow and additional customer data sent to the Customer Vault.
callback true function Callback function invoked with the result of the tokenization.
{return} false undefined No value returned from method invocation.
options
threeDS false object An object representing the 3DS parameters. Include this object to enable 3DS.
vault false object Additional customer data associated with the single-use token from the Customer Vault.
singleUseCustomerToken false string This is the single-use profile token that the merchant generated using the Single-use profile token request.
paymentTokenFrom false string This is single-use card token associated with the customer profile.
threeDS
amount true number

Integer representing the amount in minor units to charge the customer's card following 3DS check. 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. The amount has to be supplied as a positive number and shouldn't be longer than 9 digits.

Min = 1

Max = 999999999

When using 3DS 2 (i.e. useThreeDSecureVersion2= true), amount with value: "0" can be passed.
currency true string The currency code for the merchant's account, for example, USD or GBP.
accountId true number

The id of the selected merchant account to use to process the payment.
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
vault
holderName conditional string

Name of the card holder, 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.
billingAddress false object Card billing address - additional details for the BillingAddress object can be found in the Customer Vault documentation.
shippingAddress false object This is the shipping address of the customer. Applies for 3D Secure 2.
billingAddress
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 First line of the street address
street2 false string Second line of the street address
useAsShippingAddress false boolean Indicates that this address will be used also as shipping address. Applies for 3D Secure 2.
shippingAddress
recipientName false

string

length<=255

 This is the recipient's name.
street false

string

length<=50

 This is the first line of the street address of the shipping address.
street2 false

string

length<=50

 This is the second line of the street address of the shipping address.
city false

string

length<=40

 This is the shipping address city.
country true

string

2-character ISO code

 This is the shipping address country.
zip true

string
length<=10

This is the shipping address zip or postal code.

Required for countries with postal code.
state false

string
length<=40

 This is the shipping address state/province/region.
shipMethod false string

This is the method of shipment. Applies for 3D Secure 2. Possible values are:

  • N – Next Day/Overnight
  • T – Two-Day Service
  • C – Lowest Cost
  • O – Other
  • S – Same Day
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

This is the email address to which the merchandise was delivered.

length <= 240 chars
airlineTravelDetails
To see the list of fields for the airlineTravelDetails object, see the Cards API Reference.
passenger
To see the list of fields for the passenger object, see the Cards API Reference.
agencyAddress
To see the list of fields for the agencyAddress object, see the Cards API Reference.
flight
To see the list of fields for the flight object, see the Cards API Reference.
ticket
To see the list of fields for the ticket object, see the Cards API Reference.
travelAgency
To see the list of fields for the travelAgency object, see the Cards API Reference.
tripLegs
To see the list of fields for the tripLegs object, see the Cards API Reference.
profile
email false string

This is the email address of the customer.

length <= 255 chars
phone false string

This is the customer's primary phone.

length <= 40 chars
cellphone false string

This is the customer's cell phone.

length <= 40 chars
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

Tokenize Example

<html>

	...

	<body>

		...

		<script>

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

				if (error) {

					console.log(error);

				} else {

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

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

						instance.tokenize(function(instance, error, result) {

							if (error) {

								console.log(error);

							} else {

								// handle result

							}

						});

					});

				}

			});

		</script>

	</body>

</html>

Tokenize Example with 3D Secure Enabled

<html>

  ...

  <body>

    ...

    <script>

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

        if (error) {

          console.log(error);

        } else {

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

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

            instance.tokenize({

                threeDS: {

                  amount: 500,

                  currency: "USD",

                  accountId: 1234567890

                }

              }, function(instance, error, result) {

                if (error) {

                  console.log(error);

                } else {

                  // handle result

                }

            });

          });

        }

      });

    </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 is supported only for Visa and Mastercard. 3D Secure 2 is supported only for Visa, Mastercard, and American Express.

Tokenize Example with 3D Secure 2 Enabled

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. The cardholder's email, phone or cell phone is mandatory for Visa products.

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, the email and phone fields will be displayed in a pop-up window when the transaction is initialized. The customer will be required to populate one of these fields to proceed with the payment.

<html>

  ...

  <body>

    ...

    <script>

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

        if (error) {

          console.log(error);

        } else {

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

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

            instance.tokenize({

                threeDS: {

                  profile: {

                    email: "johnsmith@paysafe.com",

                    phone: "023456789",

                    cellPhone: "0888112233"

                  } 

                  amount: 500,

                  currency: "USD",

                  accountId: 1234567890,

				  useThreeDSecureVersion2: true,

				  authenticationPurpose: "INSTALMENT_TRANSACTION",

				  maxAuthorizationsForInstalmentPayment: 12,

				  billingCycle: {

				    frequency: 1,

				    endDate: "2020-01-26"

				  }

				},

				vault: {

				  holderName: "Aleks Smith"

				}

              }, function(instance, error, result) {

                if (error) {

                  console.log(error);

                } else {

                  // handle result

                }

            });

          });

        }

      });

    </script>

  </body>

</html>

Tokenize Example with Additional Customer Details

<html>

  ...

  <body>

    ...

    <script>

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

        if (error) {

          console.log(error);

        } else {

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

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

            instance.tokenize({

              vault: {

                holderName: "John Smith",

                  billingAddress: {

                    country: "CA",

                    zip: "M5H 2N2",

                    state: "ON",

                    city: "Toronto",

                    street: "100 Queen Street",

                    street2: "201"

                  }

                }

              }, function(instance, error, result) {

                if (error) {

                  console.log(error);

                } else {

                  // handle result

                }

            });

          });

        }

      });

    </script>

  </body>

</html>

The tokenize callback function has the following signature:

function callback(instance, errorResponse, result) {

	if (errorResponse) {

		// handle error

	} else {

		// use token

	}

}

The parameters are described below.

Parameter Required Type Description
instance true object Paysafe.js instance
errorResponse false object Object containing information for the error.
result false object

Result containing the payment token.
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 return 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.
9004 There was an error (9004), please contact our support. Callback should be function. The callback parameter passed to tokenize is not a function.
9015 There was an error (9015), please contact our support. Invalid options argument. The options parameter is not an object.
9034 There was an error (9034), please contact our support. ThreeDS amount should be number. The amount parameter passed to tokenize is not a number.
9035 There was an error (9035), please contact our support. ThreeDS currency should be valid currency code. The currency parameter passed to tokenize is not a string.
9036 There was an error (9036), please contact our support. ThreeDS accountId should be number. The accountId parameter passed to tokenize is not a number.
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.
9043 There was an error (9043), please contact our support. HolderName should be valid. The holder name parameter is not a string, is longer than 160 characters or is less than 2 characters (when using 3DS 2 and supported card brand for 3DS 2).
9044 There was an error (9044), please contact our support. BillingAddress country should be valid country code. The country parameter is not a string or is not 2 character country code.
9045 There was an error (9045), please contact our support. BillingAddress zip should be valid zip code. The zip parameter is not a non empty string or is longer than 10 characters.
9046 There was an error (9046), please contact our support. BillingAddress state should be valid state. The state parameter is not a string or is longer than 40 characters.
9047 There was an error (9047), please contact our support. BillingAddress city should be valid city. The city parameter is not a string or is longer than 40 characters.
9048 There was an error (9048), please contact our support. BillingAddress street should be valid street. The street parameter is not a string or is longer than 50 characters.
9049 There was an error (9049), please contact our support. BillingAddress street2 should be valid street. The street2 parameter is not a string or is longer than 50 characters.
9050 There was an error (9050), please contact our support. ThreeDS should be object. The threeDS parameter is not an object.
9051 There was an error (9051), please contact our support. Vault should be object. The vault parameter is not an object.
9052 There was an error (9052), please contact our support. BillingAddress should be object. The billingAddress parameter is not an object.
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 unhandled error.
9111 There was an error (9111), please contact our support. Invalid merchant configuration setup. Used when the merchant configuration setup is invalid.
9112 There was an error (9112), please contact our support. Invalid threeDS useThreeDSecureVersion2 parameter. Used when the supplied useThreeDSecureVersion2 parameter is not a boolean.
9113 There was an error (9113), please contact our support. The accountId provided is not enabled for 3DS version 2. Used when the supplied accountId (accounts.CC) is not enabled for 3DS version 2.
9114 There was an error (9114), please contact our support. Unable to initiate ThreeDs SDK challenge. Used when the when 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 card brand not supported by the merchant 3D Secure 2 configuration.
On this Page