Recursos para IA

Personalización de comportamiento del Card Payment

MercadoPago.js V2 ofrece recursos adicionales para la integración del Card Payment Brick para pagos con tarjeta en sitios web. En esta sección, verás cómo restringir los medios de pago aceptados, limitar el intervalo de cuotas, iniciar el formulario con datos ya conocidos del comprador y acceder a información complementaria de la tarjeta. Consulta a continuación cómo configurar estos recursos.

Restringir medios de pago y limitar cuotas

Si tu operación no acepta determinados tipos de tarjeta, o trabaja con un rango específico de cuotas, es posible aplicar estas reglas directamente en el formulario a través del objeto customization.paymentMethods, definido al renderizar el Card Payment.

Por defecto, se aceptan crédito y débito. La configuración de los tipos se realiza por exclusión, es decir, indicas lo que no aceptas. Las cuotas, por su parte, se restringen al intervalo definido, y solo se muestran al comprador las opciones dentro de él.

Propiedad	Tipo	Descripción
`customization.paymentMethods.types.excluded`	String	Tipos de tarjeta excluidos. Los valores aceptados dentro del array son: `credit_card`, `debit_card` y `prepaid_card`.
`customization.paymentMethods.minInstallments`	Number	Número mínimo de cuotas mostradas al comprador.
`customization.paymentMethods.maxInstallments`	Number	Número máximo de cuotas mostradas al comprador.

const settings = {
  ...,
  customization: {
    paymentMethods: {
      types: {
        excluded: ['debit_card'],
      },
      minInstallments: 1,
      maxInstallments: 6,
    },
  },
};

const customization = {
  paymentMethods: {
    types: {
      excluded: ['debit_card'],
    },
    minInstallments: 1,
    maxInstallments: 6,
  },
};

Inicializar el formulario con datos del comprador

Si el comprador ya está autenticado en tu sitio, puedes enviar los datos que ya conoces en el momento en que renderizas el Card Payment, evitando que tenga que completarlos nuevamente. Estos datos se informan en el objeto initialization.payer.

Propiedad	Tipo	Descripción
`initialization.payer.email`	String	E-mail del comprador. Cuando se envía un e-mail válido, el campo correspondiente deja de mostrarse en el formulario.
`initialization.payer.identification.type`	String	Tipo de documento del comprador.
`initialization.payer.identification.number`	String	Número de documento del comprador. Cuando se envía junto con un `identification.type` correspondiente, el campo de documento se completa automáticamente.

const settings = {
  initialization: {
    amount: 100,
    payer: {
      email: 'comprador@ejemplo.com',
      identification: {
        type: 'DNI',
        number: '12345678',
      },
    },
  },
  ...
};

const initialization = {
  ...,
  payer: {
    ...,
    email: 'comprador@ejemplo.com',
    identification: {
      type: 'DNI',
      number: '12345678',
    },
  },
};

Obtener el bin de la tarjeta

El callback onBinChange devuelve el bin de la tarjeta que se está ingresando. Se llama en tiempo real, siempre que el bin se actualiza en el campo de número de la tarjeta, y permite reaccionar a la marca identificada antes de la conclusión del pago.

const settings = {
  ...,
  callbacks: {
    ...
    onBinChange: (bin) => {
      // callback llamado siempre que el bin de la tarjeta cambia
      console.log(bin);
    },
  },
};

import { CardPayment } from '@mercadopago/sdk-react';

<CardPayment
  ...,
  onBinChange={bin => {
    console.log(bin);
  }}
/>

El bin devuelto por onBinChange corresponde a lo que el comprador ingresó hasta ese momento, y se dispara un nuevo evento con cada modificación del campo. Por lo tanto, considera el bin válido y confiable solo después de que el evento de envío sea disparado por el callback onSubmit.

Acceder a datos adicionales del formulario

El callback onSubmit recibe un parámetro de uso opcional llamado additionalData, que reúne información útil para tu integración, pero que no es necesaria para la confirmación del pago en el backend.

El parámetro additionalData solo se devuelve cuando el comprador opta por pagar con tarjeta.

Campo	Tipo	Descripción
`bin`	String	El `bin` de la tarjeta ingresada por el comprador.
`lastFourDigits`	String	Últimos cuatro dígitos de la tarjeta.
`cardholderName`	String	Nombre de la persona titular de la tarjeta.

const settings = {
  ...,
  callbacks: {
    onSubmit: (formData, additionalData) => {
      // callback llamado después de que el comprador hace clic en el botón de envío de datos
      // el parámetro additionalData es opcional, puedes removerlo si quieres
      console.log(additionalData);
      return new Promise((resolve, reject) => {
        const submitData = {
          type: "online",
          total_amount: String(formData.transaction_amount), // debe ser un string con formato 00.00
          external_reference: "ext_ref_1234", // identificador del origen de la transacción.
          processing_mode: "automatic",
          transactions: {
            payments: [
              {
                amount: String(formData.transaction_amount), // debe ser un string con formato 00.00
                payment_method: {
                  id: formData.payment_method_id,
                  type: additionalData.paymentTypeId,
                  token: formData.token,
                  installments: formData.installments,
                },
              },
            ],
          },
          payer: {
            email: formData.payer.email,
            identification: formData.payer.identification,
          },
        };

        fetch("/process_order", {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
          },
          body: JSON.stringify(submitData),
        })
          .then((response) => response.json())
          .then((response) => {
            // recibir el resultado del pago
            resolve();
          })
          .catch((error) => {
            // gestionar la respuesta de error al intentar crear el pago
            reject();
          });
      });
    },
  },
};

import { CardPayment } from '@mercadopago/sdk-react';

<CardPayment
  initialization={initialization}
  customization={customization}
  onSubmit={async (formData, additionalData) => {
    console.log(formData, additionalData);
  }}
/>

Si no estás utilizando el botón nativo de envío del formulario, también puedes acceder al objeto additionalData a través del método getAdditionalData, como en el ejemplo a continuación.

Javascript
// variable donde el controller del Brick está guardado
cardPaymentBrickController.getAdditionalData()
    .then((additionalData) => {
        console.log("Additional data:", additionalData);
    })
    .catch((error) => console.error(error));

Llama al método getAdditionalData solo después del envío del formulario, es decir, después de llamar al método getFormData. Con esto, se garantiza que los datos devueltos son válidos y confiables.
Para saber cómo ocultar el botón nativo y usar getFormData, consulta la sección Ocultar botón de pago.

AnteriorPersonalizaciones visuales del Card PaymentVe cuáles son las posibles personalizaciones visuales para tu checkout web integrado con Card Payment Brick.

PróximoPersonalizaciones visuales del Card PaymentVe cuáles son las posibles personalizaciones visuales para tu checkout móvil integrado con Card Payment Brick.