Click to Pay

Click to Pay provides a multi-factor authenticated online checkout option featuring advanced payment technology and intelligent security based on the EMVCo secure remote commerce integration. Spreedly has partnered with Mastercard to allow merchants to make transactions via the Spreedly API with credit card information obtained via Mastercard Click to Pay. Card brands eligible to be enrolled and retrieved via C2P are Mastercard, Visa, Discover, and American Express. C2P is gateway agnostic and therefore can be used alongside any gateway supported by Spreedly that accepts credit cards.

For additional information go to Mastercard Click to Pay documentation.

Pre-requisites

To configure your order pages to make use of C2P through the Spreedly iFrame, some pre-requisite conditions must be met for the page.

DPAID

The merchant must have a Digital Payment Application Identification Number, or DPAID, which must be configured with Mastercard before Click to Pay can be used. To obtain a DPAID please reach out to Spreedly Support.

When a DPAID is acquired, it must be included when each C2P session is invoked. A merchant can have multiple DPAIDs. An example would be to have a unique DPAID for both sandbox and production for Mobile Apps, and a third DPAID for web development.

Overview

There are three primary user flows that a customer of the merchant could encounter when using Click to Pay:

• New user
• Returning user unrecognized device
• Returning user recognized device

New user

When an end user without a Click to Pay account first interacts with the Click to Pay button, they will encounter the new user flow. To checkout with Click to Pay, the user will need to provide a credit card number, billing address, email address, and phone number that will be used as part of the One Time Password (OTP) authentication to create a new Click to Pay account.

Example:

Returning user - unrecognized device

In the case where an end-user clicks on the Click to Pay button but a Click to Pay cookie is not detected within the browser storage, the user will be prompted for their email and phone number. If they already have a C2P account, a OTP check will be initiated and handled through the Click to Pay UI.

Example:

Returning user - recognized device

In the case where an end-user clicks on the Click to Pay button and a Click to Pay device cookie is detected within the browser, the user will proceed directly to card selection once the Click to Pay experience is loaded.

At the conclusion of all three flows, the user will be presented with the option to checkout with a card, either one they are adding to their Click to Pay wallet, or a card already in their Click to Pay wallet (in the case of a returning user).

Invoking Click to Pay with Spreedly

When the checkout page loads, the following steps must be completed to use C2P.

1. The Click to Pay SDK must be loaded
   1. To correctly load the Click to Pay SDK and the Mastercard UI, the merchant must add the following scripts and origin URLs to CORS rules.
   2. Add Mastercard SRC UI Kit scripts.
   3. Add Click to Pay library

<script
  type="module"
  src="https://src.mastercard.com/srci/integration/components/src-ui-kit/src-ui-kit.esm.js"></script>
<link
  rel="stylesheet"
  href="https://src.mastercard.com/srci/integration/components/src-ui-kit/src-ui-kit.css">

<!-- C2P Library for sandbox -->
<script
  src="https://sandbox.src.mastercard.com/srci/integration/2/lib.js?srcDpaId={{srcDpaId}}&locale={{locale}}"></script>

<!-- C2P Library for production -->
<script
  src="https://src.mastercard.com/srci/integration/2/lib.js?srcDpaId={{srcDpaId}}&locale={{locale}}"></script>

Notes:

• Replace the {{srcDpaId}} with your DPA Id.
• Replace the {{locale}} with merchant site preferred locale. Format: ISO language_country pair (e.g., en_US ).

Add all the needed domains to your “Content-Security-Policy” header, so the external resource can be properly loaded. The following is an express.js example using cors dependency:

const app = express();

app.use(cors({
    origin: [
      '*.visa.com',
      '*.staticv.me',
      '*.discover.com',
      '*.discovercard.com',
      '*.aexp-static.com',
      '*.americanexpress.com',
    ]
}));

2. The Click to Pay button must be loaded.

Add this button to initialize Click to Pay.

<src-button card-brands="{{card-brands}}" />

Example:

