@netceterapx/click-to-pay-sdk v2.1.0

Component usage

The Netcetera Click-to-Pay SDK component is of type web component.

<click-to-pay locale='en_US'
              isexpanded='true'
              email='myemail@email.com'
              dcfopeningbehaviour='full'
              sandbox='false'></click-to-pay>

locale This prop informs the SRCi component to render in the appropriate language set by the merchant.

isexpanded This prop is used to show/hide the SRCi component. It can be used when the SRCi button is clicked to open the component, or let the merchant control when to show the component.

email This prop can contain the currently authenticated profile email address. This allows the login section of the SRC component to autofill the users email.

dcfopeningbehaviour This prop controls how the SRC component will render the DCF window. Available options are:

• replace This will hide the SRC component while the DCF window is active. It will be placed where the SRC component is located.
• full This will cover the whole page with a backdrop. The DCF window will be placed in the center of the screen.
• popup This will open the DCF window in a popup window.

sandbox This prop controls the environment which the SRCi component starts. Possible values:

• false This starts the SRCi in production mode, using the production SDK's by the chosen credit card brands. Note: A production environment must be configured first with the chosen credit card brand (Visa, MS, etc...).
• true This starts the SRCi in development mode, using the sandbox version of the chosen credit card brands. As an example, this can be useful for local development.

ispaninpaybutton This prop controls whether a masked PAN is shown on the payment button. Possible values:

• true Masked pan is shown on the payment button.
• false Masked pan is not shown on the payment button.

buttonstyle This prop controls whether the main button in the component is in filled or outlined state. Possible values:

• FILLED Button is in filled state.
• OUTLINED Button is in outlined state.

Note: The application starts by default in production mode.

config This prop is used for initializing the SRC component.

clickToPay.config = {
  mastercard: {
    srcInitiatorId: 'required-src-initiator-id',
    srciDpaId: 'required-src-dpa-id',
    dpaTransactionOptions: {
      dpaLocale: 'required-dpa-locale',
    },
  },
  visa: {
    srcInitiatorId: 'required-src-initiator-id',
    srciDpaId: 'required-src-dpa-id',
    encryptionKey: 'required-encryption-key',
    nModulus: 'required-n-modulus',
  },
  amex: {
    srcInitiatorId: 'required-src-initiator-id',
    dpaData: {
      dpaPresentationName: 'required-dpa-presentation-name',
      dpaName: 'required-dpa-name',
    },
    dpaTransactionOptions: {
      threeDsPreference: 'required-three-ds-preference',
    },
  },
};

If for example you do not support Amex, just by not including the amex property will be enough to inform the SRC component to ignore that vendor.

Note: The SRC component has a detailed error reporting solution. Thus, any values that are missing will be reported with the full path.

config.iframe This prop is used when a custom iframe window is used by the merchant. This allows the merchant to control the position of the iframe window and also react on the iframe state changes.

<iframe width='600px' height='800px' id='src-iframe'></iframe>

clickToPay.config = {
  iframe: {
    ref: document.querySelector('#src-iframe'),
    handlers: {
      onDcfShow() {
        // handle when DCF is visible and loaded...
      },
      onDcfHide() {
        // handle when DCF window is removed...
      }
    }
  },
}

Note: The config.iframe.ref property is required when using a custom window.

transactionAmount This prop contains the amount and currency code associated with the transaction that are shown on the payment button. It is a required prop.

  clickToPay.transactionamount = {
    amount: '10',
    currencyCode: 'USD',
  }

Note: Some fields might be ignored / not used, by a particular credit card brand DCF.

Dynamically update the SRCi component

The SRCi component able to react to any changes of its props. That means the merchant can programmatically set/update its props, and the component will update itself accordingly.

