Version: current

UX Recommendations for Colombia

About this guide

This page will present some resources to help you to provide a better user experience for your customers in Colombia. 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

Field Name and Parameter	Field and placeholder translation	Note
Full Name payment.name	Nombre y Apellido
Email payment.email	Correo Electrónico
Phone number payment.phone_number	Teléfono Fijo o Celular
Document payment.document	Número del Documento

Credit and Debit Information

Field Name and Parameter	Field and placeholder translation	Note
Cardholder Name payment.creditcard.card_name	Nombre del titular Como en la tarjeta
Card Number payment.creditcard.card_number	Número de la tarjeta		"
Expiration Date payment.creditcard.card_due_date	Fecha de expiración MM/AAAA
CVV payment.creditcard.card_cvv	Código de seguridad (CVV)
Installments payment.instalments	Cuotas	Installments are only available for credit card payments. Know More

Billing Address Information

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

Field Name and Parameter	Field and placeholder translation	Note
Zipcode payment.zipcode	Código postal
Country payment.country	País Seleccione tu País
State payment.state	Departamento
City payment.city	Ciudad
Address payment.address	Dirección
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 Colombia.

Personal information

Field Name and Parameter	Validation Method and Mask	Error 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 es requerido Invalid format: Este correo electrónico parece estar incorrecto
Phone Number payment.phone_number	10 digits, numeric only	Empty field: Este campo es requerido Invalid format: Este teléfono parece estar incorrecto
Document payment.document	NIT (Número de Identificación Tributaria): Length of 9 to 10 digits. Regex: `!/^\d{9,15}$/` CC (Cédula de Ciudadanía): Length of 5 to 15 digits. CE (Cédula de Extranjería):Length of 1 to 6 digits.	Empty field: Este campo es requerido Invalid format: Este documento parece estar incorrecto

Credit card information

Field Name and Parameter	Validation Method and Mask	Error Messages
Credit card number payment.creditcard.card_number	Masks: - AMEX: `9999 9999 9999 99999` - Other Brands: `9999 9999 9999 9999` Regular Expression: Click here	Empty field: Este campo es requerido Invalid format: Esta tarjeta parece estar incorrecta
Expiration Date payment.creditcard.card_due_date	Mask: `99/9999` REGEX: `^(0[1-9]\|1[0-2])\/([0-9]{4})$`	Empty field: Este campo es requerido Invalid format: Esta fecha parece estar incorrecta
CVV payment.creditcard.card_cvv	AMEX: 4 digits, numeric only Other Brands: 3 digits, numeric only	Empty field: Este campo es requerido Invalid format: El código parece estar incompleto

Billing address information

Field Name and Parameter	Validation Method and Mask	Error messages
Zip Code payment.zipcode	6 digits, numeric only REGEX:`[0-9]{6}`	Empty field: Este campo es requerido Invalid format: Este código postal parece estar incorrecto
State payment.state	Amazonas Antioquia Arauca Atlántico Bolívar Boyacá Caldas Caquetá Casanare Cauca Cesar Chocó Cundinamarca Córdoba Distrito Capital de Bogotá Guainía Guaviare Huila La Guajira Magdalena Meta Nariño Norte de Santander Putumayo Quindío Risaralda San Andrés, Providencia y Santa Catalina Santander Sucre Tolima Valle del Cauca Vaupés Vichada	Empty field: Este campo es requerido Invalid format: Este estado parece estar incorrecto

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 = /^[0-9]{5}[0-9]{5}$/;
  return re.test(String(phoneNumber));
}

zipcode_validation.js

function validateZipcode(zipcode) {
  const re = /[0-9]{6}/;
  return re.test(String(zipcode));
}

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

Informaciones personales

Todas las informaciones abajo son requeridas.

Nombre y Apellido

Correo Electrónico

Teléfono

Live code editor

