Skip to content

lucmantovani/sdk-js

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

SDK MercadoPago.js V2

Mercado Pago's Official JS SDK


Table of Contents

  1. About
  2. Support
    1. Desktop web
    2. Mobile web
  3. Installation
  4. Initializing
  5. Checkout API
  6. Checkout Pro
  7. API
  8. Notes

About

It is a clientside SDK whose main objective is to facilitate the integration of Mercado Pago payment solutions on your website, thus allowing a secure flow and within the security standards of sensitive data transfer.


Support

Desktop web

Browser Support
Chrome 80+
Firefox 74+
Safari 14+
Edge 80+
Opera Complete
Internet Explorer 11

Mobile web

Browser Support
Chrome Complete
Firefox Complete
Safari Complete
Android Browser Complete

Installation

To install the SDK, you must include script in your application's HTML:

<script src="https://sdk.mercadopago.com/js/v2"></script>

Initializing

To start the SDK, you need to assign your public_key along with some options.

Example:

const mp = new MercadoPago('YOUR_PUBLIC_KEY', {
  locale: 'en-US',
})

Checkout API

Use our APIs to build your own payment experience on your website or mobile application. From basic to advanced settings, control the entire experience.

There are multiple supported ways to integrate Checkout API. Ranging from the most simple integration, using Checkout Bricks, to integrating with the Core Methods, where the integrator has total control of the checkout experience.

For a complete reference on the integration options, check the API reference


Full example (using Bricks)

<html>
    <body>
        <div id="cardPaymentBrick_container"></div>
    </body>
</html>
<script src="https://sdk.mercadopago.com/js/v2"></script>


<script>
    const mp = new MercadoPago('YOUR_PUBLIC_KEY');
    const bricksBuilder = mp.bricks();

    const renderCardPaymentBrick = async (bricksBuilder) => {

        const settings = {
            initialization: {
                amount: 100, //value of the payment to be processed
            },
            customization: {
                visual: {
                    style: {
                        theme: 'dark' // 'default' |'dark' | 'bootstrap' | 'flat'
                    } 
                }
            },
            callbacks: {
                onSubmit: (cardFormData) => {
                    return new Promise((resolve, reject) => {
                        fetch("/process_payment", { 
                            method: "POST",
                            headers: {
                                "Content-Type": "application/json",
                            },
                            body: JSON.stringify(cardFormData)
                        })
                        .then((response) => {
                            // get payment result
                            resolve();
                        })
                        .catch((error) => {
                            // get payment result error
                            reject();
                        })
                    });
                },
                onReady: () => {
                    // handle form ready
                },
                onError: (error) => {
                    // handle error
                }
            }                       
        }

        cardPaymentBrickController = await bricksBuilder.create('cardPayment', 'cardPaymentBrick_container', settings);
    };

    renderCardPaymentBrick(bricksBuilder);
</script>

Full example (using cardForm)

