Version: current

Card Tokenization

About this guide

This page explains how to create a credit card token using our javascript library, EBANX.js, and our Direct API. Tokens allow merchants to perform transactions without sending raw credit card information to their server.

If you are not integrated with EBANX Direct API yet, please take a look at this basic guide about it. Are you not sure if EBANX Direct API is the best option for your e-commerce? Please, talk with one of our integration specialists.

What you will need

Before starting your integration, please make sure that you have:

  1. An EBANX Sandbox account. That's not the case? Please sign up for an Sandbox Account here;
  2. Credit Cards or Debit Cards enabled in your EBANX Dashboard.

How it works

There are two options to create a credit card token:

  1. EBANX.js: In this method, you'll generate the token on the client side, using our EBANX.js javascript library and send the token to your API call.
  2. Direct API: In this method, you'll use only our Direct API to create the token and add it to your payment.

Create a token using EBANX.js

  1. Add EBANX.js to your webpage

    Our client SDK enables you to securely collect payment information from your customers. Add the following script to your webpage:

    <script type="text/javascript" src="https://ebanx-js.ebanx.com/v1.106.0/dist/ebanx.js"></script>

    And initialize it with your Merchant's Configuration:

    EBANX.init({
    publicIntegrationKey: 'your_integration_key_goes_here',
    country: 'br',
    mode: 'test',
    });

  2. Create an object with your payment information

    Create an object with with the following fields:

    const tokenizeOptions = {
    card: {
    number: '4111111111111111',
    dueDate: '12/2025',
    holderName: 'JOAO DA SILVA',
    },
    paymentTypeCode: 'creditcard',
    countryCode: 'br',
    };

  3. Create the token using EBANX.js

    Call the EBANX.cardTokenizer.tokenize function passing the object created in the previous step.

    EBANX.cardTokenizer
    .tokenize(tokenizeOptions)
    .then((tokenizedCard) => {
    // use the tokenizedCard to fullfil your payment
    })
    .catch((error) => {
    // handle any errors that can happen
    });

    EBANX.cardTokenizer.tokenize returns a Promise object, so, make sure you handle the asynchrounous call properly by using a callback function. A successful token creation response contains the following fields. The values will vary for each token creation:

    //The tokenizedCard object created in the previous step will have the following fields:
    {
    payment_type_code: 'visa';
    token: 'c7957fc8d0e92c8fa859120ccbf24ef03486dc2cbc9081447bf883a6c495c71fdcd85b77db23373ae3ab76910a8857eb7788540c190a7160195d51de016699f6';
    }

  4. Add the token to your payment request

    Include the token you obtained in the previous step to your card object in your Direct API call. For more information on our Direct API, click here!

    //If you're using old Javascript syntax, the spread syntax will not work. So in this case you can set the card properties individually.
    "card": {
    ...tokenizedCard //spread of the object returned by EBANX.cardTokenizer.tokenize.
    }

Create a token using Direct API

  1. Call the /ws/token to create the token

    Using the /ws/token API call, pass the credit card information, country, payment type and your integration key. Here's an example:

    curl -X POST 'https://sandbox.ebanxpay.com/ws/token' \
    -d 'request_body={
    "integration_key": "your_test_integration_key",
    "payment_type_code": "creditcard",
    "country": "br",
    "card": {
    "card_number": "4111111111111111",
    "card_name": "Jose da Silva",
    "card_due_date": "10/2020",
    "card_cvv": "123"
    }
    }'

    A successful API call will return the following JSON object:

    {
    "status": "SUCCESS",
    "payment_type_code": "visa",
    "token": "b81cc06bcf0d013c3688eb1b229dc155cd23b5d18781bee0fb246537cb42f151117ae7f06617cae384d4829c82151983177c87584686fad5e497dde1d0871862",
    "masked_card_number": "411111xxxxxx1111"
    }

  2. Add the token to your payment request

    Include the token you obtained in the previous step to your card object in your Direct API call. For more information on our Direct API, click here!

    "card": {
    "token": "b81cc06bcf0d013c3688eb1b229dc155cd23b5d18781bee0fb246537cb42f151117ae7f06617cae384d4829c82151983177c87584686fad5e497dde1d0871862"
    }

Live Sample

Here's a sample of a token being generated using EBANX.js:

Importing Tokens

In case you want to import existing tokens from a different provider, you'll need to export them safely using an encrption key. Please use this public key to encrypt files from your existing provider before sending it to EBANX:

Getting help

We hope this article was enlightening, but in case we’ve failed to take out your doubts you have the following options to keep on seeking for answers:

  • If you’re not our partner yet and would like to know more about our prices and conditions please fill our this form and our commercial team will get in touch with you.
  • In case you’re already our partner please get in touch with our support team at integration@ebanx.com.
Edit this page
Last updated on by FlavioCostaeSilva
On this page