function UXMX(props) {
  const [phoneError, setPhoneError] = React.useState(false);
  const [emailError, setEmailError] = React.useState(false);

  function validatePhoneNumber(e) {
    if (/^[0-9]{5}[0-9]{5}$/.test(String(e.target.value)) || !e.target.value) {
      setPhoneError(false);
    } else {
      setPhoneError(true);
    }
  }

  function validateEmail(e) {
    if (
      /^[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])?)*$/.test(
        String(e.target.value)
      ) ||
      !e.target.value
    ) {
      setEmailError(false);
    } else {
      setEmailError(true);
    }
  }

  return (
    <div>
      <Typography variant='h6' gutterBottom>
        Informaciones personales
      </Typography>
      <Typography variant='h7' gutterBottom>
        Todas las informaciones abajo son requeridas.
      </Typography>
      <div>
        <br />
      </div>
      <Grid container xs={12} spacing={3}>
        <Grid item container spacing={3}>
          <Grid item xs={12}>
            <TextField
              required
              variant='outlined'
              id='fullName'
              name='fullName'
              label='Nombre y Apellido'
              fullWidth
              autoComplete='given-name'
            />
          </Grid>
          <Grid item xs={12}>
            <TextField
              required
              variant='outlined'
              id='email'
              name='email'
              label='Correo Electrónico'
              fullWidth
              autoComplete='shipping email'
              onBlur={validateEmail}
              error={emailError}
            />
          </Grid>
          <Grid item xs={12}>
            <TextField
              required
              variant='outlined'
              id='phoneNumber'
              name='phoneNumber'
              label='Teléfono'
              fullWidth
              onBlur={validatePhoneNumber}
              error={phoneError || false}
              autoComplete='shipping phone-number'
            />
          </Grid>
        </Grid>
      </Grid>
    </div>
  );
}

function UXMX(props) {
  const [phoneError, setPhoneError] = React.useState(false);
  const [emailError, setEmailError] = React.useState(false);
  function validatePhoneNumber(e) {
    if (/^[0-9]{5}[0-9]{5}$/.test(String(e.target.value)) || !e.target.value) {
      setPhoneError(false);
    } else {
      setPhoneError(true);
    }
  }
  function validateEmail(e) {
    if (
      /^[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])?)*$/.test(
        String(e.target.value)
      ) ||
      !e.target.value
    ) {
      setEmailError(false);
    } else {
      setEmailError(true);
    }
  }
  return (
    <div>
      <Typography variant='h6' gutterBottom>
        Informaciones personales
      </Typography>
      <Typography variant='h7' gutterBottom>
        Todas las informaciones abajo son requeridas.
      </Typography>
      <div>
        <br />
      </div>
      <Grid container xs={12} spacing={3}>
        <Grid item container spacing={3}>
          <Grid item xs={12}>
            <TextField
              required
              variant='outlined'
              id='fullName'
              name='fullName'
              label='Nombre y Apellido'
              fullWidth
              autoComplete='given-name'
            />
          </Grid>
          <Grid item xs={12}>
            <TextField
              required
              variant='outlined'
              id='email'
              name='email'
              label='Correo Electrónico'
              fullWidth
              autoComplete='shipping email'
              onBlur={validateEmail}
              error={emailError}
            />
          </Grid>
          <Grid item xs={12}>
            <TextField
              required
              variant='outlined'
              id='phoneNumber'
              name='phoneNumber'
              label='Teléfono'
              fullWidth
              onBlur={validatePhoneNumber}
              error={phoneError || false}
              autoComplete='shipping phone-number'
            />
          </Grid>
        </Grid>
      </Grid>
    </div>
  );
}

Instructions

These fields are required for any payment method in Colombia;
If the customer provided this information in previous steps, you can reuse it to reduce friction. :::

Card information

Preview

Datos de la tarjeta

Todas las informaciones abajo son requeridas.

Nombre del titular

Número de la tarjeta

Fecha de Expiración

Código de Seguridad (CVV)

Cuotas

¿En cuántas cuotas deseas pagar?

Información de Cobro

Todas las informaciones abajo son requeridas, excepto "Informaciones Adicionales"

Código Postal

Estado

Ciudad

Dirección

Número

Informaciones Adicionales

Opcional

Live code editor