<src-button card-brands="mastercard,visa,discover,amex" />

For additional options of the Click to Pay button, please visit the following document: Mastercard Developer - Button(requires Mastercard Developer login)

If you require a more personalized version of the Click to Pay button, please review the following documentation: Mastercard Developer - Source Marks(requires Mastercard Developer login)

If you need to disable this button, you can:

// Option 1
document.querySelector('src-button').onclick = function (event) {
  document.querySelector('src-button').shadowRoot.firstChild.setAttribute("disabled", true);
  if (!this.flag) {
    this.flag = true;
    // your code here
  }
}
// ShadowRoot reference: https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot

// Option 2
document.querySelector('src-button').onclick = function (event) {
  document.querySelector('src-button').style.pointerEvents = 'none';
  // your code here
}

3. iFrame must be added to the page

Add iFrame library:

<script type="text/javascript" src="https://core.spreedly.com/iframe/iframe-v1.min.js"></script>

Initialization

To trigger the C2P flow the merchant needs to initialize the library with the proper credentials, the needed HTML elements and bind the Spreedly.c2pInit() to a button or form submit event.

Spreedly.init will be automatically invoked as a step when loading Click to Pay user data. However, you may invoke it yourself if you want to configure any styles or event handlers prior to starting the Click to Pay flow. In that case, Click to Pay can use the existing session by providing the same number and cvv ids to c2pInit as provided to init.

Calling Spreedly.c2pInit will check that the Click to Pay SDK is complete and correctly loaded. c2pInit will, by default, also submit the provided email or phone number to MasterCard to validate if this is a new or returning Click to Pay user. If the user is already enrolled, a verification process is carried out by a OTP. If the user is not enrolled, the creation of a new profile is started.

Signature

Spreedly.c2pInit(environmentKey, options)

Arguments

Options attributes

c2pConfig note

The Mastercard C2P implementation has an init function, and it has been integrated in iFrame inside the Spreedly.c2pInit function. Therefore, the parameters that are required to C2P are those defined in iFrame in c2pConfig, the following guide shows what they are and how to use them:

Considerations

1. The srcDpaId parameter is required but does not need to be specified because Spreedly is finding this value on the Mastercard Click to Pay SDK script definition.
2. The same is true for the dpaTransactionOptions.dpaLocale and locale parameters. Each Mastercard UI component (src-otp-input, src-otp-channel-selection, src-card-list, etc.) uses the same locale parameter that is specified in the Click to Pay SDK script URL.
3. Locale for users who have a C2P profile, the language in the checkout process will be the language of the user profile, not the one that you have configured on your website or applications.
4. MUST request FPAN from Mastercard C2P API because DPAN is not supported at this time with Spreedly.
5. c2pConfig.cardBrands supports the following brands: mastercard, visa, amex, and discover.
6. When Click to Pay is initialized, Mastercard waits several seconds for each of the requested card brands to load. If any of the card brands exceed the timeout, they will not be included as an available brand and thus will be unavailable for checkout process.
7. For dpaTransactionOptions.dpaBillingPreference attribute the default value is NONE. The other options you can set are FULL (to show a full address) or POSTAL_COUNTRY.

MasterCard Developers - Click to Pay Integration

Email note

The user’s email is an input for the “new user” and “recognized user on unrecognized” device flows, so it is marked as a required field for initialization. You can provide that value in two places:

• emailEL html element, which corresponds to an HTML input, where C2P code will read the value for the user’s email.

Example:

<input type="email" id="email" placeholder="you@example.com">

// …
const options = {
  // …
  emailEl: "email",
  // …
}

Spreedly.c2pInit(environmentKey, options)

• If you already know the user’s email, you can pass it directly to the initialization or lookup code on the customer.email key and also to the emailEl element so that the user can see which email is going to be used. Since emailEl is relevant to customer.email, the user can modify it to carry out the Click to Pay process with a different desired email.

Example:

 <input type="email" id="email" placeholder="you@example.com">

