wallet.md

ATTENTION: Wallet Brick has two ways of integration, one is sending the preference on initialization, and the other is sending the preference at the moment of submit (callback onSubmit). You must choose only one way of integration.

BricksBuilder.create(brick, target, settings)

Returns: Promise<BRICK CONTROLLER>

See more about Brick Controller

Example of sending the preference on initialization:

mp.bricks().create("wallet", "walletBrick_container", {
  initialization: {
    preferenceId: "<PREFERENCE_ID>", // preferenceId generated in the backend
  },
  callbacks: {
    onReady: () => {
      // Callback called when the brick is ready.
      // Here you can hide loadings from your site, for example.
    },
    onSubmit: () => {
      // Callback called when clicking on Wallet Brick.
      // This is possible because the brick is a button.
    },
    onError: (error) => {
      // Callback called for all brick error cases
      console.error(error);
    },
  },
});

Example of sending the preference in callback onSubmit:

mp.bricks().create("wallet", "walletBrick_container", {
  callbacks: {
    onReady: () => {
      // Callback called when the brick is ready.
      // Here you can hide loadings from your site, for example.
    },
    onSubmit: () => {
      // Callback called when clicking Wallet Brick.
      // This is possible because the brick is a button.
      // At this time of submit, you must create the preference.
      const yourRequestBodyHere = {
        items: [
          id: "202809963",
          title: "Dummy title",
          description: "Dummy description",
          quantity: 1,
          unit_price: 10,
        ],
        purpose: "wallet_purchase"
      };

      return new Promise((resolve, reject) => {
        fetch("/create_preference", {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
          },
          body: JSON.stringify(yourRequestBodyHere)
        })
        .then((response) => {
          // Resolve the promise with the Preference ID
          resolve(response.preference_id);
        })
        .catch((error) => {
          // Handle error response when trying to create the preference
          reject();
        })
      });
    },
    onError: (error) => {
      // Callback called for all brick error cases
      console.error(error);
    },
  },
});

Params:

brick | string, REQUIRED

Selected Brick. Possible values are: wallet.

target | string, REQUIRED

Id of the container that the brick will be rendered in. Can be any HTML element.

settings | object, REQUIRED

The settings object has properties to initialize and customize the brick being created.

Setting key	Type	Description
initialization	object	Defines the initialization data. See more	Only required if you chose to integrate through the flow that sends the preference on initialization
callbacks	object	Defines the callback functions. See more	REQUIRED
customization	object	Defines custom properties. See more	OPTIONAL
locale	string	Defines locale.	OPTIONAL

Initialization

Initialization is an object with the properties the brick will initialize with.

Initialization key	Type	Description
preferenceId	string	Preference generated in the backend	OPTIONAL

Callbacks

The callbacks object contains the callbacks functions the brick will call during its life cycle.

Callback key	Description		Params	Returns
onReady	It is called when the brick finishes loading	REQUIRED	void	void
onError	It is called when there is an error in the brick	REQUIRED	BrickError	void
onSubmit	It is called when the user clicks on the brick	OPTIONAL	void	Promise<void>

BrickError

{
  type: "non_critical" | "critical";
  message: string;
  cause: ErrorCause;
}

ErrorCause

{
  'already_initialized'
  'container_not_found'
  'get_preference_details_failed'
  'incorrect_initialization'
  'invalid_sdk_instance'
  'missing_container_id'
  'missing_locale_property'
  'missing_required_callbacks'
  'missing_texts'
  'no_preference_provided'
  'settings_empty'
}

Customization

Customizations object is used to load Brick under different conditions.

Customization key	Type	Description
texts	object	Controls the texts of the brick.	OPTIONAL
texts.action	string	Defines the the call to action text. Options available: pay, buy. Default is pay.	OPTIONAL
texts.valueProp	string	Defines the value prop. Options available: practicality, convenience, security_details, security_safety. Default is security_safety.	OPTIONAL
visual	object	Controls visual aspects of the brick.	OPTIONAL
visual.buttonBackground	string	Defines the brick background color. Available options: default, black, blue, white. Default is default.	OPTIONAL
visual.buttonHeight	string	Defines the brick height. Default is 48px. Min: 48px. Max: free choice.	OPTIONAL
visual.borderRadius	string	Defines the brick border radius. Default is 6px.	OPTIONAL
visual.valuePropColor	string	Defines the value prop color. Available options: grey, white. Default is grey.	OPTIONAL
visual.verticalPadding	string	Defines the brick vertical padding. Default is 16px. Min: 8px. Max: free choice.	OPTIONAL
visual.horizontalPadding	string	Defines the brick horizontal padding. Default is 0px. Min: 0px. Max: free choice.	OPTIONAL
visual.hideValueProp	boolean	Hides the value prop text. Default is false.	OPTIONAL

Brick Controller

The Brick Controller contains methods that allow the integrator to interact with the rendered Brick.

unmount	METHOD

Brick Controller.unmount()

The unmount methods removes the rendered Brick from the page.

Params

None.

Returns

void

A note about the purpose of the preference

When creating the preference in the backend, you can (optionally) configure a field called purpose, which can be wallet_purchase or onboarding_credits, learn more about the differences between them:

• wallet_purchase: users must log in when redirected to their Mercado Pago account.
• onboarding_credits: after logging in, the user will see the pre-selected credit payment option in his Mercado Pago account.