Skip to main content
The Tokenizer is a frontend SDK that transforms a credit card’s sensitive data into an opaque, disposable tokenId, right in the buyer’s browser. This token is what you send in creditCard.token when creating a transaction — so the card number never passes through your server, reducing your PCI scope.
The card’s sensitive data (PAN, CVV) is collected and sent by the SDK in the buyer’s browser, directly to Z2Pay’s secure vault. Never send the full card number or the CVV to your backend: your server should only ever receive the tokenId.

​
Why use the SDK

When the buyer enters the card data at checkout, the SDK sends the number (PAN), the CVV, and the expiry date directly from the browser to the vault and to the PSPs — never to your backend. What your server receives is only an opaque tokenId: a string that is meaningful only within Z2Pay and that, on its own, reveals nothing about the card.

No card data on your server

The PAN/CVV go from the browser directly to the vault. You only ever see the tokenId.

Disposable token

The tokenId is temporary and expires automatically (24h TTL).

​
Installation

You can load the SDK via a <script> tag (CDN) or install it as a dependency via npm. 
<script src="https://cdn.z2pay.com/assets/tokenizer.js"></script>
<!-- Exposes the constructor on window.Z2Pay.Tokenizer -->

​
Configuration

Create a Tokenizer instance passing the configuration below.
​
companyId
string
required
Public identifier of your company. It is safe to expose it on the frontend.
​
apiUrl
string
required
Base URL of the Z2Pay API. Use https://api.sandbox.z2pay.com in the sandbox and the production URL (see Environments) in production.
​
timeout
number
default:"15000"
Optional. Maximum time, in milliseconds, for tokenization. Default: 15000 (15s).

​
Tokenize a card

Call createCardToken with the card data. The SDK returns a { tokenId } object.
​
number
string
required
Card number (PAN), digits only. Never reaches your server.
​
holder
string
required
Cardholder name, as printed on the card.
​
document
string
required
Cardholder’s CPF or CNPJ, digits only.
​
cvv
string
required
Card security code (CVV).
​
expiration
string
required
Expiry in the MM/YYYY format (e.g. 12/2030). The MM/YY format is also accepted.
<script src="https://cdn.z2pay.com/assets/tokenizer.js"></script>
<script>
  const tokenizer = new window.Z2Pay.Tokenizer({
    companyId: 'comp_a1b2c3d4',
    apiUrl: 'https://api.sandbox.z2pay.com',
  });

  async function tokenizeCard() {
    const { tokenId } = await tokenizer.createCardToken({
      number: '4111111111111111',
      holder: 'MARIA DA SILVA',
      document: '12345678909',
      cvv: '123',
      expiration: '12/2030',
    });

    // Send tokenId in creditCard.token when creating the transaction on your backend
    return tokenId;
  }
</script>

​
Response

createCardToken resolves with an object containing the opaque tokenId.
​
tokenId
string
Opaque, temporary token. Use it in creditCard.token in the POST /transactions. Expires in 24h.
{
  "tokenId": "tok_a1b2c3d4e5f6"
}
The prefix and exact format of the tokenId are defined internally — treat the value as an opaque string and do not attempt to parse it.
The tokenId is valid for 24 hours (TTL) and single-use. Tokenize the card shortly before creating the transaction.

​
Using the token in a transaction

With the tokenId in hand, create the transaction on your backend by providing it in creditCard.token: 
curl -X POST https://api.sandbox.z2pay.com/transactions \
  -H "x-api-key: YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 19900,
    "paymentMethod": "credit_card",
    "creditCard": {
      "token": "tok_a1b2c3d4e5f6"
    }
  }'
This example illustrates how the token is used. The exact fields for creating a transaction are documented on the Transactions page. Values are always integers in cents (19900 = R$ 199.00).

​
How it works under the hood

When you call createCardToken, the SDK — running in the buyer’s browser — sends the sensitive data (PAN, CVV) directly to Z2Pay’s secure vault and to its PSPs, in parallel, and exchanges everything for a single opaque tokenId. The card data never passes through your backend; you only receive the tokenId. All communication with the vault, the PSPs, and the tokenization service is handled by the SDK — you don’t need to orchestrate any of it by hand.

​
Common errors

  • Failed to generate any tokens: no PSP or vault was able to tokenize the card. Common causes: invalid card data or no PSP configured for the company. Check the companyId and the data provided.
  • Timeout: tokenization exceeded the timeout (default 15s). This usually indicates a slow network on the buyer’s side.
  • Network / API error: if the call to the Z2Pay API fails, the SDK throws an Error with the status and the response body. See Errors for the API error format.

​
See also

Transactions

Use the tokenId when creating a card transaction.

Cards

Saved cards and persistent tokenization.

Test cards (sandbox)

Card numbers for testing in the sandbox environment.

Environments

Sandbox and production URLs.