function UXMX(props) {
  const [cardNumberError, setCardNumberError] = React.useState(false);

  function validateCardNumber(e) {
    if (
      /^[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])?)*$/.test(
        String(e.target.value)
      ) ||
      !e.target.value
    ) {
      setCardNumberError(false);
    } else {
      setCardNumberError(true);
    }
  }

  const amount = 5000000;
  const installments_max = 36;
  const local_currency = 'COP';
  const installments_options = [];
  installments_options.push(
    <option value='1'>
      1 mes de {local_currency}$ {amount}
    </option>
  );
  for (let i = 2; i <= installments_max; i++) {
    installments_options.push(
      <option value='1'>
        {i} meses de {local_currency}$ {(amount / i).toFixed(2)}
      </option>
    );
  }

  return (
    <div>
      <Typography variant='h6' gutterBottom>
        Datos de la tarjeta
      </Typography>
      <Typography variant='h7' gutterBottom>
        Todas las informaciones abajo son requeridas.
      </Typography>
      <div>
        <br />
      </div>
      <Grid container xs={12} spacing={3}>
        <Grid item container spacing={3}>
          <Grid item xs={12}>
            <TextField
              required
              variant='outlined'
              id='cardHolder'
              name='cardHolder'
              label='Nombre del titular'
              placeholder='Como en la tarjeta'
              fullWidth
            />
          </Grid>
          <Grid item xs={12}>
            <InputMask
              mask='9999 9999 9999 99999'
              disabled={false}
              maskChar=' '
              onBlur={validateCardNumber}
            >
              {() => (
                <TextField
                  required
                  variant='outlined'
                  id='cardNumber'
                  name='cardNumber'
                  type='text'
                  label='Número de la tarjeta'
                  fullWidth
                  placeholder='1111 1111 1111 1111'
                  error={cardNumberError}
                />
              )}
            </InputMask>
          </Grid>
          <Grid item xs={12} sm={6}>
            <InputMask mask='99/9999' disabled={false} maskChar=' '>
              {() => (
                <TextField
                  required
                  variant='outlined'
                  id='dueDate'
                  name='dueDate'
                  label='Fecha de Expiración'
                  fullWidth
                  placeholder='MM/AAAA'
                />
              )}
            </InputMask>
          </Grid>
          <Grid item xs={12} sm={6}>
            <TextField
              required
              id='cvv'
              name='cvv'
              label='Código de Seguridad (CVV)'
              variant='outlined'
              inputProps={{ maxLength: 4 }}
              fullWidth
            />
          </Grid>
          <Grid item xs={12}>
            <TextField
              id='installments'
              select
              label='Cuotas'
              fullWidth
              SelectProps={{
                native: true,
              }}
              helperText='¿En cuántas cuotas deseas pagar?'
              variant='outlined'
            >
              {installments_options}
            </TextField>
          </Grid>
        </Grid>
      </Grid>
      <div>
        <br />
      </div>
      <Typography variant='h6' gutterBottom>
        Información de Cobro
      </Typography>
      <Typography variant='h7' gutterBottom>
        Todas las informaciones abajo son requeridas, excepto "Informaciones
        Adicionales"
      </Typography>
      <div>
        <br />
      </div>
      <Grid container xs={12} spacing={3}>
        <Grid item container spacing={3}>
          <Grid item xs={12}>
            <TextField
              required
              variant='outlined'
              id='postalCode'
              name='postalCode'
              label='Código Postal'
              fullWidth
            />
          </Grid>
          <Grid item xs={12} sm={6}>
            <TextField
              required
              id='state'
              name='state'
              label='Estado'
              variant='outlined'
              fullWidth
            />
          </Grid>
          <Grid item xs={12} sm={6}>
            <TextField
              required
              id='city'
              name='city'
              label='Ciudad'
              variant='outlined'
              fullWidth
            />
          </Grid>
          <Grid item xs={12}>
            <TextField
              required
              variant='outlined'
              id='address'
              name='address'
              label='Dirección'
              placeholder='Calle, Avenida o Otro'
              fullWidth
            />
          </Grid>
          <Grid item xs={12} sm={6}>
            <TextField
              required
              id='streetNumber'
              name='streetNumber'
              label='Número'
              variant='outlined'
              fullWidth
            />
          </Grid>
          <Grid item xs={12} sm={6}>
            <TextField
              id='additionalInfo'
              name='additionalInfo'
              label='Informaciones Adicionales'
              variant='outlined'
              fullWidth
              helperText='Opcional'
            />
          </Grid>
        </Grid>
      </Grid>
    </div>
  );
}