<!DOCTYPE html>
<html>
    <body>
    <form id="form-checkout" >
    <input type="text" name="cardNumber" id="form-checkout__cardNumber" />
    <input type="text" name="expirationDate" id="form-checkout__expirationDate" />
    <input type="text" name="cardholderName" id="form-checkout__cardholderName"/>
    <input type="email" name="cardholderEmail" id="form-checkout__cardholderEmail"/>
    <input type="text" name="securityCode" id="form-checkout__securityCode" />
    <select name="issuer" id="form-checkout__issuer"></select>
    <select name="identificationType" id="form-checkout__identificationType"></select>
    <input type="text" name="identificationNumber" id="form-checkout__identificationNumber"/>
    <select name="installments" id="form-checkout__installments"></select>
    <button type="submit" id="form-checkout__submit">Pay</button>

    <progress value="0" class="progress-bar">loading...</progress>
    </form>

    <script src="https://sdk.mercadopago.com/js/v2"></script>
    <script>
        const mp = new MercadoPago('PUBLIC_KEY', {
            locale: 'en-US'
        })

        const cardForm = mp.cardForm({
            amount: '100.5',
            autoMount: true,
            processingMode: 'aggregator',
            form: {
                id: 'form-checkout',
                cardholderName: {
                    id: 'form-checkout__cardholderName',
                    placeholder: 'Cardholder name',
                },
                cardholderEmail: {
                    id: 'form-checkout__cardholderEmail',
                    placeholder: 'Email',
                },
                cardNumber: {
                    id: 'form-checkout__cardNumber',
                    placeholder: 'Card number',
                },
                expirationDate: {
                    id: 'form-checkout__expirationDate',
                    placeholder: 'MM/YYYY'
                },
                securityCode: {
                    id: 'form-checkout__securityCode',
                    placeholder: 'CVV',
                },
                installments: {
                    id: 'form-checkout__installments',
                    placeholder: 'Total installments'
                },
                identificationType: {
                    id: 'form-checkout__identificationType',
                    placeholder: 'Document type'
                },
                identificationNumber: {
                    id: 'form-checkout__identificationNumber',
                    placeholder: 'Document number'
                },
                issuer: {
                    id: 'form-checkout__issuer',
                    placeholder: 'Issuer'
                }
            },
            callbacks: {
                onFormMounted: error => {
                    if (error) return console.warn('Form Mounted handling error: ', error)
                    console.log('Form mounted')
                },
                onFormUnmounted: error => {
                    if (error) return console.warn('Form Unmounted handling error: ', error)
                    console.log('Form unmounted')
                },
                onIdentificationTypesReceived: (error, identificationTypes) => {
                    if (error) return console.warn('identificationTypes handling error: ', error)
                    console.log('Identification types available: ', identificationTypes)
                },
                onPaymentMethodsReceived: (error, paymentMethods) => {
                    if (error) return console.warn('paymentMethods handling error: ', error)
                    console.log('Payment Methods available: ', paymentMethods)
                },
                onIssuersReceived: (error, issuers) => {
                    if (error) return console.warn('issuers handling error: ', error)
                    console.log('Issuers available: ', issuers)
                },
                onInstallmentsReceived: (error, installments) => {
                    if (error) return console.warn('installments handling error: ', error)
                    console.log('Installments available: ', installments)
                },
                onCardTokenReceived: (error, token) => {
                    if (error) return console.warn('Token handling error: ', error)
                    console.log('Token available: ', token)
                },
                onSubmit: (event) => {
                    event.preventDefault();
                    const cardData = cardForm.getCardFormData();
                    console.log('CardForm data available: ', cardData)
                },
                onFetching:(resource) => {
                    console.log('Fetching resource: ', resource)

                    // Animate progress bar
                    const progressBar = document.querySelector('.progress-bar')
                    progressBar.removeAttribute('value')

                    return () => {
                        progressBar.setAttribute('value', '0')
                    }
                },
                onError: (error, event) => {
                    console.log(event, error);
                },
                onValidityChange: (error, field) => {
                    if (error) return error.forEach(e => console.log(`${field}: ${e.message}`));
                    console.log(`${field} is valid`);
                },
                onReady: () => {
                    console.log("CardForm ready");
                }
            }
        })
    </script>
    </body>
    </html>

Checkout Pro

Checkout Pro is the integration that allows you to charge through our web form from any device in a simple, fast and secure way.

See the API reference


Full example

    <!DOCTYPE html>
    <html>
    <body>
        <div class="cho-container"></div>
        <script src="https://sdk.mercadopago.com/js/v2"></script>
        <script>
            const mp = new MercadoPago('PUBLIC_KEY', {
                locale: 'en-US'
            })
            const checkout = mp.checkout({
                preference: {
                    id: 'YOUR_PREFERENCE_ID'
                }
            });
            checkout.render({
                container: '.cho-container',
                label: 'Pay'
            });
        </script>
    </body>
</html>

API

MercadoPago(public_key[, options])

SDK instantiation method.

Params:

public_key | string, REQUIRED

It is the public key for your account.


options | object, OPTIONAL

Option name Values Default Type Description
locale es-AR
es-CL
es-CO
es-MX
es-VE
es-UY
es-PE
pt-BR
en-US
Browser default locale string Set the locale OPTIONAL
advancedFraudPrevention true|false true boolean Set the advanced fraud prevention status OPTIONAL
trackingDisabled true|false false boolean Enable/disable tracking of generic usage metrics OPTIONAL

Example:

const mp = new MercadoPago('PUBLIC_KEY', {
  locale: 'en-US',
  advancedFraudPrevention: true,
})

Return: mp instance

Check the reference for all SDK modules.

Checkout Bricks
Card Form
Core Methods
Secure Fields
Checkout Pro



Notes

When requesting our SDK (https://sdk.mercadopago.com/js/v2), we may ship different script based on the browser's User Agent so we can optmize the bundle size according to the needs. For IE 11 we ship polyfills so you can get a better experience when integrating with our SDK

About

Mercado Pago's Official JS SDK

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published