Network Tokens using Direct API

The EBANX Network Token provides a secure, tokenized version of a customer’s payment card details, designed to simplify recurring payments while enhancing security and reducing the risk of fraud. By replacing sensitive card information with a unique encrypted token, network tokenization ensures compliance with security standards like PCI DSS, while also improving the payment experience for returning customers. In this guide, you’ll learn how to integrate EBANX Network Tokens into your payment flow, enabling secure and efficient transactions.

Tokenization methods

There are two options to create a token.

Method	Description	Side
EBANX.js	Generate the token on the client side using the EBANX.js JavaScript library, and then send the token in your API call.	Client Side
Direct API	Use the Direct API to generate the token server-side and include it in your payment request.	Server Side

How it works

Network Tokenization is divided into two steps.

1. Token request - You request a network token from EBANX via the /ws/token endpoint.
2. Token usage - Once a network token is ready for use, you can include it in the card node for subsequent payment requests.

Requirements

• API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
• Card information - Ensure you have access to the customer’s card details to tokenize.

Instructions

Follow the steps below.

1. Select your environment

   Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.

   SandboxProduction

   https://sandbox.ebanx.com/ws/token

2. Define your parameters

   The following fields are required to obtain an EBANX network token:

   Parameter	Description
   integration_key	Your EBANX integration key
   payment_type_code	Payment method (e.g., creditcard).
   country	Two-letter country code. (e.g., br for Brazil).
   card.card_number	Card number
   card.card_name	Cardholder name (as written om the card)
   card.card_due_date	Card's valid thru date (formatted as mm/yyyy)
   card.card_cvv	Card verification value (CVV, CVV2 or CVC)

3. Sample request

   Use the following to initiate a request by calling /ws/token with information collected from the previous step.

   When you request a network token, the request will be received by EBANX, and the token will be generated.

   
   

   curl -X POST \
     --location 'https://sandbox.ebanx.com/ws/token' \ 
     --header 'Content-Type: application/json' \
     --data '{
     "integration_key": "integration_key",
     "payment_type_code": "debitcard",
     "country": "br",
     "card": {
       "card_number": "5200000000001096",
       "card_name": "Jose da Silva",
       "card_due_date": "10/2021",
       "card_cvv": "123"
     },
   }

4. Sample response

   A successful request will return a response similar to the example below.

   {
     "status": "SUCCESS",
     "payment_type_code": "mastercard",
     "token": "b81cc06bcf0d013c3688eb1b229dc155cd23b5d18781bee0fb246537cb42f151117ae7f06617cae384d4829c82151983177c87584686fad5e497dde1d0871862",
     "masked_card_number": "520000xxxxxx1096",
   }

5. Create a payment (with token)

   Use the token to process payments in the card object of your Direct API call.

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

   For recurrent transactions, set the network_token_mode field to recurrent.

   "card": {
       "token": "b81cc06bcf0d013c3688eb1b229dc155cd23b5d18781bee0fb246537cb42f151117ae7f06617cae384d4829c82151983177c87584686fad5e497dde1d0871862",
       "network_token_mode": "recurrent"
       }
   For more information about creating payments, refer to the

   Direct API Guidechevron_right
   
   

6. Congratulations!

   You have succesfully integrated EBANX Network Tokens.

Network Token Status

To check the status of a network token, use the /ws/token/query endpoint.

1. Request token status

   Example request:

   curl -X POST \
     --location 'https://sandbox.ebanx.com/ws/token/query' \ 
     --header 'Content-Type: application/json' \
     --data '{
     "integration_key": "integration_key",
     "token": "b81cc06bcf0d013c3688eb1b229dc155cd23b5d18781bee0fb246537cb42f151117ae7f06617cae384d4829c82151983177c87584686fad5e497dde1d0871862"
   }

2. Response

   Upon success, the following JSON object will be returned:

   Example response:

   {
       "card_type": "mastercard",
       "country": "not informed",
       "due_date": "10/2021",
       "bin": "520000",
       "last_four": "1096",
       "network_token_credit_card_name": "Jose da Silva",
       "network_token_cryptogram": "network_token_cryptogram_example",
       "network_token_due_date": "06/2025",
       "network_token_pan": "5211111111111111",
       "network_token_status": "ACTIVE"
   }