document.addEventListener('DOMContentLoaded', () => {
  
  const clickToPay = document.querySelector('click-to-pay');

  clickToPay.setAttribute('isExpanded', 'false');

  clickToPay.config = {
    // ...
  }

  clickToPay.addEventListener('consumerStatus', (e) => {
    // handle consumer status events...
  });

  clickToPay.addEventListener('paymentSuccess', (e) => {
    // handle success...
  });
  clickToPay.addEventListener('paymentError', (e) => {
    // handle error...
  });

  clickToPay.addEventListener('generalEvents', (e) => {
    // handle events that might be important to listen on...
  });

  clickToPay.addEventListener('performanceUpdate', (e) => {
    // handle performance entry update
  });
  
  clickToPay.addEventListener('userActionUpdate', (e) => {
    // handle user action entry update
  });
});

document.addEventListener('DOMContentLoaded', () => {...}); It's recommended to initialize/update any properties after the component is fully initialized.

const clickToPay = document.querySelector('click-to-pay'); The merchant can get a reference to the SRCi component.

clickToPay.setAttribute('isExpanded', 'false'); Then, the merchant is able to modify any prop for the component, when that happens the component reacts.

clickToPay.addEventListener('consumerStatus', (e) => {}); The SRCi component will fire a consumer status event whenever there is an update that affects the consumer status during the interaction with the click-to-pay component. The event contains the following parameters that describe the current state of the consumer in the click-to-pay flow:

1. isRecognized: Informs whether consumer was recognized by detecting a cookie in the browser set by the SRC System.
2. hasProfile: Informs whether consumer has a profile in any of the SRC Systems.
3. hasCards: Informs whether consumer has saved cards in any of the SRC Systems.
4. hasProfileInSchemes: Gives a list of Schemes that the user has a profile in.
5. manualCardEntryMandatory: Informs whether the manual card entry form should be open by default.

clickToPay.addEventListener('paymentSuccess', (e) => {}); The SRCi component will fire a success event when the card has been selected from the user. The response will contain the data for the user card needed to complete a transaction.

clickToPay.addEventListener('paymentError', (e) => {}); The SRCi component will fire a error event whenever there is a problem that is not able to recover from. For example: The vendor SDK servers are down. Or something unexpected happened.

clickToPay.addEventListener('generalEvents', (e) => {}); The SRCi component will fire an event when important steps/actions happened inside the component, triggered by the user or the component itself. Example: The user chose to cancel the open DCF window.

clickToPay.addEventListener('performanceUpdate', (e) => {}); The SRCi component will fire an event when a new SDK performance entry has been measured. Example: Mastercard/Visa/Amex SDK init or get profile method finished, and the time for its execution has been measured.

clickToPay.addEventListener('userActionUpdate', (e) => {}); The SRCi component will fire an event when a new user action has been performed. Example: User clicked on an input field/button, started typing text or selected a card.

 enum GeneralEvents {
  ON_DCF_CANCEL
}

The SRC component can start in a "headless" mode. That means there will be no UI rendered on the screen, which is left on the merchant, rather it exposes the checkout method directly. Thus, the merchant can control the UI flow and leave the checkout process to the SRC component to handle.

Note: The SRCi components still needs to be initialized by placing the HTML code. You can hide the UI with the isExpanded props.

<click-to-pay isExpanded='false'></click-to-pay>

document.addEventListener('DOMContentLoaded', () => {
  
  const clickToPay = document.querySelector('click-to-pay');
  
  clickToPay.config = {
    // ...
  }

  // merchant creates the form. In this example we have a checkout submit button.
  let checkoutButton = document.querySelector('#checkout-button');
  
  // .then().catch() are also compatible.
  checkoutButton.onclick = async () => {
    try {
      let response = await clickToPay.checkout({
        card: {
          primaryAccountNumber: '1212121212121212',
          panExpirationMonth: '7', // '07' is also allowed.
          panExpirationYear: '2030', // must be 4 digits.
          cardSecurityCode: '123', // must be 3 or 4 digits.
        },
      });
      // handle the response.
    } catch (e) {
      // handle the error.
    }
  };
});

The response of the checkout method is forwarded from the SRC vendor to the merchant.