const options = {
  // …
  emailEl: "email",
  // …
  customer: {
    email: “you@example.com”
  }
}
Spreedly.c2pInit(environmentKey, options)

Code example:

const environmentKey = "{{environmentKey}}"
const options = {
  spreedlyPaymentFormEl: "spreedly-payment-form",
  numberEl: "spreedly-number",
  cvvEl: "spreedly-cvv",
  spreedlyPaymentFormSubmitEl: "guest-checkout-submit",
  spreedlyPaymentFormC2PSubmitEl: "c2p-checkout-submit",
  emailEl: "email",
  countryCodeEl: "country-code",
  phoneEl: "phone",
// To pass the identifier use either the element IDs (above), or the customer object (below).
// If both are passed, the values in the elements will be used.
// If setting `doLookup: false`, you can provide neither.
// customer: {
//   email: "sample@email.com",
//   phone: {
//     number: "1234567890",
//     countryCode: "1"
//   }
// },
  c2pFrameEl: "mastercard-ui",
  c2pFrameStyle: "width=600,height=720",
  otpEl: "otp",
  cardsEl: "cards",
  cvvContainerEl: "cvv-container",
  c2pConfig: {
    dpaData: {
      "dpaPresentationName": "Moovet Shop",
      "dpaName": "MoovetShop"
    },
    dpaTransactionOptions: {
      "paymentOptions": [{
        "dynamicDataType": "NONE"
      }],
      "transactionAmount": {
        "transactionAmount": 100,
        "transactionCurrencyCode": "USD"
      }
    },
    cardBrands: ["mastercard", "visa", "discover", "amex"]
  }
}
Spreedly.c2pInit(environmentKey, options)

The initialization function will check the value of doLookup, and if unset or true, will then immediately start the c2pLookup. If doLookup is set to false, the function will stop after initialization has completed.

The initialization function will emit the c2p-initialized event upon completion.

After everything is configured, the merchant can add an onClick event to the Click to Pay button and trigger the initialization process. Example:

document.querySelector('src-button').onclick = function () {
      …
      Spreedly.c2pInit(environmentKey, options)
})

c2pFrameEl

To add the Click to Pay iFrame HTML element, you need to specify an html div with the id property that will be the placeholder to load the Click to Pay UI:

The following part of the code shows the HTML element with the id that we defined in the options for the initialization c2pInit function:

Checkout Frame: Mastercard Developers - Checkout With Existing Card & Mastercard Developers - Checkout with New Card

<iframe style="visibility: hidden" id="mastercard-ui" name="mastercard-ui"></iframe>

// Merchants should have an iFrame that the C2P checkout window can launch in
// Merchants can specify the area, size, and many more details
// C2P will then launch the card network-specific checkout flow within that iFrame
// Spreedly will toggle visibility if needed. 

If you would like to use different styling for the Spreedly iFrame during the C2P experience, you can update the styles via the iframe CSS customization function.

c2pLookup

If the initialization option doLookup is unset, or set to true, this lookup step happens automatically immediately after initialization completes. However if doLookup is set to false, or if you want to search on a different email address or phone number, you will need to manually call c2pLookup. You may call c2pLookup multiple times, each invocation will overwrite the previous call.

Spreedly.c2pLookup();

If you specify email or phone number by passing the emailEl/phoneEl&countryCodeEl no additional parameters are needed, as c2pLookup will draw the necessary values from the specified element.

If you are passing email or phone number by the email/phone&countryCode values, please include an object similar to below. You may include either the email value, the phone values, or both.

{
  email: "customers@email.com",
  phone: {
    number: "1234567890",
    countryCode: "1"
  }
}

The lookup function will trigger one of the following flows:

• In the new user flow, the Spreedly iFrame payment form that is already implemented in the merchant site will be made visible. This form must be conditioned to support two different checkout actions (conventional checkout and checkout using Click to Pay). c2p-new-user event.
• The flow for a returning user on unrecognized device triggers a One Time Password (OTP) provided by the selected card brand or MasterCard. After the OTP is successfully validated, the merchant can show the list of available credit cards, and the end-user selects one to continue with the checkout. c2p-existing-userevent
• The frictionless flow that recognizes the user with an active session and goes directly to the select card step and continues with the checkout. c2p-verified-user event

Configuring each flow

New user

This flow is used when a new Click to Pay user profile needs to be created for the current user. For a new profile creation, the following HTML elements are required in the merchant’s DOM and their ids must be specified in the c2pInit function:

• spreedlyPaymentFormEl
• numberEl
• cvvEl
• spreedlyPaymentFormSubmitEl
• spreedlyPaymentFormC2PSubmitEl

Code example:

For this code example, the following ids are defined as follows:

const options = {
    spreedlyPaymentFormEl: "spreedly-payment-form",
    numberEl: "spreedly-number",
    cvvEl: "spreedly-cvv",
    spreedlyPaymentFormSubmitEl: "guest-checkout-submit",
    spreedlyPaymentFormC2PSubmitEl: "c2p-checkout-submit",
    // ..
    // more config options
}

Spreedly.c2pInit(environmentKey, options)

The following part of the code shows a form that contains the HTML elements with ids that we defined in the initialization c2pInit function and the additional payment method fields that the merchant considers necessary to add.

This will send the data contained within the iFrame fields to the Spreedly environment, along with any additional payment method fields specified here.

<form method="GET" id="spreedly-payment-form" style="visibility: hidden">
  <label for="spreedly-name">Name</label>
  <input type="text" id="full_name" name="name_on_card">
  <br />
  <label for="spreedly-number">Credit Card Number</label>
  <div id="spreedly-number"></div>
  <br />
  <label for="spreedly-exp" id="spreedly-exp-label">Expiration Date</label>
  <input type="text" id="month" name="month" maxlength="2">
  <span>/</span>
  <input type="text" id="year" name="year" maxlength="4">
  <br />
  <label for="spreedly-cvv">CVV</label>
  <div id="spreedly-cvv"></div>
  <br />
  <input type="submit" value="C2P checkout" onclick="buildOptionAndCheckoutWithNewCard(); return false;" id="c2p-checkout-submit">
  <input type="submit" value="Guest checkout" onclick="buildOptionAndTokenize(); return false;" style="visibility: hidden;" id="guest-checkout-submit">
</form>

<script>
  function buildOptionAndCheckoutWithNewCard() {
    var paymentMethodFields = ['full_name', 'month', 'year']
    options = {};
    for(var i = 0; i < paymentMethodFields.length; i++) {
      var field = paymentMethodFields[i];
      options[field] =  document.getElementById(field).value;
    }
    Spreedly.c2pCheckout(options);
  }
  function buildOptionAndTokenize() {
    var paymentMethodFields = ['full_name', 'month', 'year']
    options = {};
    for(var i = 0; i < paymentMethodFields.length; i++) {
      var field = paymentMethodFields[i];
      options[field] =  document.getElementById(field).value;
    }
    Spreedly.tokenizeCreditCard(options);
  }
</script>

C2P accepts either a two digit or four digit year. If you would like to restrict the length of the year input, you can add the maxlength property to the year input field.

Additional payment method fields

The following fields are required by MasterCard Click to Pay:

• phone_number
• month
• last_name (Required unless full_name is specified)
• first_name (Required unless full_name is specified)
• full_name (Required unless first_name and last_name are specified)
• email

Some additional payment method fields are required by Mastercard Click to Pay, documentation here: Mastercard Developers

Legal text

This document explains the Consent for enrollment and legal text

Example:

By continuing (merchant name) will share your card details and email with my selected card brand to allow (merchant name) to securely enroll in Click to Pay for faster checkouts. Learn more.

Submit form

Two submit buttons are defined in this form:

• One of them is for the conventional checkout or guest checkout and tokenization, bonded to the buildOptionAndTokenize function.
• The other one is for the Click to Pay checkout bonded to the buildOptionAndCheckoutWithNewCard function.

