Possible erros

Below you will find lists of errors that may occur during Brick integration. Whether they are related to sending variables or communication with external services (Mercado Pago APIs).

Variables passed by the integrator

During the Brick integration process, it is possible that when the Brick is instantiated, different errors related to sending variables may be shown to the integrator. These errors will be shown through a log in the browser console (the buyer does not receive any message).

Error	Message	Cause code
Empty configuration object	[Initialization error] Settings object is empty, please pass required properties	settings_empty
Absence of the property amount (total amount of the purchase)	[Initialization error] Amount property is required	missing_amount_property
Absence of the callbacks of onReady and onError	[Initialization error] Callbacks onReady and onError are required	missing_required_callbacks
Absence of an ID of an HTML element that serves as the container of the Brick	[Initialization error] You must provide an HTML element ID as a container to allow component rendering	missing_container_id
Absence of the property locale (preferred language)	[Initialization error] Locale property is required	missing_locale_property
Generic error occurred during Brick initialization, usually some validation that failed due to a value sent by the integrator	[Initialization error] Brick incorrectly initialized: {error}	incorrect_initialization

Communication with external services (Mercado Pago APIs)

Error	Message for the user	Message for the integrator	Critical?	Cause code
Inability to generate Secure Fields within the Card Payment Brick form	An error occurred	The integration with Secure Fields failed	Yes	fields_setup_failed
It wasn’t possible to get the payment method information according to the integrator's public_key	An error occurred. Please try again later.	An error occurred while trying to search for payment methods	No	get_payment_methods_failed
It wasn’t possible to create the token that represents the card information	An error occurred and the payment could not be processed. Please try again later.	Failed to create card token	No	card_token_creation_failed
Error when searching for types of identification documents according to the country defined in the MercadoPago.js SDK	An error occurred. Please try again later.	Failed to get identification types	No	get_identification_types_failed
Failed to get bin based card information	An error occurred. Please try again later.	Failed to get payment methods using card bin	No	get_card_bin_payment_methods_failed
Error searching card issuing banks	An error occurred. Please try again later.	Failed to get card issuer(s)	No	get_card_issuers_failed
Error when searching the amount and the values of the payment installments according to the amount sent by the integrator	An error occurred. Please try again later.	Failed to get payment installments	No	get_payment_installments_failed
Incomplete payment fields for some reason (fees, card issuer, payment_method_id)	An error occurred. Please try again later.	Some of the following messages will be returned according to the type of error: * The payment method id is missing * The payment installments are missing * The card issuer is missing	No	missing_payment_information

How to update data sent during the initialization of a Brick

If it is necessary to update the values sent during the initialization of a Brick, it is necessary to explicitly specify the code's asynchronicity and use the unmount function provided in the Brick's Controller before updating the data. Additionally, the configuration object must be sent in its entirety, as it is related to a rendering process.

It is important to remember that one should not simply call the rendering function with the new values. This would lead to a duplication of the Brick on the screen, and the second rendering would display an error.

The example of code below exemplifies the flow using the update of a preference in the Payment Brick, but the flow itself is valid for necessary updates in the initialization data of any brick.

//First render
const renderPaymentBrick = async (bricksBuilder) => {
      const settings = {
        initialization: {
          amount: 100,
          preferenceId: "<YOUR_FIRST_PREFERENCE_ID>"
        },
...
window.paymentBrickController = await bricksBuilder.create(
   "payment",
   "paymentBrick_container",
   settings
 );

    };

await renderPaymentBrick(bricksBuilder);

//Second render
window.paymentBrickController.unmount()

const secondRenderPaymentBrick = async (bricksBuilder) => {
      const settings = {
        initialization: {
          amount: 100,
          preferenceId: "<YOUR_SECOND_PREFERENCE_ID>"
        },
...
window.paymentBrickController = await bricksBuilder.create(
   "payment",
   "paymentBrick_container",
   settings
 );

    };

await secondRenderPaymentBrick(bricksBuilder);

...

// Brick Container
<div id="paymentBrick_container"></div>

Error "Container Not Found"

For the rendering to occur correctly, it is necessary that the ID of the container in the DOM where the Brick will be rendered is provided identically to the Brick's creation function. Any string can be used as the name, and as long as the names are the same, this error will not occur. Note that classes are not accepted as a container for the Brick, it needs to be an ID.

Another important point is to ensure that when calling the Brick's rendering function, its container is already rendered on the screen. We emphasize this point due to the possibility of the brick's container being inside other containers. This rendering sequence is important to avoid the mentioned error.

Below is a code snippet exemplifying this point using the Payment Brick.

const renderPaymentBrick = async (bricksBuilder) => {
 const settings = { ... };
 window.paymentBrickController = await bricksBuilder.create(
   "payment",
   "paymentBrick_container",
   settings
 );
};

await renderPaymentBrick(bricksBuilder);

...

<div id="paymentBrick_container"></div>

Using Bricks with Next.js

Next.js is a framework for creating interfaces with React components. Therefore, it is possible to use our React SDK to integrate Bricks, as well as other solutions provided through the React SDK.

However, our SDK was structured for client-side rendering while Next.js typically works with Server-Side Rendering (SSR). Thus, when using our SDK, it is necessary to take this into consideration.

You can achieve this integration by dynamically importing the SDK, as indicated in the Next.js documentation. Below you will find an example of dynamically importing a component provided in our SDK, the Payment Brick.


//index.tsx

import Head from "next/head";
import styles from "../styles/Home.module.css";
import dynamic from "next/dynamic";

const CheckoutMercadoPago = dynamic(() => import("./checkoutMercadoPago"), {
  ssr: false,
});

export default function Home() {
  return (
    <>
      <Head>
        <title>Checkout Brick + NextJS</title>
        <meta name="description" content="Generated by create next app" />
      </Head>
      <main className={styles.main}>
        <CheckoutMercadoPago />
      </main>
    </>
  );
}

//checkoutMercadoPago.tsx

import { initMercadoPago, Payment } from "@mercadopago/sdk-react";

initMercadoPago("<YOUR_PUBLIC_KEY>");

const CheckoutMercadoPago = () => {
  const initialization = {
    amount: <YOUR_AMOUNT>,
    preferenceId: "<YOUR_PREFERENCE_ID>"
  };
  const customization = {
    paymentMethods: {
      ticket: "all",
      bankTransfer: "all",
      creditCard: "all",
      debitCard: "all",
      mercadoPago: "all",
    },
  };
  const onSubmit = async ({ selectedPaymentMethod, formData }) => {
   
 // callback called when clicking the submit data button
    return new Promise((resolve, reject) => {
      fetch("/process_payment", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        body: JSON.stringify(formData),
      })
        .then((response) => response.json())
        .then((response) => {
          // receive payment result
          resolve();
        })
        .catch((error) => {
          // handle error response when trying to create payment
          reject();
        });
    });
  };
  const onError = async (error) => {
    // callback called for all Brick error cases
    console.log(error);
  };
  const onReady = async () => {
    /*
     Callback called when Brick is ready.
     Here you can hide loadings from your site, for example.
    */
  };

  return (
    <Payment
      initialization={initialization}
      customization={customization}
      onSubmit={onSubmit}
      onReady={onReady}
      onError={onError}
    />
  );
};
export default CheckoutMercadoPago;

Reembolsos e cancelamentos

Saiba a diferença e como prosseguir para realizar reembolsos e/ou cancelamentos de determinada cobrança.

GitHub project

Tenha acesso aos links do projeto funcional e da documentação técnica.