SDK MercadoPago.js V2

Mercado Pago's Official JS SDK

About
Support
1. Desktop web
2. Mobile web
Installation
Initializing
Checkout API
Checkout PRO
Checkout Tokenizer
API
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

Navegador	Suporte
Chrome	Complete
Firefox	Complete
Safari	Complete
Edge	Complete
Opera	Complete
Internet Explorer	11

Mobile web

Navegador	Suporte
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.

See the API for Checkout API CardForm or Checkout API Core Methods

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="cardExpirationMonth" id="form-checkout__cardExpirationMonth" />
   <input type="text" name="cardExpirationYear" id="form-checkout__cardExpirationYear" />
   <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',
             },
              cardExpirationMonth: {
                 id: 'form-checkout__cardExpirationMonth',
                 placeholder: 'MM'
             },
             cardExpirationYear: {
                 id: 'form-checkout__cardExpirationYear',
                 placeholder: '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')
                }
            },
        }
     })
 </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 for Checkout PRO

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>

Checkout Tokenize

With the Web Tokenize Checkout from Mercado Pago forget the complexity to structure a form for tokenization and payment. This simple integration will provide you with a form with a design and ready front end.

See the API for Checkout Tokenize

Full example

<!DOCTYPE html>
<html>
<body>
    <div class="tokenizer-container"></div>
    <script src="https://sdk.mercadopago.com/js/v2"></script>
    <script>
        const tokenizer = mp.checkout({
            tokenizer: {
                totalAmount: 4000,
                summary: {
                    arrears: 18,
                    taxes: 20,
                    charge: 30,
                    discountLabel: 'discount label',
                    discount: 5,
                    productLabel: 'product label',
                    product: 400,
                    shipping: 10,
                    title: 'summary title',
                },
                savedCards: {
                    cardIds: 'CARD_ID',
                    customerId: 'CUSTOMER_ID'
                },
                installments: {
                    minInstallments: 2,
                    maxInstallments: 9,
                },
                backUrl: 'http://YOUR_URL/process'
            },
            theme: {
                elementsColor: '#2ddc52',
                headerColor: '#2ddc52'
            }
        });
        
        tokenizer.render({
            container: '.tokenizer-container',
            label: 'Pagar'
        });
    </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

Example:

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

Return: `mp instance`


getIdentificationTypes	METHOD
getPaymentMethods	METHOD
getIssuers	METHOD
getInstallments	METHOD
createCardToken	METHOD
cardForm	CARDFORM

`mp instance`.getIdentificationTypes()

Return all the document types based on the public_key

Example:

const identificationTypes = await mp.getIdentificationTypes()

Return: `PROMISE`

[{
  id: string,
  name: string,
  type: string,
  min_length: number,
  max_length: number
}]

`mp instance`.getPaymentMethods(`paymentMethodsParams`)

Returns a payment methods list

Params:

paymentMethodsParams | object, REQUIRED

Option Key	Type	Description
`bin`	`STRING`	Card number first 6 digits	REQUIRED
`processingMode`	`"aggregator"` \| `"gateway"`	Process mode	OPTIONAL

Example:

const paymentMethods = await mp.getPaymentMethods({ bin: '411111' })

Return: `PROMISE` (showing most common used results.)