Example response:

{
    "userAction": "COMPLETE",
    "checkoutResponseSignature": "eyJraWQiOiJTRTZOOE...",
    "creditCardBrand": "Visa",
    "performance":{"correlationId":{"visa":"5ee5add0-bbdd-6094-55bd-16c4c7bda302","mc":"34f4a04b.8add86db-c257-4f8c-808a-b51a4a07e444","amex":""},"referenceTimestamp":"2022-12-18T20:15:50.036Z","totalLoadingTime":3731,"consumerStatus":{"isRecognized": false, "hasProfile": true, "hasCards": true, "hasProfileInSchemes": ["Visa", "Mastercard"], "manualCardEntryMandatory": false},"sdkPerformance":{"visa":[{"methodName":"init","duration":1428,"startDelta":0},{"methodName":"isRecognized","duration":1297,"startDelta":3690},{"methodName":"identityLookup","duration":1218,"startDelta":18833},{"methodName":"getSrcProfile","duration":2548,"startDelta":41254},{"methodName":"unbindAppInstance","duration":24,"startDelta":52816}]}},
    "userActions": [{"type":"click","target":"email","startDelta":1215},{"type":"text_type","target":"email","startDelta":1743},{"type":"click","target":"continue","startDelta":9258},{"type":"click","target":"otp","startDelta":18889.000000000004},{"type":"text_type","target":"otp","startDelta":43660},{"type":"click","target":"continue","startDelta":44120},{"type":"click","target":"continue","startDelta":50200}]
}

The checkout response includes a performance object that contains information about the duration of the performed SDK methods during the user interaction, and the point of time in which they started executing. Apart from the performance object, it also contains an array of user actions that the user performed, and the point of time in which the user performed the actions.

Performance object parameters:\ correlationId: The correlation ID used for the transaction.\ referenceTimestamp: The time when the click to pay component finished loading.\ totalLoadingTime: The total loading time of the click to pay component.\ consumerStatus: The consumer status.\ sdkPerformance: The SDK performance entries.

SDK performance object parameters:\ methodName: The name of the SDK method.\ duration: The duration of the method execution.\ startDelta: The number of milliseconds when the method started executing after the start of the init method execution.

User Action object parameters:\ type: The type of user action. Example: click, text_type, select.\ target: The target on which the user action is performed. Example: email, otp.\ startDelta: The point of time when the user action got executed after the loading of the click to pay component finished. Measured in milliseconds.

Error response

The SRC component validates the provided input for the checkout method. In case there is a validation error, the following response can be returned.

enum CreditCardValidationErrorType {
  CREDIT_CARD_NUMBER_REQUIRED,
  CREDIT_CARD_CVV_REQUIRED,
  CREDIT_CARD_EXPIRATION_YEAR_REQUIRED,
  CREDIT_CARD_EXPIRATION_MONTH_REQUIRED,
  CREDIT_CARD_NUMBER_INVALID,
  CREDIT_CARD_NUMBER_UNSUPPORTED,
  CREDIT_CARD_CVV_INVALID,
  CREDIT_CARD_EXPIRED,
}

interface CreditCardValidation {
  type: CreditCardValidationErrorType;
}

Inside the error part (catch (e)...) as an example the response can be:

{
  type: 'CREDIT_CARD_NUMBER_REQUIRED'
}

Click to Pay explanation modal

We offer the possibility to trigger the displaying of a Click to Pay explanation modal from the outside of our product. The merchant or PSP can call our displayClickToPayExplanationModal() method, and we will overlay the screen with a Click to Pay explanation modal.

The modal can be closed by:

• clicking on the x button within the modal
• pressing the escape key
• clicking anywhere outside the modal

document.addEventListener('DOMContentLoaded', () => {
  const clickToPay = document.querySelector('click-to-pay');
  
  clickToPay.displayClickToPayExplanationModal();
});

The Click to Pay explanation modal is following the UX guidelines of the schemes.