Card Verification ensures that a card is valid, and free from restrictions imposed by the card issuer. It also helps confirm the authenticity of the card information provided during a transaction, enhancing the overall security of your payment system and reduces the risk of fraud. In this guide, you'll learn how to verify card details with the EBANX API.
How it works
Verification can be performed in two ways.
- Zero Dollar Transaction - A special verification transaction with no amount charged.
- Will be used if supported by the acquirers and issuers, otherwise Ghost Authorization is applied.
- Ghost Authorization - A charge authorization for a small unitary amount in the local currency, followed by an immediate cancellation (the authorization is never captured).
Requirements
- API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
Instructions
Follow the steps below.
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.
https://sandbox.ebanx.com/ws/verifycardDefine your parameters
The following fields are required to perform a card verification:
Parameter Description integration_keyYour EBANX integration key payment_type_codeSet to creditcard or debitcard countryTwo-letter country code. device_idThe unique identification of a customer’s device card.card_numberCard number card.card_nameCardholder name (as written om the card) card.card_due_dateCard's valid thru date (formatted as mm/yyyy) card.card_cvvCard verification value (CVV, CVV2 or CVC) Card on FileYou can initiate a Card on File transaction during the card verification process, which allows you to securely store the customer’s card details for future transactions while verifying the card’s validity. A successful response will include a
mandate_id, which is the brand transaction ID from the acquirer. This ID must be stored for future recurrent transactions.Sample request
Use the following example to initiate a request with the information from the previous step.
curl -X POST \
--location 'https://sandbox.ebanxpay.com/ws/verifycard' \
--header 'Content-Type: application/json' \
--data '{
"integration_key": "your_ebanx_integration_key",
"operation": "request",
"country": "br",
"payment_type_code": "creditcard",
"card": {
"card_number": "1111111111111111",
"card_name": "John Doe",
"card_due_date": "07/2029",
"card_cvv": "111"
},
// Optional -> Card-on-File initiation
"cof_info": {
"cof_type": "Initial",
"initiator": "CIT",
"trans_type": "CUSTOMER_COF"
}
}'Sample Response
A successful request will return a response similar to the example below.
{
"status": "SUCCESS",
"payment_type_code": "creditcard",
"card_issuer_country": "br"
"card_verification": {
"transaction_status": {
"code": "OK",
"description": "Accepted"
},
"transaction_type": "ZERO DOLLAR"
},
// Card-on-File response (if initiated in the request)
"cof_info": {
"cof_type": "INITIAL",
"initiator": "CIT",
"mandate_id": "{mandate_id_here}"",
"trans_type": "CUSTOMER_COF"
},
}Congratulations!
You have succesfully integrated Card Verification.
Card verification (during card tokenization)
Card verification can also be performed during card tokenization. Using tokens generated from verified cards typically results in higher approval rates compared to those generated with unverified cards. If a token operation is requested with the card verification flag enabled, no token will be created if the verification results indicate that the card is not eligible.
Instructions
Follow the steps below to verify a card during tokenization.
Define your parameters
In addition to the parameters required by the ws/token endpoint, you must include the following:
Parameter Description verify_cardSet to true Sample request
Call the /ws/token endpoint and provide the information gathered in the previous step.
curl -X POST \
--location 'https://sandbox.ebanxpay.com/ws/token' \
--header 'Content-Type: application/json' \
--data '{
"integration_key": "your_ebanx_integration_key",
"country": "br",
"payment_type_code": "creditcard",
"verify_card": true, // Set to 'true'
"card": {
"card_number": "1111111111111111",
"card_name": "John Doe",
"card_due_date": "07/2029",
"card_cvv": "111"
}
}Sample response
A successful request will return a response similar to the example below.
Eligible card
{
"status": "SUCCESS",
"payment_type_code": "creditcard",
"token": "abcdef123456abcdef123456...", // Token created
"masked_card_number": "111111xxxxxx1111",
"card_verification": {
"transaction_status": {
"code": "OK", // Eligible
"description": "Accepted"
},
"transaction_type": "ZERO DOLLAR"
}
}Non-eligible card
{
"status": "SUCCESS",
"payment_type_code": "creditcard",
"token": null, // Token NOT created
"masked_card_number": "111111xxxxxx1111",
"card_verification": {
"transaction_status": {
"code": "NOK", // Not Eligible
"description": "Not accepted"
},
"transaction_type": "ZERO DOLLAR"
}
}Congratulations!
You have succesfully integrated Card Verification (during tokenization).
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.
API Reference
Click here to access detailed API documentation to integrate efficiently.
Mock Customer Data
Click here to view mock customer data for testing and validating user flows.
Error Codes
Click here to review common error codes to troubleshoot and resolve issues quickly.
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.