{
  paging: {
    total: number,
      limit: number,
      offset: number,
    },
  results: [{
    secure_thumbnail: string,
    min_accreditation_days: number,
    max_accreditation_days: number,
    id: string,
    payment_type_id: string,
    accreditation_time: number,
    thumbnail: string,
    marketplace: string,
    deferred_capture: string,
    labels: string[],
    name: string,
    site_id: string,
    processing_mode: string,
    additional_info_needed: string[],
    status: string,
    settings: [{
        security_code: {
            mode: string,
            card_location: string,
            length: number
        },
        card_number: {
            length: number,
            validation: string
        },
        bin: {
            pattern: string,
            installments_pattern: string,
            exclusion_pattern: string,
        }
    }],
    issuer: {
        default: boolean,
        name: string,
        id: number
    },
}

`mp instance`.getIssuers(`issuersParams`)

Returns a issuers list

Params:

issuersParams | object, REQUIRED

Option Key	Type	Description
`paymentMethodId`	`STRING`	Payment method ID	REQUIRED
`bin`	`STRING`	Card number first 6 digits	REQUIRED

Example:

const issuers = await mp.getIssuers({ paymentMethodId: 'visa', bin: '4111111' })

Return: `PROMISE`

[{
  id: string,
  name: string,
  secure_thumbnail: string,
  thumbnail: string,
  processing_mode: string,
  merchant_account_id?: string,
}]

`mp instance`.getInstallments(`installmentsParams`)

Returns all installments available

Params:

installmentsParams | object, REQUIRED

Option Key	Type	Description
`amount`	`STRING`	Payment total amount	REQUIRED
`bin`	`STRING`	Card number first 6 digits	REQUIRED
`locale`	`STRING`	Set the response message language	OPTIONAL
`processingMode`	`"aggregator"` \| `"gateway"`	Process mode	OPTIONAL

Example:

const installments = await mp.getInstallments({
  amount: '1000',
  locale: 'pt-BR',
  bin: '411111',
  processingMode: 'aggregator'
})

Return: `PROMISE`

[{
  ...
  merchant_account_id?: string,
  payer_costs: [{
    installments: number,
    installment_rate: number,
    discount_rate: number,
    labels: string[],
    installment_rate_collector: string[],
    min_allowed_amount: number,
    max_allowed_amount: number,
    recommended_message: string,
    installment_amount: number,
    total_amount: number,
    payment_method_option_id: string
  }]
}]

`mp instance`.createCardToken(`cardTokenParams`)

Return a token card

Params:

cardTokenParams | object, REQUIRED

Option Key	Type	Description
`cardNumber`	`STRING`	Card number	REQUIRED
`cardholderName`	`STRING`	Cardholder name	REQUIRED
`cardExpirationMonth`	`STRING`	Expiration month	REQUIRED
`cardExpirationYear`	`STRING`	Expiration year	REQUIRED
`securityCode`	`STRING`	Security code	REQUIRED
`identificationType`	`STRING`	Type of document	REQUIRED
`identificationNumber`	`STRING`	Value of document	REQUIRED

Example:

const cardToken = await mp.createCardToken({
    cardNumber: '5031433215406351' ,
    cardholderName: 'APRO',
    cardExpirationMonth: '11',
    cardExpirationYear: '2025',
    securityCode: '123',
    identificationType: 'CPF',
    identificationNumber: '12345678912',
})

Return: `PROMISE`

{
  ...
  id: string
}

`mp instance`.cardForm({`amount`[`, autoMount`, `processingMode`]`, form, callbacks`})

CardForm instantiation method.

Returns: `CARDFORM INSTANCE`

Params:

amount | string, REQUIRED

Payment total amount

autoMount | boolean, OPTIONAL

Mount the Cardform Instance when it is instantiated

default value: true

processingMode | string, OPTIONAL

Set the processing mode

valid values: "gateway" | "aggregator"

default value: aggregator

form | object, REQUIRED

The form object contains cardFormMap whose purpose is to map the HTML fields into the SDK.

Form Options:

Option Key	Type	HTML Element	Description
`id`	`string`	`<form>`	Form ID	REQUIRED
`cardholderName`	`cardFormMap`	`<input>`	Cardholder name HTML options	REQUIRED
`cardholderEmail`	`cardFormMap`	`<input>`	Cardholder Email HTML options	OPTIONAL
`cardNumber`	`cardFormMap`	`<input>`	Card number HTML options	REQUIRED
`cardExpirationMonth`	`cardFormMap`	`<input>` \| `<select>`	Card expiration month HTML options	REQUIRED
`cardExpirationYear`	`cardFormMap`	`<input>` \| `<select>`	Card expiration year HTML options	REQUIRED
`securityCode`	`cardFormMap`	`<input>`	CVV HTML options	REQUIRED
`installments`	`cardFormMap`	`<select>`	Installments HTML options	REQUIRED
`identificationType`	`cardFormMap`	`<select>`	Documentation type HTML options	REQUIRED
`identificationNumber`	`cardFormMap`	`<input>`	Documentation value HTML options	REQUIRED
`issuer`	`cardFormMap`	`<select>`	Issuer value HTML options	REQUIRED

The `CardformMap` type


`id`	`string`	Field ID	REQUIRED
`placeholder`	`string`	Field Placeholder	OPTIONAL

callback | object, REQUIRED

The callback object contains callbaks functions to handle different stages of Cardform instance's flow

callback	params	Description
onFormMounted	`error`?: ERROR	Callback triggered when CardForm is mounted	REQUIRED
onFormUnmounted	`error`?: ERROR	Callback triggered when CardForm is unmounted	OPTIONAL
onIdentificationTypesReceived	`error`?: ERROR `data`?: `identificationTypesResponse`	Callback triggered when `getIdentificationTypes()` response returns	OPTIONAL
onPaymentMethodsReceived	`error`?: ERROR `data`?: `paymentMethodsResponse`	Callback triggered when `getPaymentMethods()` response returns	OPTIONAL
onIssuersReceived	`error`?: ERROR `data`?: `issuersResponse`	Callback triggered when `getIssuers()` response returns	OPTIONAL
onInstallmentsReceived	`error`?: ERROR `data`?: `installmentsResponse`	Callback triggered when `getInstallments()` response returns	OPTIONAL
onCardTokenReceived	`error`?: ERROR `data`?: `cardTokenResponse`	Callback triggered when `createCardToken()` response returns	OPTIONAL
onFetching	`resource`?: String	Callback triggered whenever the SDK is asynchronously fetching an external resource. Its possible to return a function from this callback, which is executed after the fetching is done	OPTIONAL
onSubmit	`event`?: Event	Callback triggered before the form is submitted	OPTIONAL

The responses types:

identificationTypesResponse

[{
    installments: string,
    installment_rate: number,
    discount_rate: number,
    min_allowed_amount: number,
    max_allowed_amount: number,
    recommended_message: string,
    installment_amount: number,
    total_amount: number,
    payment_method_option_id: string,
}]

paymentMethodsResponse

{
  paging: {
    total: number,
      limit: number,
      offset: number,
    },
  results: [{
    secure_thumbnail: string,
    min_accreditation_days: number,
    max_accreditation_days: number,
    id: string,
    payment_type_id: string,
    accreditation_time: number,
    thumbnail: string,
    marketplace: string,
    deferred_capture: string,
    labels: string[],
    name: string,
    site_id: string,
    processing_mode: string,
    merchant_account_id?: string,
    additional_info_needed: string[],
    status: string,
    settings: [{
        security_code: {
            mode: string,
            card_location: string,
            length: number
        },
        card_number: {
            length: number,
            validation: string
        },
        bin: {
            pattern: string,
            installments_pattern: string,
            exclusion_pattern: string,
        }
    }],
    issuer: {
        default: boolean,
        name: string,
        id: number
    },
}

issuersResponse

[{
    id: string,
    name: string,
    thumbnail: string,
    processing_mode: string,
}]

installmentsResponse

{
    merchant_account_id?: string,
    payer_costs: [{
        installments: string,
        installment_rate: number,
        discount_rate: number,
        min_allowed_amount: number,
        max_allowed_amount: number,
        recommended_message: string,
        installment_amount: number,
        total_amount: number,
        payment_method_option_id: string,
    }]
}

cardTokenResponse

{
    token: string
}

CARDFORM HELPERS

Once CardForm is instantiated, CARDFORM HELPERS is returned, and contains methods (HELPER FUNCTION) that help working with CARDFORM INSTANCE

`cardform instance`.mount()

Mount cardForm

Return:

Trigger onFormMounted callback

`cardform instance`.unmount()

Unmount cardForm

Return:

Trigger onFormUnmounted callback

`cardform instance`.createCardToken()

Create a card token

Return:

Trigger onCardTokenReceived callback

`cardform instance`.getCardFormData()

Returns all the available data from your cardForm instance

Return:

cardFormDataResponse

{
    token: string,
    installments: string,
    paymentMethodId: string,
    issuerId: string,
    identificationType: string,
    identificationNumber: string,
    processingMode: string,
    merchantAccountId?: string
}

`cardform instance`.submit()

Invoke a HTMLFormElement.requestSubmit() on your cardForm form element

Return:

Trigger onSubmit callback

Checkout PRO

Initializing the Checkout

To initialize the checkout you need to call the .checkout function from the SDK along with some options.

Checkout

mercadopago.checkout(checkoutParams)

Params

Option name	Type	Attributes	Description
`preference`	object	`id`: string	Payment Preference	REQUIRED

Tokenizer

mercadopago.checkout(tokenizerParams)

Params

tokenizer | object, REQUIRED : Data and customizations for the tokenizer. Can contain the following attributes:

Option name	Type	Attributes	Description
`totalAmount`	number		Payment amount	REQUIRED
`summary`	object	`title`: string `taxes`: number `arrears`: number `charge`: number `discount`: number `product`: number `shipping`: number `discountLabel`: string `productLabel`: string	Additional taxes and customization for the summary	OPTIONAL
`backUrl`	string		Return URL	OPTIONAL
`installments`	object	`minInstallments`: number `maxInstallments`: number	Set minimum and maximum number of installments available	OPTIONAL
`savedCards`	object	`cardIds`: string `customerId`: string	Set default saved cards	OPTIONAL

Additional configurations

Regardless of the product you are trying to render, you can pass some other configurations as params to the .checkout() function:

theme | object | OPTIONAL : Visual customization data.

Option name	Type	Description
`elementsColor`	string	Checkout elements color (e.g., buttons, labels)
`headerColor`	string	Color for the checkout header

autoOpen | boolean | OPTIONAL : If the value is set to true, it will trigger the checkout to automatically open as soon as the page loads.

render | object | OPTIONAL : Set the render options right away without needing to call the rendering functions later.

Option name	Type	Description
`container`	string	Checkout elements color (e.g., buttons, labels)
`label`	string	Label for the checkout trigger button
`type`	string	Type for the checkout trigger button

Rendering the Checkout

mercadopago.checkout.`render()`

Renders the Payment Button on a given container. This button has the trigger to open the checkout.

Params

Option name	Type	Description
`container`	string	Selector (id, class) for the container element
`label`	string	Label for the checkout trigger button
`type`	string	Type for the checkout trigger button

mercadopago.checkout.`open()`

Manually triggers the opening of an iframe element with the checkout.

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

isabella232 / sdk-js Goto Github PK

sdk-js's Introduction

SDK MercadoPago.js V2

Table of Contents

About

Support

Desktop web

Mobile web

Installation

Initializing

Example:

Checkout API

Full example (using cardForm)

Checkout PRO

Full example

Checkout Tokenize

Full example

API

MercadoPago(public_key[, options])

Params:

Example:

Return: mp instance

mp instance.getIdentificationTypes()

Example:

Return: PROMISE

mp instance.getPaymentMethods(paymentMethodsParams)

Params:

Example:

Return: PROMISE (showing most common used results.)

mp instance.getIssuers(issuersParams)

Params:

Example:

Return: PROMISE

mp instance.getInstallments(installmentsParams)

Params:

Example:

Return: PROMISE

mp instance.createCardToken(cardTokenParams)

Params:

Example:

Return: PROMISE

mp instance.cardForm({amount[, autoMount, processingMode], form, callbacks})

Returns: CARDFORM INSTANCE

Params:

The CardformMap type

The responses types:

CARDFORM HELPERS

cardform instance.mount()

Return:

cardform instance.unmount()

Return:

cardform instance.createCardToken()

Return:

cardform instance.getCardFormData()

Return:

cardform instance.submit()

Return:

Checkout PRO

Initializing the Checkout

Checkout

Params

Tokenizer

Params

Additional configurations

Rendering the Checkout

mercadopago.checkout.render()

mercadopago.checkout.open()

Notes

sdk-js's People

Contributors

Recommend Projects

Recommend Topics

Recommend Org

MercadoPago(`public_key`[`, options`])

Return: `mp instance`

`mp instance`.getIdentificationTypes()

Return: `PROMISE`

`mp instance`.getPaymentMethods(`paymentMethodsParams`)

Return: `PROMISE` (showing most common used results.)

`mp instance`.getIssuers(`issuersParams`)

Return: `PROMISE`

`mp instance`.getInstallments(`installmentsParams`)

Return: `PROMISE`

`mp instance`.createCardToken(`cardTokenParams`)

Return: `PROMISE`

`mp instance`.cardForm({`amount`[`, autoMount`, `processingMode`]`, form, callbacks`})

Returns: `CARDFORM INSTANCE`

The `CardformMap` type

`cardform instance`.mount()

`cardform instance`.unmount()

`cardform instance`.createCardToken()

`cardform instance`.getCardFormData()

`cardform instance`.submit()

mercadopago.checkout.`render()`

mercadopago.checkout.`open()`