Skip to content

Latest commit

 

History

History
359 lines (255 loc) · 13.4 KB

card-form.md

File metadata and controls

359 lines (255 loc) · 13.4 KB
Raw

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 Is Required
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