Version: current

UX Recommendations for Brazil

About this guide

This page will present some resources to help you to provide a better user experience for your customers in Brazil. The content is divided into three main sections, covering mandatory fields translations, field validation and checkout live suggestions.

If you are looking for an integration guide with mandatory parameters and examples, you can find it here:

Mandatory fields

Below you will find all the mandatory fields, as well the translations for both Field and Placeholder texts.

Personal information

FieldTranslationPlaceholder
Full Name
payment.name
Nome completo
Email
payment.email
Email
Phone number
payment.phone_number
TelefoneFixo ou Celular
Document
payment.document
CPF ou CPNJ

Credit and Debit Information

FieldTranslationPlaceholder
Cardholder Name
payment.creditcard.card_name
Nome do titularComo impresso no cartão
Card Number
payment.creditcard.card_number
Número do Cartão
Expiration Date
payment.creditcard.card_due_date
Validade do CartãoMM/AAAA
CVV
payment.creditcard.card_cvv
Código de Segurança (CVV)
Installments
payment.instalments
ParcelamentoSelecione o número de parcelas

Billing Address Information

These fields are needed for credit and debit card transactions only.

FieldTranslationPlaceholder
Zipcode
payment.zipcode
CEP
Country
payment.country
PaísSelecione seu país
State
payment.state
EstadoSelecione seu estado
City
payment.city
Cidade
Address
payment.address
EndereçoRua, avenida, etc
Street Number
payment.street_number
Número

Validation

Below you will find how to validate each mandatory field, preventing user errors and guaranteeing a correct payment processing in Brazil.

Personal information

