Skip to content

Latest commit

 

History

History
410 lines (323 loc) · 16.5 KB

wallet.md

File metadata and controls

410 lines (323 loc) · 16.5 KB
Raw

BricksBuilder.create(brick, target, settings)

Returns: Promise<BRICK CONTROLLER> See more about Brick Controller

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.


Example of sending the preference on initialization:

When sending the preferenceId on initialization, the callbacks are optional

// HTML/JS
mp.bricks().create("wallet", "walletBrick_container", {
  initialization: {
    preferenceId: "<PREFERENCE_ID>", // preferenceId generated in the backend
  },
});
// React/JSX
const App = () => {
  return (
    <Wallet
      initialization={{
        preferenceId: "PREFERENCE_ID", // preferenceId generated in the backend
      }}
    />
  );
};

Example of sending the preference in callback onSubmit:

When not sending the preferenceId on initialization, the onSubmit callback become mandatory, since the preference is expected to be created on it.

// HTML/JS
mp.bricks().create("wallet", "walletBrick_container", {
  callbacks: {
    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((resp) => resp.json())
          .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();
          });
      });
    },
  },
});
// React/JSX
const App = () => {
  return (
    <Wallet
      initialization={{ redirectMode: "self" }}
      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((resp) => resp.json())
            .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();
            });
        });
      }}
    />
  );
};

Parameters

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 REQUIRED¹
callbacks object Defines the callback functions. See more REQUIRED²
customization object Defines custom properties. See more OPTIONAL
locale string Defines locale. OPTIONAL

¹ Required when integrating through the flow that sends the preference on initialization

² Required when integrating through the flow that creates the preference on submit


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³
redirectMode string Indicates how the experience will be conducted. See more REQUIRED
marketplace boolean Indicates if the integration is for a marketplace flow. OPTIONAL

³ Optional when integrating through the flow that creates the preference on submit


Callbacks

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

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

⁴ Required when integrating through the flow that creates the preference on submit


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 call to action text. Options available: pay, buy. Default is pay. OPTIONAL
texts.actionComplement¹ string Defines the action complement. Options available: brand, amount. Default is brand. OPTIONAL
texts.valueProp¹ string Defines the value prop. Options available: practicality, convenience_all, security_details, security_safety, convenience_credits, smart_option and payment_methods_logos. 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

¹ For more information, see the Change texts page.

Value prop availability

Country Value prop availability
🇦🇷 Argentina practicality, convenience_all, security_details, security_safety, convenience_credits, smart_option, payment_methods_logos
🇧🇷 Brazil practicality, convenience_all, security_details, security_safety, convenience_credits, smart_option, payment_methods_logos
🇲🇽 Mexico practicality, convenience_all, security_details, security_safety, convenience_credits, smart_option, payment_methods_logos
🇨🇴 Colombia practicality, security_details, security_safety, smart_option,payment_methods_logos
🇺🇾 Uruguay practicality, security_details, security_safety, smart_option, payment_methods_logos
🇨🇱 Chile practicality, security_details, security_safety, smart_option, payment_methods_logos
🇵🇪 Peru practicality, security_details, security_safety, smart_option, payment_methods_logos

Caution

Important notice about payment_methods_logos
When using the value prop payment_methods_logos, it is recommended to initialize Wallet Brick with a preference.
If the preference has zero or only one valid payment method, Wallet Brick will stop displaying the payment methods logos and will show a fallback text according to the country.
See the table below to know each fallback text.

Country Fallback text
🇦🇷 Argentina Account money or installments with no card
🇧🇷 Brazil Account money or installments with no card
🇲🇽 Mexico Account money or installments with no card
🇨🇴 Colombia With account money
🇺🇾 Uruguay With account money
🇨🇱 Chile With account money
🇵🇪 Peru With account money

Opening scheme

There are three ways to open the checkout experience: redirect on the same tab, which is the default, or redirecting to a new tab.

Parameter value Description
redirectMode self Keeps the redirect on the same page
redirectMode blank Makes the redirect to a new page
HTML/JS example 
mp.bricks().create("wallet", "walletBrick_container", {
  initialization: {
    preferenceId: "<PREFERENCE_ID>", // preferenceId generated in the backend
    redirectMode: "blank", // default value is 'self'
  },
});
ReactJS example 
const App = () => {
  return (
    <Wallet
      initialization={{
        preferenceId: "PREFERENCE_ID", // preferenceId generated in the backend
        redirectMode: "blank", // default value is 'self'
      }}
    />
  );
};

BrickError example

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

The ErrorCauses

{
  ("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");
}

Colors style

Wallet Brick allows you to personalize the color style of its interface elements, customizing the way it will be displayed to the user.

  • Only applicable to Mercado Pago Wallet payment method
  • Exclusive for the modal opening scheme
  • Color attributes must be in hexadecimal format
HTML/JS example 
mp.bricks().create("wallet", "walletBrick_container", {
  initialization: {
    preferenceId: "<PREFERENCE_ID>",
    redirectMode: "blank",
  },
  customization: {
    checkout: {
      theme: {
        elementsColor: "#4287F5",
        headerColor: "#4287F5",
      },
    },
  },
});
ReactJS example 
<Wallet
  initialization={{ preferenceId: '<PREFERENCE_ID>', redirectMode: 'blank' }}
  customization={{
    checkout: {
      theme: {
        elementsColor: '#4287F5',
        headerColor: '#4287F5'
      },
    },
 }}
/>

Brick Controller

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

Brick Controller.unmount()

The unmount method removes the rendered Brick from the page.

Params

None.

Returns

void

Unmount example 
const controller = await mercadopago
  .bricks()
  .create("wallet", "<DOM_CONTAINER>", {
    initialization: {
      preferenceId: "<PREFERENCE_ID>",
    },
  });

// Somewhere in your flow
controller.unmount();

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.