This way the Click to Pay button triggers Spreedly.c2pCheckout on the filled credit card and starts the process to create a new profile on MasterCard c2p.The process and result of a call to Spreedly.c2pCheckout is the same for the three flows and is going to be explained in the following section.

Returning user on unrecognized device

This flow occurs when the user already has a profile on Mastercard C2P but doesn’t have an active session on the current device; to confirm the user, a two-factor authentication needs to be performed by sending an OTP the customer’s email or phone.

To enable this behavior, a HTML element needs to be included alongside the checkout form and the id needs to be specified in the initialization code that calls c2pInit function:

• otpEl => id of the MasterCard OTP element.

For this code example, the following id is defined as follows:

const options = {
    otpEl: "otp",
    // ..
    // more config options
}

Spreedly.c2pInit(environmentKey, options)

The following part of the code shows the HTML elements with ids that we defined in the initialization c2pInit function:

OTP Input: Mastercard Developers

<src-otp-input id="otp" style="visibility: hidden"></src-otp-input>

// Merchants should add this to display the OTP input.
// Spreedly will toggle visibility if needed. 

The OTP element is a custom element provided by the network that is confirming the account.

Returning user on a recognized device

This flow doesn’t require any particular configuration or initialization. Click to Pay was able to recognize an enrolled user on a recognized device so the user can immediately begin selecting which credit card to use at checkout.

Card selection

Once the user has an active session, a UI element with the list of available credit cards will need to be presented so the user can select which card is going to be used for checkout. An HTML element needs to be added to your page and the id of that element should be passed to the c2pInit function:

• cardsEl

For this code example, the following id is defined as follows:

UI configuration

1. Add the HTML element to display the list of cards

The following part of the code shows the HTML element with the id that has been defined in the options for the initialization c2pInit function:

Displaying cards: Mastercard Developers

  <src-card-list id="cards" style="visibility: hidden"></src-card-list>

  // Merchants should include the above line where they want to display cards
  // They can provide customizations in the HTML element or attempt to apply CSS
  // They can then provide this to Spreedly to populate with cards
  // Spreedly will toggle visibility if needed. 

A user, despite seeing a list of cards returned from Click to Pay, might want to add a new card to their account. Therefore, a New Card button is included in the list of returned cards. This button, when clicked, should make the card entry fields used in the New User flow visible.

This option uses the same HTML element used for the Spreedly Payment Form.

2. Include the CVV/CVC field for all returning card selections

As a requirement for several Issuing Banks, CVC must be collected for each card type. When a new card is entered, CVC should be included by default. However, CVC must also be captured for returning cards to ensure authorization rates are acceptable.

No validation exists for the correctness of CVV/CVC on the iFrame side.

The CVV HTML element uses the same one that is defined in the Spreedly Payment Form, therefore it must be moved or shown next to display cards. The CVV will automatically be moved after showing cards, but if you want to control this input you can specify cvvContainerEl and add the placeholder to position the CVV element where it is required. For example:

<style type="text/css">
  #cvv-container {
    position: relative;
    height: 150px;
  }

  #cvv-container #spreedly-cvv-test {
    position: absolute;
    top: 35px;
    left: 200px;  
  }
</style>

<src-card-list id="cards" style="visibility: hidden"></src-card-list>

<div id="cvv-container">
  <label>CVV input</label>
</div>

3. Customize options

The card-list UI component supports several configuration values, if you want to check the complete list of customizations, refer to the Mastercard Developers guide: Mastercard Developers

c2pSignout

If you end up in a scenario where you want to lookup a new email or phone number, after a prior successful lookup, you can call await Spreedly.c2pSignout();. This will clear any existing sessions. This should not be called prior to the first c2pLookup as an existing user's cookie may be removed, causing additional friction of the Unrecognized Device flow instead of the Recognized device flow.

Events

You can react to different Click to Pay events by registering listeners for a different set of events, like this

