Card Payment behavior customizations
MercadoPago.js V2 offers additional resources for the Card Payment Brick integration for card payments on websites. In this section, you will see how to restrict the accepted payment methods, limit the installment range, initialize the form with data already known about the buyer, and access complementary card information. See below how to configure these resources.
If your operation does not accept certain card types, or works with a specific installment range, you can apply these rules directly in the form through the customization.paymentMethods object, defined when rendering the Card Payment.
By default, credit and debit are accepted. The configuration of the types is done by exclusion, that is, you indicate what you do not accept. Installments, in turn, are restricted to the defined range, and only the options within it are displayed to the buyer.
| Property | Type | Description |
customization.paymentMethods.types.excluded | String | Excluded card types. The accepted values inside the array are: credit_card, debit_card, and prepaid_card. |
customization.paymentMethods.minInstallments | Number | Minimum number of installments displayed to the buyer. |
customization.paymentMethods.maxInstallments | Number | Maximum number of installments displayed to the buyer. |
const settings = {
...,
customization: {
paymentMethods: {
types: {
excluded: ['debit_card'],
},
minInstallments: 1,
maxInstallments: 6,
},
},
};const customization = {
paymentMethods: {
types: {
excluded: ['debit_card'],
},
minInstallments: 1,
maxInstallments: 6,
},
};If the buyer is already authenticated on your site, you can send the data you already know at the moment you render the Card Payment, preventing them from having to fill it in again. This data is provided in the initialization.payer object.
| Property | Type | Description |
initialization.payer.email | String | Buyer's e-mail. When a valid e-mail is sent, the corresponding field is no longer displayed in the form. |
initialization.payer.identification.type | String | Buyer's document type. |
initialization.payer.identification.number | String | Buyer's document number. When sent together with a corresponding identification.type, the document field is filled in automatically. |
const settings = {
initialization: {
amount: 100,
payer: {
email: 'buyer@example.com',
identification: {
type: 'CPF',
number: '12345678909',
},
},
},
...
};const initialization = {
...,
payer: {
...,
email: 'buyer@example.com',
identification: {
type: 'CPF',
number: '12345678909',
},
},
};The onBinChange callback returns the bin of the card being entered. It is called in real time, whenever the bin is updated in the card number field, and allows you to react to the identified card brand before the payment is completed.
const settings = {
...,
callbacks: {
...
onBinChange: (bin) => {
// callback called whenever the card bin changes
console.log(bin);
},
},
};import { CardPayment } from '@mercadopago/sdk-react';
<CardPayment
...,
onBinChange={bin => {
console.log(bin);
}}
/>bin returned by onBinChange corresponds to what the buyer has entered up to that moment, and a new event is triggered with each change to the field. Therefore, consider the bin valid and reliable only after the submit event is triggered by the onSubmit callback.The onSubmit callback receives an optional parameter called additionalData, which gathers information useful for your integration, but which is not required for the payment confirmation in the backend.
additionalData parameter is only returned when the buyer chooses to pay by card.| Field | Type | Description |
bin | String | The bin of the card entered by the buyer. |
lastFourDigits | String | Last four digits of the card. |
cardholderName | String | Name of the cardholder. |
const settings = {
...,
callbacks: {
onSubmit: (formData, additionalData) => {
// callback called after the buyer clicks the data submission button
// the additionalData parameter is optional, you can remove it if you want
console.log(additionalData);
return new Promise((resolve, reject) => {
const submitData = {
type: "online",
total_amount: String(formData.transaction_amount), // must be a string in the 00.00 format
external_reference: "ext_ref_1234", // identifier of the transaction origin.
processing_mode: "automatic",
transactions: {
payments: [
{
amount: String(formData.transaction_amount), // must be a string in the 00.00 format
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) => {
// receive the payment result
resolve();
})
.catch((error) => {
// handle the error response when trying to create the payment
reject();
});
});
},
},
};import { CardPayment } from '@mercadopago/sdk-react';
<CardPayment
initialization={initialization}
customization={customization}
onSubmit={async (formData, additionalData) => {
console.log(formData, additionalData);
}}
/>If you are not using the native form submission button, you can also access the additionalData object through the getAdditionalData method, as in the example below.
Javascript// variable where the Brick controller is stored cardPaymentBrickController.getAdditionalData() .then((additionalData) => { console.log("Additional data:", additionalData); }) .catch((error) => console.error(error));
getAdditionalData method only after the form submission, that is, after calling the getFormData method. This ensures that the returned data is valid and reliable. To learn how to hide the native button and use
getFormData, see the Hide payment button section.