Click to Pay - JavaScript SDK

To use Click to Pay with FatZebra's JavaScript SDK, you call the renderClickToPay function:

fz.renderClickToPay({
  containerId: 'fz-paynow',
  paymentIntent: {
    payment: {
      amount: 100,
      currency: "AUD",
      reference: "ABCD1234",
    },
    verification: hash,
  }
});

The containerId parameter here will render the Click to Pay UI within the element with that ID. An example element would be:

<div id='fz-paynow'></div>

You may wish to pass an email and/or mobile as options to identify a user for the Click to Pay flow

fz.renderClickToPay({
  containerId: 'fz-paynow',
  paymentIntent: {
    payment: {
      amount: 100,
      currency: "AUD",
      reference: "ABCD1234",
    },
    verification: hash,	
  },
  options: {
    email: "[email protected]",
    mobile: "0491 571 266",
  }
});

Calling this function will render an iframe within the specified element on the page. The User Flow here is identical to how it works on the "Hosted Payment Page" version of this form.

For other options, please see the options section below.

Verification hash calculation

The verification hash is calculated by combining the reference, amount and currency into a string. Using the examples above:

ABCD1234:100:AUD

This string is then HMAC-MD5 encrypted using your account's shared secret value. If this secret value was 52ccce5a5c5, then the way to calculate this hash would be:

HmacMD5("ABCD1234:100:AUD", "52ccce5a5c5").toString();

This would result in the hash of:

d02851631e2f836ac10bb33e58687dd4

returnPath option is included in hash calculation

Note: if you also include the returnPath option, it will be appended to the end of your hash calculation:

HmacMD5("ABCD1234:100:AUD:https://example.com/purchase/successful", "52ccce5a5c5").toString();

The calculated hash for this is:

8db3bc06cf4c87f9ea6ed27bfb1ed4f6

Check your verification hashes

You can check your hash calculation method by using our Verification Hash Generator.

PaymentIntent.Payment

The payment intent options indicate the information about the payment once it gets completed.

Options

The renderClickToPay function takes several options.

Note on external CSS: When external CSS specified in the options the hosted payment page a number of verification and sanitisation steps are taken before rendering the CSS in the page, including:

• Verifying the URL specified is served over HTTPS and is in-fact a CSS file
• Verifying that the css_signature matches the URL
• Scrubbing any potentially dangerous CSS statements from the file

After successful verification and sanitising , the filtered CSS is cached by the Hosted Payment Page for 5 minutes. If the cache needs to be updated, the following options are available:

• Change the URL and update the signature to reflect - the CSS cache uses the filename and merchant ID as the cache key, so changing this will force the cache to be updated

Events

The following events may be subscribed to during the Click to Pay flow:

• fz.click_to_pay.dcf - emitted when the Digital Checkout Flow (DCF) is loaded. The card scheme hosting the flow is indicated in the event data.

{
  message: 'Digital checkout form loaded.',
  data: {  
    cardScheme: <'visa'|'mastercard'|'amex'>  
  },
}

• fz.click_to_pay.mrt - emitted if a user elects to be remembered in the browser in a new user checkout/OTP flow AND a recognition token is returned during the Click to Pay checkout. The recognition token value is provided in the event data.
  • When a non-null token value is emitted, it should be persisted as a first-class cookie.
  • When a null token value is emitted (signifying user sign-out), any associated cookie should be removed.
  • On the call to renderClickToPay(), the cookie value should be fetched and passed in via the mrtoption. This value will then be used to initialise the Click to Pay checkout.

{
  message: 'MRT created.',
  data: {
    mrt: <token value> 
  }
}

• fz.click_to_pay.resize - emitted when the Click to Pay container is resized. The new container height (in pixels) is provided in the event data. Note that this event will not be emitted when the DCF flow is entered as this content is controlled by the card schemes. We provide the fz.click_to_pay.dcfevent to notify when this flow is launched, together with the hosting card scheme, to assist with appropriately sizing the container.

{
  message: 'Container resized.',
  data: { 
    heightPx: <number> 
  }
}

• fz.click_to_pay.tokenization.success - emitted on tokenization success. This event's body and how to use it is explained further in the "Using Tokenized Cards" page.