Skip to content

Latest commit

 

History

History
326 lines (251 loc) · 8.91 KB

card-form.md

File metadata and controls

326 lines (251 loc) · 8.91 KB

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
expirationMonth cardFormMap <input> | <select>|Card expiration month HTML options REQUIRED
expirationYear cardFormMap <input> | <select>|Card expiration year HTML options REQUIRED
expirationDate cardFormMap <input> | <select>|Card expiration date HTML options REQUIRED
securityCode cardFormMap <input>|SecurityCode 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
style object Field styles only available for cardNumber, securityCode, expirationDate, expirationMonth and expirationYear when the iframe option is true. See more OPTIONAL
customFonts array Field customFonts only available for cardNumber, securityCode, expirationDate, expirationMonth and expirationYear when the iframe option is true. See more OPTIONAL
mode string Field mode only available for expirationDate and expirationYear when the iframe option is true. See more 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
onReady Callback triggered when cardForm is ready. It occurs when getIdentificationTypes() response returns and when iframes are ready if iframe option is true OPTIONAL
onValidityChange error?: validityChangeResponse
field?: string
Callback triggered when some field validation occurs OPTIONAL
onBinChange bin: string Callback triggered when BIN has changed OPTIONAL
onError error?: onErrorResponse
event?: ErrorEvent
Callback triggered when some error occurs. You can use this callback to replace error validation of previous callbacks 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
}

validityChangeResponse

[
    {
        message: string,
        code: string
    }
]

onErrorResponse

[
    {
        message: string
    }
]


iframe | boolean, OPTIONAL

Defines wheter the SDK should use MP Fields for cardNumber, securityCode and expirationDate or not.

If you opt to use iframe, you must change the HTML Element for cardNumber, securityCode and expirationDate to div, in order to be used as the container for the iFrames.

Check section Fields for more information

default value: false



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


cardform instance.update(field, properties)

Method to update field properties.


Params:

Param Type Description
field string Field to update REQUIRED
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