Possible values include:

Status	Description	Source
REQUESTED_SUCCESSFULLY	The network token request was successful, and it is now pending provisioning.	Initial request
FAILED_REQUEST	It was not possible to request the network token	Initial request
NOT_PROVISIONED	The network token provisioning was not possible. The issuer may have denied provisioning or an error may have occurred in the token provisioning	Status query
ACTIVE	The network token can be used in transactions	Status query
SUSPENDED	The network token cannot be used in transactions at the moment. This state can change to ACTIVE or DELETED in the future	Status query
DELETED	The network token is deactivated permanently and cannot be used in transactions anymore. This is the final state for the network token, and occurs when the customer closed his bank account for example	Status query

Test Cards

Below are the test card numbers you can use to verify your integration and check the network token status during the token request process.

Initial Token Request

Card	Token Status
Any card (E.g. 4111111111111111)	REQUESTED_SUCCESSFULLY
5102026827345142	FAILED_REQUEST

Token Status Query

Card	Token Status	Description
Any card (E.g. 4111111111111111)	ACTIVE	The network token can be used in transactions
5102026827345142	NOT_FOUND	We couldn't find a network token related to the token
5237990616767170	WAIT_PROVISIONING	Waiting for the issuer to provision the network token
5169808734990544	NOT_PROVISIONED	The network token provisioning was not possible. The issuer may have denied provisioning or an error may have occurred in the token provisioning
5498527767276454	SUSPENDED	The network token cannot be used in transactions at the moment. This state can change to ACTIVE or DELETED in the future
5448419208577578	DELETED	The network token is deactivated permanently and cannot be used in transactions anymore. This is the final state for the network token, and occurs when the customer closed his bank account for example

Errors

If a tokenization request fails on the /ws/token endpoint, EBANX will return a JSON object with error details.

Error object - The following key-value pairs exist with each error response.

// Sample error object
{
  "status": "ERROR",
  "status_code": "BP-DR-61",
  "status_message": "It was not possible to create the token for this card - please, try again later"
}

Token related errors

Code arrow_downward	Error Message arrow_downward	Description arrow_downward
BP-DR-35	Invalid payment_type_code: X	The payment method is not enabled. Contact our Integration Team.
BP-DR-36	Payment type is not active	The payment method is not enabled. Contact our Integration Team.
BP-DR-48	Field card is required for this payment type	The field was not filled.
BP-DR-49	Field card.card_number is required	The field was not filled.
BP-DR-51	Field card.card_name is required	The field was not filled.
BP-DR-56	Field card.card_due_date is required	The field was not filled
BP-DR-55	Parameter card.card_cvv is invalid	The parameter has more characters than the limit allowed.
BP-DR-61	It was not possible to create the token for this credit card - please, try again later	It was not possible to complete the operation.
BP-DR-67	Field card.card_due_date is invalid	The parameter sent was not valid.
BP-DR-75	Card number is invalid	The parameter sent was not valid.
BP-DR-77	Country is not enabled	The country is not available. Contact our Integration Team.
BP-DR-78	Country not enabled for merchant	The country is not available on your account. Contact our Integration Team.
BP-DR-83	Foreign credit card cannot be processed.	The credit card was issued in a country other than the country of the acquirer.
BP-DR-95	Parameter card.card_name must be a valid name: number isn’t allowed	The customer may have mistaken the fields and put the number of the card instead of the name.
BP-DR-101	Card is not eligible for ecommerce	The card provided by the customer cannot be used for online transactions
BP-DR-104	Payment type is not valid for this country	The payment type is invalid for the country sent.

Resources

Use the following resources when testing in your sandbox environment.

Sample Cards

Click here to view mock card data to validate your payment integration.

Click to explorechevron_right

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explorechevron_right

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explorechevron_right

Still need help?

We hope this article was helpful. If you still have questions, you can explore the following options:

• Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.