Field name and parameterValidationsError messages
Email
payment.email
REGEX: ^[a-zA-Z0-9.!#$%&'*+/=?^_{\|}~-]+@[a-zA-Z0-9]\(?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9]\(?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$Empty field:
Este campo é obrigatório

Invalid format:
Este email parece estar incorreto
Phone Number
payment.phone_number
10 digits
Mask: XX XXX XXXXX
REGEX: (?:(^\+\d{2})?)(?:([1-9]{2})
Empty field:
Este campo é obrigatório

Invalid format:
Este telefone parece estar incorreto
Document
payment.document
CPF: Length of 11 digits, numeric only.

Mask: 000.000.000-00
Empty field:
Este campo é obrigatório

Invalid format:
Este documento parece estar incorreto

Credit card information

Field name and parameterValidationsError messages
Credit card number
payment.creditcard.card_number
Masks:
  - AMEX: 9999 9999 9999 999
  - Other Brands: 9999 9999 9999 9999

Regular Expression:
https://developer.ebanx.com/docs/resources/validation-rules/
Empty field:
Este campo é obrigatório

Invalid format:
O número do cartão parece estar incorreto
Expiration Date
payment.creditcard.card_due_date
Mask: 99/9999
REGEX: ^(0[1-9]|1[0-2])\/([0-9]{4})$
Empty field:
Este campo é obrigatório

Invalid format:
A data de validade parece estar incorreta
CVV
payment.creditcard.card_cvv
AMEX: 4 digits, numeric only
Other Brands: 3 digits, numeric only
Empty field:
Este campo é obrigatório

Invalid format:
O código parece estar incompleto

Billing address information

Field name and parameterValidationsError messages
Zip Code
payment.zipcode
8 digits, numeric only
Simple regex to validate 8 numbers without the dash ( - )
[0-9]{8}
Empty field:
Este campo é obrigatório

Invalid format:
O CEP parece estar incorreto
State
payment.state
[[“Acre”, “AC”],
[“Alagoas”, “AL”],
[“Amapá“, “AP”],
[“Amazonas”, “AM”],
[“Bahia”, “BA”],
[“Ceará“, “CE”],
[“Distrito Federal”, “DF”],
[“Espírito Santo”, “ES”],
[“Goiás”, “GO”],
[“Maranhão”, “MA”],
[“Mato Grosso”, “MT”],
[“Mato Grosso do Sul”, “MS”],
[“Minas Gerais”, “MG”],
[“Pará“, “PA”],
[“Paraíba”, “PB”],
[“Paraná“, “PR”],
[“Pernambuco”, “PE”],
[“Piauí“, “PI”],
[“Rio de Janeiro”, “RJ”],
[“Rio Grande do Norte”, “RN”],
[“Rio Grande do Sul”, “RS”],
[“Rondônia”, “RO”],
[“Roraima”, “RR”],
[“Santa Catarina”, “SC”],
[“São Paulo”, “SP”],
[“Sergipe”, “SE”],
[“Tocantins”, “TO”]]
Empty field:

Invalid format:

Validation snippets

You can use the following Javascript funcions to validate some of the mandatory fields requested in your checkout.

phone_number_validation.js
function validatePhoneNumber(phoneNumber){
const re = /^\([1-9]{2}\) (?:[2-8]|9[1-9])[0-9]{3}\-[0-9]{4}$/;
return re.test(String(phoneNumber));
}
zipcode_validation.js
function validateZipcode(zipcode){
const re = /[0-9]{8}/;
return re.test(String(zipcode));
}
cpf_cnpj_length_validation.js
var options = {
onKeyPress: function (cpf, ev, el, op) {
var masks = [000.000.000-000,00.000.000/0000-00];
mask = (cpf.length > 14) ? masks[1] : masks[0];
el.mask(mask, op);
}
}
$(.cpfOuCnpj’).mask(000.000.000-000, options);
cpf_validation.js
function validateCPF(cpf) {
var number, digits, sum, i, result, equal_digits;
cpf = cpf.replace(/[^\d]+/g,'');
equal_digits = 1;
if (cpf.length != 11)
return false;
for (i = 0; i < cpf.length - 1; i++)
if (cpf.charAt(i) != cpf.charAt(i + 1)){
equal_digits = 0;
break;
}
if(equal_digits == 1)
return false;
number = cpf.substring(0,9);
digits = cpf.substring(9);
sum = 0;
for (i = 10; i > 1; i--)
sum += number.charAt(10 - i) * i;
result = sum % 11 < 2 ? 0 : 11 - sum % 11;
if (result != digits.charAt(0))
return false;
number = cpf.substring(0,10);
sum = 0;
for (i = 11; i > 1; i--)
sum += number.charAt(11 - i) * i;
result = sum % 11 < 2 ? 0 : 11 - sum % 11;
if (result != digits.charAt(1))
return false;
return true;
}
cnpj_validation.js
function validateCNPJ(cnpj) {
var i, equal_digits = 1, limit, numbers, sum, pos, result, digits;
cnpj = cnpj.replace(/[^\d]+/g,'');
if (cnpj.length != 14)
return false;
for (i = 0; i < cnpj.length - 1; i++){
if (cnpj.charAt(i) != cnpj.charAt(i + 1)){
equal_digits = 0;
break;
}
}
if(equal_digits == 1)
return false;
limit = cnpj.length - 2
numbers = cnpj.substring(0,limit);
digits = cnpj.substring(limit);
sum = 0;
pos = limit - 7;
for (i = limit; i >= 1; i--) {
sum += numbers.charAt(limit - i) * pos--;
if (pos < 2)
pos = 9;
}
result = sum % 11 < 2 ? 0 : 11 - sum % 11;
if (result != digits.charAt(0))
return false;
limit = limit + 1;
numbers = cnpj.substring(0,limit);
sum = 0;
pos = limit - 7;
for (i = limit; i >= 1; i--) {
sum += numbers.charAt(limit - i) * pos--;
if (pos < 2)
pos = 9;
}
result = sum % 11 < 2 ? 0 : 11 - sum % 11;
if (result != digits.charAt(1))
return false;
return true;
}

Checkout recommendations

Below you will find live code examples, where you can view and test the checkout experience in this country. Also, you will find recommendations to offer a better experience for your customers.

Personal information

Preview
Informações Pessoais
Todas as informações são obrigatórias, exceto "complemento".

CPF

Endereço

Opcional

Live code editor
Instructions
  • These fields are required for any payment method in Brazil;
  • If the customer provided this information in previous steps, you can reuse it to reduce friction.

Credit and debit card information

Preview
Dados do Cartão
Todas as informações abaixo são obrigatórias.

Live code editor
Instructions
  • Be careful to show installment (Parcelas) options only for Credit Card payments, since they are not available for Debit Card payments
  • Offer a tooltip explaining CVV: "Código de 3 números encontrado na parte de trás do cartão. Em cartões AMEX, o código é de 4 números e está na frente do cartão."

Payment method selection

Payment method selection

Instructions
  • Present all payment methods clearly
  • Make the selector, being it a card or a radio list, to look clickable
  • You can use icons to make each payment method more recognizable

Credit card selection

Credt card

Instructions
  • Use terminologies that are familiar to the user (check Mandatory Fields above)
  • You can use a clear call to action to reinforce the method selection
  • If using Installments (Parcelas), it can be interesting to show it together with the total amount (Check Total Order Amount)

Debit card selection

Debit card

Instructions
  • Use terminologies that are familiar to the user (check Mandatory Fields above)
  • You can use a clear call to action to reinforce the method selection
  • Be careful to not show installment (Parcelas) options here, since they are only available for credit card payments

Boleto selection

Boleto

Instructions
  • You can offer a short explanation when the payment method is selected.
  • You can use a clear call to action to reinforce the method selection.

E-Wallets selection

E-wallet

E-wallet

E-wallet

Instructions
  • You can offer a short explanation when the payment method is selected.
  • You can use a clear call to action to reinforce the method selection.

Online Debit selection

Bank Transfer

Instructions
  • You can offer a short explanation when the payment method is selected.
  • You can use a clear call to action to reinforce the method selection.
  • Since the customer is going to be redirected to her/his bank site, it's necessary to show the bank selector when the customer chooses "Internet Banking"

Bank Transfer selection

Bank Transfer

Bank Transfer

Bank Transfer

Bank Transfer

Instructions
  • You can offer a short explanation when the payment method is selected.
  • You can use a clear call to action to reinforce the method selection.

Total order amount

RegularFree shipping
Total amount description - RegularTotal amount description - Free shipping
Instructions
  • Always show values clearly, such as shipping taxes and installment number, preventing surprises
  • When dealing with different currencies, pay attention to how you present the difference between then. Also, if possible present exchange rate ("Tipo de Cambio") to the customer.
Last updated on by “ElderBalsani