Recursos para IA

Personalização de comportamento do Card Payment

O MercadoPago.js V2 oferece recursos adicionais para a integração do Card Payment Brick para pagamentos com cartão em websites. Nesta seção, você verá como restringir os meios de pagamento aceitos, limitar o intervalo de parcelas, iniciar o formulário com dados já conhecidos do comprador e acessar informações complementares do cartão. Veja abaixo como configurar esses recursos.

Restringir meios de pagamento e limitar parcelas

Caso a sua operação não aceite determinados tipos de cartão, ou trabalhe com uma faixa específica de parcelamento, é possível aplicar essas regras diretamente no formulário através do objeto customization.paymentMethods, definido ao renderizar o Card Payment.

Por padrão, crédito e débito são aceitos. A configuração dos tipos é feita por exclusão, ou seja, você informa o que não aceita. Já as parcelas são restringidas ao intervalo definido, e apenas as opções dentro dele são exibidas ao comprador.

Propriedade	Tipo	Descrição
`customization.paymentMethods.types.excluded`	String	Tipos de cartão excluídos. Os valores aceitos dentro do array são: `credit_card`, `debit_card` e `prepaid_card`.
`customization.paymentMethods.minInstallments`	Number	Número mínimo de parcelas exibidas ao comprador.
`customization.paymentMethods.maxInstallments`	Number	Número máximo de parcelas exibidas ao 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 o formulário com dados do comprador

Se o comprador já estiver autenticado no seu site, você pode enviar os dados que já conhece no momento em que renderiza o Card Payment, evitando que ele precise preenchê-los novamente. Esses dados são informados no objeto initialization.payer.

Propriedade	Tipo	Descrição
`initialization.payer.email`	String	E-mail do comprador. Quando um e-mail válido é enviado, o campo correspondente deixa de ser exibido no formulário.
`initialization.payer.identification.type`	String	Tipo de documento do comprador.
`initialization.payer.identification.number`	String	Número do documento do comprador. Quando enviado junto de um `identification.type` correspondente, o campo de documento é preenchido automaticamente.

const settings = {
  initialization: {
    amount: 100,
    payer: {
      email: 'comprador@exemplo.com',
      identification: {
        type: 'CPF',
        number: '12345678909',
      },
    },
  },
  ...
};

const initialization = {
  ...,
  payer: {
    ...,
    email: 'comprador@exemplo.com',
    identification: {
      type: 'CPF',
      number: '12345678909',
    },
  },
};

Obter o bin do cartão

O callback onBinChange devolve o bin do cartão que está sendo digitado. Ele é chamado em tempo real, sempre que o bin é atualizado no campo de número do cartão, e permite reagir à bandeira identificada antes da conclusão do pagamento.

const settings = {
  ...,
  callbacks: {
    ...
    onBinChange: (bin) => {
      // callback chamado sempre que o bin do cartão é alterado
      console.log(bin);
    },
  },
};

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

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

O bin devolvido por onBinChange corresponde ao que o comprador digitou até aquele momento, e um novo evento é disparado a cada alteração do campo. Portanto, considere o bin válido e confiável apenas depois que o evento de envio for disparado pelo callback onSubmit.

Acessar dados adicionais do formulário

O callback onSubmit recebe um parâmetro de uso opcional chamado additionalData, que reúne informações úteis para a sua integração, mas que não são necessárias para a confirmação do pagamento no backend.

O parâmetro additionalData só é devolvido quando o comprador opta por pagar com cartão.

Campo	Tipo	Descrição
`bin`	String	O `bin` do cartão inserido pelo comprador.
`lastFourDigits`	String	Últimos quatro dígitos do cartão.
`cardholderName`	String	Nome da pessoa titular do cartão.

const settings = {
  ...,
  callbacks: {
    onSubmit: (formData, additionalData) => {
      // callback chamado após o comprador clicar no botão de envio dos dados
      // o parâmetro additionalData é opcional, você pode removê-lo se quiser
      console.log(additionalData);
      return new Promise((resolve, reject) => {
        const submitData = {
          type: "online",
          total_amount: String(formData.transaction_amount), // deve ser uma string com formato 00.00
          external_reference: "ext_ref_1234", // identificador da origem da transação.
          processing_mode: "automatic",
          transactions: {
            payments: [
              {
                amount: String(formData.transaction_amount), // deve ser uma string com 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) => {
            // receber o resultado do pagamento
            resolve();
          })
          .catch((error) => {
            // lidar com a resposta de erro ao tentar criar o pagamento
            reject();
          });
      });
    },
  },
};

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

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

Caso não esteja utilizando o botão nativo de envio do formulário, você também pode acessar o objeto additionalData através do método getAdditionalData, como no exemplo a seguir.

Javascript
// variável onde o controller do Brick está salvo
cardPaymentBrickController.getAdditionalData()
    .then((additionalData) => {
        console.log("Additional data:", additionalData);
    })
    .catch((error) => console.error(error));

Chame o método getAdditionalData somente após o envio do formulário, ou seja, depois de chamar o método getFormData. Com isso, é garantido que os dados devolvidos são válidos e confiáveis.
Para saber como ocultar o botão nativo e usar getFormData, consulte a seção Ocultar botão de pagamento.

AnteriorCustomizações visuais do Card PaymentVeja quais são as possíveis customizações visuais para o seu checkout web integrado com Card Payment Brick.

PróximoCustomizações visuais do Card PaymentVeja quais são as possíveis customizações visuais para o seu checkout mobile integrado com Card Payment Brick.