React SDK MercadoPago

Mercado Pago's Official React SDK.

Table of Contents

• React SDK MercadoPago
• Table of Contents
  • About
  • Prerequisites
  • Installation
  • Initialization
  • Checkout Bricks
    • Card Payment Brick
    • Payment Brick
    • Status Screen Brick
    • Wallet Brick
    • Brand Brick
  • Secure Fields
    • Card Number
    • Security Code
    • Expiration Date
    • Expiration Month
    • Expiration Year
    • createCardToken
    • updateCardToken
  • Fast Payment
    • createAuthenticator
  • Core Methods
    • getIdentificationTypes
    • getPaymentMethods
    • getAccountPaymentMethods
    • getCardId
    • updatePseudotoken
    • getIssuers
    • getInstallments
  • Run SDK project
  • License

About

This is a wrapper that allows integrate Checkout Bricks, Secure Fields and Core Methods, and Fast Payment authentication easily inside React projects.

Prerequisites

Before starts verify if you have installed Node version v16.20.2 or superior.

Installation

First, install SDK MercadoPago React: npm install @mercadopago/sdk-react

Initialization

Start the instance of MercadoPago:

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

initMercadoPago('YOUR_PUBLIC_KEY');

Checkout Bricks

Checkout Bricks are modular checkout components. Below are examples of Brick implementations, for more information check the Examples folder.

Note It's mandatory to have previously done the Initialization step

Card Payment Brick

Use CardPayment component inside your functional React:

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

const App = () => {
  return (
    <CardPayment
      initialization={{ amount: AMOUNT }}
      onSubmit={async (param) => {
        console.log(param);
      }}
    />
  );
};
export default App;

Payment Brick

Use Payment component inside your functional React:

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

const App = () => {
  return (
    <Payment
      initialization={{
        amount: AMOUNT,
        preferenceId: '<YOUR_PREFERENCE_ID>',
      }}
      onSubmit={async (param) => {
        console.log(param);
      }}
    />
  );
};
export default App;

Status Screen Brick

Use StatusScreen component inside your functional React:

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

const App = () => {
  return <StatusScreen initialization={{ paymentId: 'YOUR_PAYMENT_ID' }} />;
};
export default App;

Wallet Brick

Use Wallet component inside your functional React:

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

const App = () => {
  return <Wallet initialization={{ preferenceId: 'YOUR_PREFERENCE_ID' }} />;
};
export default App;

Brand Brick

Use Brand component inside your functional React:

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

const App = () => {
  return <Brand />;
};
export default App;

Secure Fields

Secure Fields are input components that allow you to collect credit and debit card information safely, and allow you to get the PCI SAQ A certification. The Secure Fields module also provides a method to get the card token safely without the need to store the card data.

Note It's mandatory to have previously done the Initialization step

Fast Payment

This feature is disabled by default, to enable, please contact the offical Mercado Pago support via developer's website: www.mercadopago.com/developers

Fast Payment allows users to authenticate using their MercadoPago/MercadoLibre account and quickly access their saved payment methods for streamlined checkout experiences.

Note It's mandatory to have previously done the Initialization step

createAuthenticator

Creates an authenticator instance for Fast Payments authentication flow.

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

// Show authentication UI and get FastPaymentToken
try {
  const authenticator = await createAuthenticator('100.00', '[email protected]');
  const fastPaymentToken = await authenticator.show({
    confirmationLocation: 'web',
  });
  console.log('FastPaymentToken:', fastPaymentToken);
} catch (error) {
  console.error(error.message, 'Error code:', error?.errorCode);
}

For a complete working example, see the examples/fastPaymentFlow/ directory.

Components

Card Number

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

const App = () => {
  return <CardNumber placeholder="Card number" />;
};
export default App;

Security Code

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

const App = () => {
  return <SecurityCode placeholder="Security code" />;
};
export default App;

Expiration Date

Note: Expiration Date cannot coexist with Expiration Month or Expiration Year

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

const App = () => {
  return <ExpirationDate placeholder="Expiration date" />;
};
export default App;

Expiration Month

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

const App = () => {
  return <ExpirationMonth placeholder="Expiration month" />;
};
export default App;

Expiration Year

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

const App = () => {
  return <ExpirationYear placeholder="Expiration year" />;
};
export default App;

Methods

createCardToken

Return a token card

import { createCardToken } from '@mercadopago/sdk-react';
const cardToken = await createCardToken({
  cardholderName: '<CARDHOLDER_NAME>',
  identificationType: '<BUYER_IDENTIFICATION_TYPE>',
  identificationNumber: '<BUYER_IDENTIFICATION_NUMBER>',
});

updateCardToken

Update a token card

import { updateCardToken } from '@mercadopago/sdk-react';
const cardToken = await updateCardToken('<OLD_CARD_TOKEN>');

Core Methods

For a full explanation of each function parameters and return, check the SDK-JS documentation of the Core Methods

Note It's mandatory to have previously done the Initialization step

getIdentificationTypes

Return all the document types based on the public_key

import { getIdentificationTypes } from '@mercadopago/sdk-react';
const identificationTypes = await getIdentificationTypes();

getPaymentMethods

Returns a payment methods list

import { getPaymentMethods } from '@mercadopago/sdk-react';
const paymentMethods = await getPaymentMethods({ bin: '<CARD_BIN>' });

getAccountPaymentMethods

Returns account payment methods for authenticated users using FastPaymentToken

import { getAccountPaymentMethods } from '@mercadopago/sdk-react';
const accountPaymentMethods = await getAccountPaymentMethods('<FAST_PAYMENT_TOKEN>');

getCardId

Retrieves card ID from a pseudotoken using FastPaymentToken authentication

import { getCardId } from '@mercadopago/sdk-react';
const cardIdResponse = await getCardId('<FAST_PAYMENT_TOKEN>', '<PSEUDOTOKEN>');
console.log(cardIdResponse.card_id);

updatePseudotoken

Updates a pseudotoken with card token information

import { updatePseudotoken } from '@mercadopago/sdk-react';
await updatePseudotoken('<FAST_PAYMENT_TOKEN>', '<PSEUDOTOKEN>', '<CARD_TOKEN>');

getIssuers

Returns a issuers list

import { getIssuers } from '@mercadopago/sdk-react';
const issuers = await getIssuers({
  paymentMethodId: '<CARD_PAYMENT_METHOD_ID>',
  bin: '<CARD_BIN>',
});

getInstallments

Returns all installments available

import { getInstallments } from '@mercadopago/sdk-react';
const installments = await getInstallments({
  amount: <AMOUNT>,
  locale: '<LOCALE>',
  bin: '<CARD_BIN>',
});

By default, your bundler should select the appropriate module format. However, if you need to explicitly use ECMAScript Modules (ESM) or CommonJS (CJS), you can specify. For example, use import createCardToken from '@mercadopago/sdk-react/esm/secureFields/createCardToken/index'; for ECMAScript modules, or const createCardToken = require('@mercadopago/sdk-react/cjs/secureFields/createCardToken/index'); for CommonJS modules.

Run SDK project

Replace the <YOUR_PUBLIC_KEY> on examples/contants with your public key.

To run Mercado Pago React SDK, follow the steps:

Install project dependencies:

npm install

Execute project build (optional):

npm run build

Execute storybook:

npm run start

License

This project is under Apache license, version 2.0. See Apache 2.0 file for more details.