🚧

3DS2 via the Hosted Payments is only supported via fatzebra.js. If you are currently using a direct integration with the Hosted Payments Page by creating your own iframe and Hosted Payments Page URL you will need to switch over to fatzebra.js in order to implement 3DS2

❗️

If you're using React...

Don't use this library! Use our React SDK instead!

Overview

Fat Zebra's Hosted Payments Page (HPP) provides a seamless way to perform 3DS2 checks on either new or existing cards before a purchase is made.

When your customers submit a payment, the Fat Zebra Hosted Payments Page form will perform the following operations behind the scenes and emit javascript events so that you can react appropriately:

1. Tokenise the card details entered into the Hosted Payments Page
2. Perform a 3DS2 check against the card (Note: the enableSca URL parameter must be set to true in order for this to happen, more details in Step 5 below)
3. Upon a successful 3DS2 check, HPP will then make a purchase call with the 3DS2 results to process the payment. If the 3DS2 check is unsuccessful, fatzebra.js will emit an event that you can react to.

📘

Before completing the steps below, speak to the Fat Zebra support team to have 3DS2 enabled on your account

Step 1 - Obtain an OAuth access token

Follow the steps in Obtain an OAuth token to obtain an access token for your checkout session.

Step 2 - Include fatzebra.js on your page

<script type="text/javascript" src="https://cdn.pmnts-sandbox.io/sdk/v1/fatzebra.js"></script>

Step 3 - Initialise the FatZebra JS SDK

Initialize the FatZebra object in the footer of your page:

// Initialize the FatZebra object in the footer of your page
<script>
const fz = new FatZebra({
  username: "<YOUR MERCHANT USERNAME>"
});

...
</script>

Note: your merchant username can be obtained from the Fat Zebra Merchant Dashboard.

Step 4 - Subscribe to fatzebra.js events

fatzebra.js will emit various javascript events. Subscribe to the ones relevant to you.

Available events include:

• Validation - for validation errors
• Tokenization - for success or failure of the tokenization of the card data
• SCA - for success or failure of the 3DS2 checks
• Payment - for success or failure of the payment

// Handle validation related errors, e.g. client-side validation
fz.on('fz.validation.error', function(event) {
  // ...
});

// Receive a FZ card token
fz.on('fz.tokenization.success', function(event) {
  // If required you can save the card token in your backend
});

// Handle errors related to payment processing
fz.on('fz.payment.error', function(event) {
  // Show an error message to the customer
});

fz.on('fz.payment.success', function(event) {
  // checkout ends
});

// Handle errors related to SCA
fz.on('fz.sca.error', function(event) {
  // Show an error message to the customer
});

Step 5 - Load Hosted Payments Page

enableSca: true

See HppSetupParams for HPP options.

Note: The customer object is only required when enableSca is set to true.

fz.renderPaymentsPage({
  containerId: "fz-paynow",
  customer: {
    firstName: 'Captain',
    lastName: 'America',
    email: '[email protected]',
    address: '123 Australia Blvd.',
    city: 'Sydney',
    postcode: '2000',
    state: 'NSW',
    country: 'AU'
  },
  paymentIntent: {
    payment: {
      amount: 500,
      currency: "AUD",
      reference: "ref_123490"
    },
    verification: 'ver_123480' // made up value
  },
  options: { // Hpp display options
    hideButton: false,
    hideLogos: true,
    enableSca: true
  }
});

// Register click event handler to trigger Hosted Payment Page payment flow if
// you have a custom checkout button.
const handler = function() {
  fz.checkout();
}

document.getElementById('checkoutButton').addEventListener('click', handler);

Your payment page is now ready for 3DS2 checks. When your customers enter card details and submit a payment, 3DS2 checks will now occur and either prompt the customer for additional verification details (challenge flow) or submit the payment without a customer prompt (frictionless flow).