function UXMX(props) {
  const [cardNumberError, setCardNumberError] = React.useState(false);
  function validateCardNumber(e) {
    if (
      /^[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])?)*$/.test(
        String(e.target.value)
      ) ||
      !e.target.value
    ) {
      setCardNumberError(false);
    } else {
      setCardNumberError(true);
    }
  }
  const amount = 5000000;
  const installments_max = 36;
  const local_currency = 'COP';
  const installments_options = [];
  installments_options.push(
    <option value='1'>
      1 mes de {local_currency}$ {amount}
    </option>
  );
  for (let i = 2; i <= installments_max; i++) {
    installments_options.push(
      <option value='1'>
        {i} meses de {local_currency}$ {(amount / i).toFixed(2)}
      </option>
    );
  }
  return (
    <div>
      <Typography variant='h6' gutterBottom>
        Datos de la tarjeta
      </Typography>
      <Typography variant='h7' gutterBottom>
        Todas las informaciones abajo son requeridas.
      </Typography>
      <div>
        <br />
      </div>
      <Grid container xs={12} spacing={3}>
        <Grid item container spacing={3}>
          <Grid item xs={12}>
            <TextField
              required
              variant='outlined'
              id='cardHolder'
              name='cardHolder'
              label='Nombre del titular'
              placeholder='Como en la tarjeta'
              fullWidth
            />
          </Grid>
          <Grid item xs={12}>
            <InputMask
              mask='9999 9999 9999 99999'
              disabled={false}
              maskChar=' '
              onBlur={validateCardNumber}
            >
              {() => (
                <TextField
                  required
                  variant='outlined'
                  id='cardNumber'
                  name='cardNumber'
                  type='text'
                  label='Número de la tarjeta'
                  fullWidth
                  placeholder='1111 1111 1111 1111'
                  error={cardNumberError}
                />
              )}
            </InputMask>
          </Grid>
          <Grid item xs={12} sm={6}>
            <InputMask mask='99/9999' disabled={false} maskChar=' '>
              {() => (
                <TextField
                  required
                  variant='outlined'
                  id='dueDate'
                  name='dueDate'
                  label='Fecha de Expiración'
                  fullWidth
                  placeholder='MM/AAAA'
                />
              )}
            </InputMask>
          </Grid>
          <Grid item xs={12} sm={6}>
            <TextField
              required
              id='cvv'
              name='cvv'
              label='Código de Seguridad (CVV)'
              variant='outlined'
              inputProps={{ maxLength: 4 }}
              fullWidth
            />
          </Grid>
          <Grid item xs={12}>
            <TextField
              id='installments'
              select
              label='Cuotas'
              fullWidth
              SelectProps={{
                native: true,
              }}
              helperText='¿En cuántas cuotas deseas pagar?'
              variant='outlined'
            >
              {installments_options}
            </TextField>
          </Grid>
        </Grid>
      </Grid>
      <div>
        <br />
      </div>
      <Typography variant='h6' gutterBottom>
        Información de Cobro
      </Typography>
      <Typography variant='h7' gutterBottom>
        Todas las informaciones abajo son requeridas, excepto "Informaciones
        Adicionales"
      </Typography>
      <div>
        <br />
      </div>
      <Grid container xs={12} spacing={3}>
        <Grid item container spacing={3}>
          <Grid item xs={12}>
            <TextField
              required
              variant='outlined'
              id='postalCode'
              name='postalCode'
              label='Código Postal'
              fullWidth
            />
          </Grid>
          <Grid item xs={12} sm={6}>
            <TextField
              required
              id='state'
              name='state'
              label='Estado'
              variant='outlined'
              fullWidth
            />
          </Grid>
          <Grid item xs={12} sm={6}>
            <TextField
              required
              id='city'
              name='city'
              label='Ciudad'
              variant='outlined'
              fullWidth
            />
          </Grid>
          <Grid item xs={12}>
            <TextField
              required
              variant='outlined'
              id='address'
              name='address'
              label='Dirección'
              placeholder='Calle, Avenida o Otro'
              fullWidth
            />
          </Grid>
          <Grid item xs={12} sm={6}>
            <TextField
              required
              id='streetNumber'
              name='streetNumber'
              label='Número'
              variant='outlined'
              fullWidth
            />
          </Grid>
          <Grid item xs={12} sm={6}>
            <TextField
              id='additionalInfo'
              name='additionalInfo'
              label='Informaciones Adicionales'
              variant='outlined'
              fullWidth
              helperText='Opcional'
            />
          </Grid>
        </Grid>
      </Grid>
    </div>
  );
}

Be careful to show installment (Cuotas) 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 situado en el reverso de la tarjeta. En las tarjetas AMEX, el código es de 4 números se sitúa en la frente de la tarjeta" :::

Payment method selection

Instructions

Present all payment methods clearly
Load the list of payment methods with the first option already selected by default
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

Credit card

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 (Cuotas), it can be interesting to show it together with the total amount (Check Total Order Amount) :::

PSE - Pagos Seguros en Línea selection

PSE

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. :::

Efecty selection

Efecty

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. :::

NEQUI selection

NEQUI

Instructions

Ask the customer to provide the cell phone as her/his NEQUI account. This way, the experience will be smoother for the customer.
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

Regular	Free shipping

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. :::

About this guide#

Mandatory fields#

Personal information#

Credit and Debit Information#

Billing Address Information#

Validation#

Personal information#

Credit card information#

Billing address information#

Validation snippets#

Checkout recommendations#

Personal information#

Informaciones personales

Instructions

Card information#

Datos de la tarjeta

Información de Cobro

Payment method selection#

Instructions

Credit card selection#

PSE - Pagos Seguros en Línea selection#

Instructions

Efecty selection#

NEQUI selection#

Instructions

Total order amount#

About this guide

Mandatory fields

Personal information

Credit and Debit Information

Billing Address Information

Validation

Personal information

Credit card information

Billing address information

Validation snippets

Checkout recommendations

Personal information

Card information

Payment method selection

Credit card selection

PSE - Pagos Seguros en Línea selection

Efecty selection

NEQUI selection

Total order amount