# Web Integration source: https://developer.mastercard.com/masterpass-merchant-integration-v7/documentation/web-integration/index.md ## JS Library {#js-library} Add the Masterpass JavaScript library to your web page * HTML ```HTML ``` ## Masterpass Button {#masterpass-button} Insert the Masterpass Button URL on your checkout page (refer to the [Masterpass Digital Assets](https://developer.mastercard.com/masterpass-merchant-integration-v7/documentation/branding/masterpass-digital-assets/index.md) page for all approved button and acceptance mark URLs). Note: The masterpass button must be hosted on a page containing a domain name rather than IP address in the URL otherwise you will not be able to successfully invoke the Masterpass UI, as discussed below. * HTML ```HTML ``` > Note: The Masterpass Button displayed to your consumers depends on their prior activity with us. To ensure the best consumer experience, you should use the provided URLs and should not locally host the button on your site. Note: For Click to Pay (through Masterpass), you should use the following URL: * HTML ```HTML Click to pay with card Click to pay with card ``` where: * is the checkout ID created during onboarding * **\** is the list of accepted card brands, comma separated (for example: "master,amex,diners,discover,jcb,maestro,visa") * \<**locale\>** is the country (and language) of the merchant. ## Standard Checkout {#standard-checkout} **Invoke the Masterpass UI** Call the Masterpass checkout function from application's checkout page when the consumer clicks the Masterpass button. * JavaScript ```JavaScript // Invoke below javascript method masterpass.checkout({ "checkoutId": "c26966b0eae94a3fbe47f994b94394b2", // Merchant checkout identifier received when merchant onboarded for masterpass "allowedCardTypes": ["master,amex,diners,discover,jcb,maestro,visa"], // Card types accepted by merchant "amount": "789.53", // Shopping cart subtotal "currency": "USD", // Currency code for cart "shippingLocationProfile": "US,AU,BE", // Shipping locations supported by merchant - configured in merchant portal "suppress3Ds": false, // Set true when 3DS not mandatory for the spcecific country "suppressShippingAddress": false, // Set true when cart items has digital goods only "cartId": "1efed583-1824-436a-869f-286ebdb22ae2", // Unique identifier for cart generated by merchant "callbackUrl": "" // The URL to which the browser must redirect when checkout is complete }); ``` | Parameter | Data Type | Required | Description | |-------------------------|--------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | checkoutId | String | Yes | Unique 32-character alphanumeric identifier generated by Masterpass, which identifies your settings during a checkout; you can find this value in your Mastercard Developers account.Example: 003901a19ce64f86992d1c0d3eeda26d | | allowedCardTypes | String array | Yes | List of payment card brands supported by you; default list of payment card brands can be set up in Merchant Portal and overwritten at run time Example: \["master,amex,diners,discover,jcb,maestro,visa"\] | | amount | String | Yes | Decimal transaction amount encoded as a JSON string. Note that only a . (period) can be used as the decimal separator irrespective of locale. No other digit separators should be used. For example, do not use commas for 1000s.Example: 1200.50 ($1200.50) | | currency | String | Yes | ISO-4217 code for currency of the transaction Example: USD | | shippingLocationProfile | String | No | Shipping location profiles supported by you and set up in Merchant Portal Example: "US,AU,BE" | | suppress3Ds | Boolean | No | Set to "true" to skip 3DS authentication by Masterpass wallet; default is false | | suppressShippingAddress | Boolean | No | Set to "true" if you don't require shipping address for checkout; default is false | | cartId | String | Yes | Merchant Cart identifier | | callbackUrl | String | No | This optional parameter can be used to override the callbackUrl specified in the Merchant Portal. Note that the callbackUrl value specified must match the same top level domain (as identified by Google's domain library) as the callbackUrl configured in the Merchant Portal. The domain for the callback must be a valid public domain. | **Additional Security Settings** If you are using DSRP then additional invocation parameters may be relevant - for details see the [User Interface Invocation Settings](https://developer.mastercard.com/masterpass-merchant-onboarding/documentation/masterpass-dsrp-and-tokenization/#user-interface-invocation-settings) section of the [Masterpass DSRP and Tokenization](https://developer.mastercard.com/masterpass-merchant-onboarding/documentation/masterpass-dsrp-and-tokenization/) guide. Note: If you are using a Payment Service Provider (PSP) with the Push or Pull model and wish to process DSRP payments, you must first confirm with your PSP whether they support DSRP. Additionally, for DSRP, you must confirm the types of cryptograms your PSP supported. For these models, the merchant must submit the appropriate DSRP parameters settings supported by merchant.js or the mobile SDKs (for a mobile integration) for every transaction. Do not use portal DSRP settings with these models. **CallbackURL Override** There is an option to override the callbackURL for a given transaction to a different one provided the top-level domain of the override matches the top-level domain of the callbackURL on the merchant profile in Merchant Portal. The top level domain must be a valid public domain. For example, if callbackURL configured in Merchant Portal is , then the override URL can be: *· avanti.simplify.com* *· simplify.com:8080/tx/189?q=44* **Local Integration Testing** If integration testing in Sandbox requires redirects to localhost, then it can be done by mapping the redirect top-level domain in the **hosts** file. For example, if callbackURL configured in Merchant Portal is , then following mapping should be added to hosts file: *simplify.com 127.0.0.1* ## Express Checkout {#express-checkout} Masterpass supports two pairing flows: pairing during checkout and pairing outside of checkout. **Pairing outside checkout** You can allow consumers to provide pairing consent outside of checkout by calling the pair function of the Masterpass JS library when consumer clicks the Masterpass Button after they log in to your site. * JavaScript ```JavaScript masterpass.pair({ "checkoutId":"c26966b0eae94a3fbe47f994b94394b2", // This is a unique, 32-character alphanumeric identifier generated by Masterpass, which identifies your settings during a checkout. You can find this value in your Mastercard Developers account. "userId": "mpassUserId" // The unique consumer user identifier from the Merchant site. }); ``` | Parameter | Data Type | Required | Description | |------------|-----------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | checkoutId | String | Yes | Unique 32-character alphanumeric identifier generated by Masterpass, which identifies your settings during a checkout; you can find this value in your Mastercard Developers accountExample: 003901a19ce64f86992d1c0d3eeda26d | | userId | String | Yes | Unique consumer user identifier from the Merchant site | **Pairing during checkout** You can allow consumers to provide pairing consent during Standard checkout by setting requestPairing=true when calling the Masterpass checkout function from application's checkout page when the consumer clicks the Masterpass button. * JavaScript ```JavaScript masterpass.checkout({ "checkoutId":"c26966b0eae94a3fbe47f994b94394b2", // This is a unique, 32-character alphanumeric identifier generated by Masterpass, which identifies your settings during a checkout. You can find this value in your Mastercard Developers account "cartId":"1efed583-1824-436a-869f-286ebdb22ae2", // This is a merchant Cart identifier "allowedCardTypes": ["master,amex,diners,discover,jcb,maestro,visa"], // Card brands accepted by merchant "amount": "789.53", // Shopping cart subtotal amount "currency": "USD", // The ISO-4217 code for currency of the transaction "suppress3Ds": false, // Set true to skip 3DS step "suppressShippingAddress": false, // Set true when cart contains digital goods only "requestPairing": true, // Set true to request pairing consent from consumer "userId": "Test", // The unique consumer user identifier from the Merchant site "shippingLocationProfile":"US,AU,BE", // Shipping locations supported by merchant - configured in merchant portal }); ``` ## Callback URL {#callback-url} The consumers browser is redirected to the Callback URL on a merchant's website when a consumer completes or cancels selection of payment details or provides pairing consent . The callback URL must begin with https:// and use TLS v1.2 or higher. A full domain name must be used (IP addresses are not permitted). The domain for the callback must be a valid public domain. Example of callback URL: * CallbackURL ```callbackURL https://mymerchant.com/teststorefront/?oauth_token=a561da1c18a89c53a4f9875f9d43fc46cd9bf3e1 &oauth_verifier=a561da1c18a89c53a4f9875f9d43fc46cd9bf3e1 &checkoutId=7906244152148449430&checkout_resource_url=https%3A%2F%2Fsandbox.api.mastercard.com %2Fmasterpass%2Fpaymentdata%2Fa561da1c18a89c53a4f9875f9d43fc46cd9bf3e1&mpstatus=success ``` **oauth_verifier -** identifies the transaction. Used to retrieve payment details from Masterpass server **mpstatus -** returns status of the consumer's interaction with the Masterpass UI. *success* - consumer successfully completed selection of payment details or providing pairing consent. *cancel* - consumer closed the Masterpass UI without selecting payment data or providing pairing consent.