Spreedly.on("some-event-key", function() {
  //Input your code here 
});

Available events:

• c2p-initialized: After the Mastercard SDK has been initialized, and will return an object including a success boolean value, and, if success is true, the C2P returned initialization object.
• c2p-verified-user: After lookup has been run, and C2P is following the Returning user - recognized device flow.
• c2p-existing-user: After lookup has been run, and C2P is following the Returning user - unrecognized device flow. The OTP flow will be initiating immediately following this event.
• c2p-new-user: After lookup has been run, and C2P is following the New user flow.
• display-cards-ready: When the account holder’s cards are received from C2P and the cardsEl HTML element is visible.
• c2p-session-deleted: When the user clicks the “Not you?” link and signs out of C2P.
• add-new-card: When the user wants to add a new card to their C2P wallet and the Spreedly payment form is displayed.
• checkout-cancelled: When the Checkout is canceled by the cardholder.
• checkout-error: When the Checkout fails with an unexpected error.
• checkout-different-pm: When in the Checkout step the consumer decides to use a different card. The merchant should make the cardsEl element visible if they want the C2P account holder to choose a different C2P card.
• checkout-window-open: When the checkout modal or frame is opened.
• checkout-window-close: When the checkout modal or frame is closed.
• otp-initiated: When the OTP flow is initiated at Mastercard.
• otp-resend: When the OTP has been resent to the user.
• otp-not-you: When the user has clicked the Not You? link in the OTP element. Spreedly will automatically hide the OTP element.
• otp-response: When an OTP response is received and will return an object including a success boolean value and, if success is false, the errorReason from Mastercard.

Checkout

Once the user selects a credit card, you should enable or show a next or checkout button that will trigger the Spreedly.c2pCheckout function, which is discussed below.

Signature

Spreedly.c2pCheckout(options)

Options attributes

Error handling

You can handle Click to Pay errors by registering a listener for error events, like this:

Spreedly.on('errors', function(errors) {
  messageEl = document.getElementById("message");
  for(var i = 0; i < errors.length; i++) {
    messageEl.innerHTML =
      "Error saving card " + errors[i]["key"] + ": " + errors[i]["message"]
  }
});

Response:

[{
  attribute: "otp_code",
  key: "errors.acct_inaccessible",
  message: "The account exists but is not currently accessible (e.g. is locked)."
}]

C2P error events

iFrame + C2P console errors

MasterCard errors

For more information about Mastercard errors go to Mastercard Developers.

Testing instructions

In order to test the use cases with a new card in the flow, the merchant needs to use test cards provided by Mastercard.

A subset of these cards have been provisioned to return successful transaction responses from the Spreedly Test gateway.

Moving to production

To move to production, you must:

• Make sure that the environmentKey in the iFrame script is a production key.
• Make sure that the domain for Click to Pay Mastercard SDK script is the production domain described above.
• Make sure to specify the production DPAID and locale in the Click to Pay Mastercard SDK script.

FAQs

1. CVC Inclusion - Why do we need to do it for every card?

As a requirement for several Issuing Banks in the region, CVC must be collected for each card type or risk a declined authorization request. When a new card is entered, CVC should be included by default already but returning cards must also request a CVC code.

2. What is a DPAID?

A Digital Payment Applications Identification Number (DPAID for short) is a registration ID that must be generated with Mastercard to begin a Click to Pay session. It must be included in each session initialization request with the Mastercard API.

3. Can a payment method be obtained via Click to Pay be used with PMD?

A successful payment method flow via Click to Pay will result in a credit card with the number, expiry month, and expiry year tokenized at Spreedly alongside the cvv and any additional credit card fields supplied by the merchant. It can then be used as a normal Spreedly credit card!

4. How can I know if a payment method was tokenized via Click to Pay?

Payment methods tokenized via the Click to Pay flow will have a field on the payment method called click_to_pay: true.

Related information

• Mastercard documentation
• C2P test cards
• Spreedly iFrame payment form docs