Skip to content

Latest commit

 

History

History
465 lines (350 loc) · 10.3 KB

fields.md

File metadata and controls

465 lines (350 loc) · 10.3 KB

Fields module

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
getIdentificationTypes METHOD
getPaymentMethods METHOD
getIssuers METHOD
getInstallments METHOD
fields MODULE


mp instance.fields.createCardToken(nonPCIData)

Token creation method


Returns: Promise<CardTokenResponse | void>

CardTokenResponse

{
    id: string,
    public_key: string,
    card_id?: unknown,
    luhn_validation: boolean,
    status: string,
    date_used?: unknown,
    card_number_length: number,
    date_created: Date,
    first_six_digits: string,
    last_four_digits: string,
    security_code_length: number,
    expiration_month: number,
    expiration_year: number,
    date_last_updated: Date,
    date_due: Date,
    live_mode: boolean,
    cardholder: Cardholder,
}

Params:

nonPCIData | object, REQUIRED

Options:

Field Type
cardId string
cardholderName string
identificationType string
identificationNumber string

mp instance.fields.create(type, options)

Field instantiation method.

Example:

mp.fields.create("cardNumber", {
    placeholder: "Card Number",
});

Returns: FIELD INSTANCE


Params:

type | string, REQUIRED

Field type. Possible values are: cardNumber, securityCode, expirationMonth, expirationYear or expirationDate.

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


options | object, OPTIONAL

The options object have properties to customize the field being created.

Options:

Option key Type Description Enabled for
placeholder string Defines field placeholder. OPTIONAL ALL
style object Defines field styles. See more OPTIONAL ALL
customFonts array Defines field customFonts. See more OPTIONAL ALL
mode string Defines year mode. See more OPTIONAL expirationYear, expirationDate

Style

Style is an object with keys being the name of CSS property and value a string with the property value.

style

{
    height: "100%",
    marginTop: "8px",
    "margin-bottom": "8px",
    fontFamily: "Roboto"
}

Accepted properties are:

Property
color
"font-family" | | fontFamily
"font-size" | | fontSize
"font-style" | | fontStyle
"font-variant" | | fontVariant
"font-weight" | | fontWeight
height
margin
"margin-bottom" | | marginBottom
"margin-left" | | marginLeft
"margin-right" | | marginRight
"margin-top" | | marginTop
padding
"padding-bottom" | | paddingBottom
"padding-left" | | paddingLeft
"padding-right" | | paddingRight
"padding-top" | | paddingTop
"placeholder-color" | | placeholderColor
"text-align" | | textAlign
width

Example:

mp.fields.create("cardNumber", {
    placeholder: "Card Number",
    style: {
        fontFamily: "Roboto"
    }
});

Custom Fonts

Custom Fonts is an array with src attribute defining an url from where to load a custom font.

customFonts

{
    src: "https://fonts.googleapis.com/css2?family=Roboto"
}

Example:

mp.fields.create("cardNumber", {
    placeholder: "Card Number",
    style: {
        fontFamily: "Roboto"
    },
    customFonts: [
        {
            src: "https://fonts.googleapis.com/css2?family=Roboto"
        }
    ]
});

Year Mode

Defines year mode for 'expirationYear' or 'expirationMonth' fields.

Possible values are short or full.

  • short: year must be of two digits.
  • full: year must be of two digits.
  • undefined: both formats are accepted.

FIELD HELPERS

field instance.mount(container)

Field mounting method.


Returns: FIELD INSTANCE


Params:

Param Type Description
container string HTML DIV id where field will be mounted REQUIRED

field instance.unmount()

Field unmounting method.


field instance.on(event, callback)

Method to add event listeners to field.


Params:

Param Type Description
event string Event to listen REQUIRED
callback function Callback function to be executed when event happens REQUIRED

The default events, enabled for every field are: blur, focus, ready or validityChange. The table below specifies the callback functions signature for every event.

Event Params Description Enabled for
blur defaultEvent Callback triggered when blur event occurs ALL
focus defaultEvent Callback triggered when focus event occurs ALL
ready defaultEvent Callback triggered when field has been initialized ALL
change defaultEvent Callback triggered when field value changes ALL
validityChange validityChangeEvent Callback triggered when field validation occurs ALL
error errorEvent Callback triggered when error event occurs ALL
binChange binChangeEvent Callback triggered when bin state changes from invalid to valid or from valid to invalid. It returns the bin when valid or null when invalid cardNumber

defaultEvent

{
    field: string
}

validityChangeEvent

{
    field: string,
    errorMessages: [{
        message: string,
        cause: string
    }]
}

The table below provides information about causes and messages:

Field Cause Messages

cardNumber

invalid_type

cardNumber should be a number.

invalid_length

cardNumber should be of length between '9' and '18'.

securityCode

invalid_type

securityCode should be a number.

invalid_length

securityCode should be of length '3'.
securityCode should be of length '4'.

expirationMonth

invalid_type

expirationMonth should be a number.

invalid_value

expirationMonth should be a value from 1 to 12.
expirationMonth value should be greater than '<previous month>' or expirationYear value should be greater than '<current year>'.

expirationYear

invalid_type

expirationYear should be a number.

invalid_length

expirationYear should be of length '2' or '4'.

invalid_value

expirationYear should be greater or equal than <currentYear>.
expirationMonth value should be greater than '<previous month>' or expirationYear value should be greater than '<current year>'.

expirationDate

expirationMonth and expirationYear causes and messages.


errorEvent

{
    field: string,
    error: string
}

binChangeEvent

{
    bin: string | null,
    field: string
}

field instance.update(properties)

Method to update field properties.


Params:

Param Type Description
properties object Properties to update REQUIRED


The table below specifies the properties available for being updated.

Property Type Description Enabled for
placeholder string Field placeholder ALL
settings SecurityCode | CardNumber Field settings securityCode, cardNumber

SecurityCode

{
    mode: string, // 'mandatory' | 'optional'
    length: number // 3 | 4
}

CardNumber

{
    length: number // Between 8 and 19
}

Returns: FIELD INSTANCE