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) {
  ...
});

The function signature contains the following 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.
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.
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.

vault
holderName false string Name of the card holder
billingAddress false object Card billing address - additional details for the BillingAddress object can be found in the Customer Vault documentation.
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

An example is shown below:

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

An alternative 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 3DS enrolled cards, the customer may be shown an overlay window from their card issuer to authorize the payment. 3DS is supported only for Visa and Mastercard.

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

One or more fields have invalid values. The error for invalid fields comes from the front-end validations or when the Customer Vault API returns 5068 or 7508 errors.

The possible values are as follows (note the spaces):

  • card number
  • cvv
  • expiry date
  • expiry year
  • expiry month
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 aborts the 3DS authentication process on the issuing bank site.
9043 There was an error (9043), please contact our support. Vault holderName should be valid. The holder name parameter is not a string or is longer than 160 characters.
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.
Did you find this page useful?