API v1.0 - SHC - Secure Hosted Checkout

API v1.0 - SHC - Secure Hosted Checkout

About SHC

What is Secure Hosted Checkout?

Secure Hosted Checkout (SHC) is a JavaScript library that allows merchants to collect and send cardholder information to PayFacto for verification without needing to access that information directly. When called, SHC will verify the card information and provide the merchant with a token that can be used with the /v1/preauthorizationWithToken or /v1/purchaseWithToken endpoints in PayFacto’s Payment API.

SHC allows you to create a secure iframe for accepting credit card information. There are four steps required to configure the necessary iframe:

  1. Include the Secure Hosted Checkout library in your webpage (i.e.: <script src="https://form.gateway.staging.payfacto.cloud/secure-hosted-checkout/v1/shc.js"></script>).
  2. Add a div tag where you want the iframe to appear (i.e. <div id="shc-fields"></div>).
  3. Acquire an SHC token by calling the /secure-hosted-checkout/v1/session endpoint from your server application.
  4. Call the shc function with the secure token and a callback function (i.e.: shc(shcToken, callback).) The callback function will receive the results of the credit card verification.

A fully functional example application can be found in our public Bitbucket repository.


What you Need for SHC

A merchant will need the following information to get started:

  • A Company Number
  • A Merchant Number
  • An API Key

This information listed above is provided to you when you create a new developer account with PayFacto.


For SecureFields Developers

For developers who have previously worked with SecureFields, SHC is not a new version of SecureFields, it is an entirely new product. It has new API calls for both the server and the client. A number of requested changes to the old SecureFields were incorporated in SHC in order to simplify development and integration. Some of the more notable changes are:

  1. The endpoint for requesting a shcToken is different than for a secureToken.
  2. The request object no longer needs to be converted into a string.
  3. The request object properties no longer start with an upper case letter.
  4. A shcToken is an object rather than a string. The whole object needs to be passed to the shc function.
  5. The shc function takes a callback rather than returning a promise.
  6. shc is not in a modal by default. There is no longer a need to embed an iframe in the page in order to have the fields appear within the page.

Calling Secure Hosted Checkout

Calling SHC is a two step process:
  1. A Secure Token must be obtained by calling the /secure-hosted-checkout/v1/session endpoint.
  2. After obtaining the token, it must be passed to the shc function which will display the fields for the cardholder to fill in.

Why a Two Step Process?

The first step, calling the /secure-hosted-checkout/v1/session endpoint, requires secret information that could be stolen if it was available to the client application. The call to /secure-hosted-checkout/v1/session should be done by the merchant’s server, with the result passed to the client.


Examples

Note: All the examples provided use JavaScript.

Obtaining a Secure Token for SHC

Secure tokens are obtained by having the merchant’s server call the /secure-hosted-checkout/v1/session endpoint. This endpoint is RESTful in that it expects a JSON object as input and returns a JSON object as output. An example of a request is given below:

  1. const endpoint = 'https://form.gateway.staging.payfacto.cloud/secure-hosted-checkout/v1/session'; // NOTE: customerNumber and operatorId are supplied by merchant // NOTE: language can be either 'en' or 'fr' const body = { companyNumber: companyNumberSuppliedByPayFacto, merchantNumber: merchantNumberSuppliedByPayFacto, customerNumber: customerNumber, operatorId: operatorId, language: language }; const payload = { method: 'POST', headers: { 'Content-Type': 'application/json', 'Accept': 'application/json', 'Access-Control-Allow-Origin': '*', 'Authorization': `Basic ${authApiKeySuppliedByPayFacto}` }, body: JSON.stringify(body) }; fetch(endpoint, payload) .then(response => response.json()) .then(response => sendResponseToBrowser(response)) .catch(error => handleError(response)); });

Displaying the Fields on the Screen

The fields for the cardholder to fill in are created and displayed when the shc function is called. The secure token is retrieved from the merchant server and passed to the shc function. The callback, the second argument passed to the shc function, is a merchant defined function that gets the results of the credit card validation and decides what action to take.

  1. <!DOCTYPE html> <html> <head> <script src="https://form.gateway.staging.payfacto.cloud/secure-hosted-checkout/v1/shc.js" ></script> <script src="/merchantCode.js" ></script> <title>SHC Example</title> </head> <body> <!-- The shc-fields div is required. The shc function will put the fields within that div --> <div id="shc-fields"></div> <script type="text/javascript"> merchantGetShcToken(shcToken => { shc(shcToken, response => merchantProcessResponse(response)); }); </script> </body> </html>

SHC Responses

After calling SHC, the response guides you to the next step

SHC Callback Response Object

When shc is called it is passed a callback to accept the results of the card validation. When the validation is successful the resulting object looks like the following example:
  1. { brand: "Visa", card: "411111******1111", cvv2Cvc2Status: "M", expiry: "1223", name: "Test Card", profileId: "72e042dd-a518-4ec2-8df0-58125f815a68", secureId: "656dp9d7058gf3958hlb5e53o37hr0x8kwi", success: true, token: "5k46v51j238tpt5v7v4u4a18hc4f04m9926" }

The callback response object definitions are:

  • brand: The card brand. Supported brand names are Amex, Diners, Discover, Mastercard, Maestro, Visa, and Unknown.
  • card: The masked card number.
  • cvv2Cvc2Status: Downstream provider verification status.
  • expiry: The card expiry date.
  • name: The cardholder’s name.
  • profileId: The cardholder profile.
  • secureId: The secure token id used to generate the verification request.
  • success: A boolean value indicating if the request was successful or not.
  • token: The purchase token created when the card is successfully verified.

The Error Response

Sometimes, things things don’t go as expected. When that happens, an error is returned to the calling object. The error object resembles the following example:
  1. { code: "INVALID_NUMBER", message: "card number is incorrect", success: false, type: "CARD_DECLINED" }
The error response definitions are:
  • code: The subclass of error that was returned. The valid values are:
    • INVALID_EXPIRY_DATE
    • INVALID_NUMBER
    • TOKEN_EXPIRED
  • message: A message that briefly describes the nature of the error.
  • success: A boolean value indicating if the request was successful or not. This property will always be set to false for an error response.
  • type: The class of error that was returned. The valid values are:
    • CARD_DECLINED
    • INTERNAL_ERROR
    • UNAUTHORIZED
​
Errors Returned by 3DS
Error TypeError Code
CARD_ERRORNOT_VERIFIED (could not verify card number)
CARD_ERRORNOT_AUTHENTICATED (issuer rejected card)
DOWNSTREAM_ERRORNOT_VERIFIED (3DS provider is having technical issues)

Adding Optional Fields

Adding additional, optional fields to collect purchaser information

By default, SCH displays the minimum number of fields needed to validate a credit card online. These are the cardholder name, card number, expiry date, and CVV fields. SCH can also display fields for address, postal code, email address, as well as change the display behavior of the Pay button. By default, the Pay button's behavior changes from the word Pay to a spinner; you can choose to disable this functionality.

To include these fields, you need to supply the optional values when creating the secure token.

  1. const body = { companyNumber: companyNumberSuppliedByPayFacto, merchantNumber: merchantNumberSuppliedByPayFacto, customerNumber: customerNumber, operatorId: operatorId, language: language, avs: both, email: true, disableSubmitIndicator: true, useRecaptcha: false, ignoreInitAuthTimedOut: true }

The companyNumber, merchantNumber, customerNumber, operatorId, and language fields are all required when calling SHC.

You can add optional fields when calling SHC that expand the functionality of the SHC token. The definitions for the optional fields are:

  • avs: Takes one of the following strings in order to display fields that will collect the customer's address:
    • address displays a field to collect the street address
    • postal displays a field to collect the postal code
    • both displays fields to collect both the street address and the postal code
  • email: Takes a boolean value
  • disableSubmitIndicator: Takes a boolean value
  • useRecaptcha: Takes a boolean value. By default, this value is true; include this line only if you wish to disable the use of reCAPTCHA on the page
  • ignoreInitAuthTimeout: Takes a boolean value. By default this value is false. Include this line if you want to ignore 3DS Secure authentication initialization errors

Disabling useRecaptcha

SHC uses Google's reCAPTCHA to prevent to prevent some automated attacks. For security purposes, the useRecaptcha option is set to true by default.

However, some merchants have reported that using Google's reCAPTCHA interferes with their site. In these rare instances, SHC allows you to disable this security feature.

🚧

Risks of disabling useRecaptcha

If you pass the useRecaptcha as false in the options, you are disabling the SHC reCAPTCHA feature and you risk exposing your custom form to various attacks, including a velocity attack.

Usage of ignoreInitAuthTimeout

As part of the 3D Secure authentication process, SHC collects information about the device and browser used by the customer. In rare cases, this process can cause a timeout and generate an initAuthTimeout error which can cause the transaction to fail. Setting ignoreInitAuthTimeout to true will ignore the the timeout error and allow the rest of the 3D Secure process to continue.

🚧

Risks of disabling ignoreInitAuthTimedOut

If you pass ignoreInitAuthTimeout as true, part of the 3D Secure process is bypassed and the merchant may be liable for fraudulent transactions.


Options, the Third Argument

Adding an additional argument to render fields correctly.

In some cases, additional information is required to render the fields in your custom form. In those cases, you can provide a third argument, containing options.

📘

Available option

Currently, the only supported option for custom forms is sourceElement.

sourceElement
When working with custom forms, SHC requires the id of the tag containing the form. This id is passed to SHC as the sourceElement property in the options parameter.

The following example shows how to use the sourceElement property as a third argument:

  1. const options = { sourceElement: ‘custom-form’ }; shc(shcToken, response => handleResponse(response), options);

Customizing

Making the payment page your own

Customizing the Look of The SHC Fields

SHC provides a number of CSS classes that you can override to change the appearance of the SHC fields. The classes are structured so you can overwrite fields as a group, allowing for consistency across all the fields. If inconsistency is desired or required, each element has its own unique id which allows for granular manipulation of each element in the form.


A field's generic layout resembles the following:
  1. <label for="${name}" id="shc-${name}-label" class="confidante-field-label">
  2.   <div id="shc-${name}-img" class="confidante-field-img"></div>
  3.   <input id="shc-${name}-input" required="required" type="text" class="confidante-field-input shc-field-${name}" name="${name}" placeholder="${placeholder}" />
  4.   <span id="shc-${name}-span">${label}</span>
  5.   <div id="shc-${name}-validate" class="confidante-field-validate"></div>
  6. </label>

Where ${name} represents the field name. Valid field name values are:
  1. name: The cardholder's name on the card.
  2. card: The card number.
  3. expiry: The card's expiry date.
  4. cvv: The three or four digit CVV number on the back of the card.
  5. email: The cardholder’s email address.
  6. address: The cardholder’s postal address.
  7. postal: The cardholder’s postal code.
If you want to hide all the images at the start of the field, use the following CSS code:
  1. .confidante-field-img svg {
  2.   visibility: collapse;
  3. }

To hide the image at the start of the card field only, use the following CSS code:
  1. #shc-card-img {
  2.   visibility: collapse;
  3. }

You can also customize the Pay button. The default layout for the button field is shown below:
  1. <button id="shc-pay-button" type="button" class="disabled">Pay</button>

By using the #shc-pay-button CSS identifier, you can add different styles to the Pay button.

Where to Put the CSS Styles
To apply the CSS styles, you need to put the shc-style id in a style tag, as shown in the following example:
  1. <style id="shc-style">
  2.   /* place the custom styles here */
  3. </style>

This ensures that all the styles in this tag will be applied to the SHC fields and buttons.

You can customize forms and messages to suit your site and your customers.

Custom Forms

To create a custom form, the merchant creates the form inside a div tag and then passes the id of that div tag to the shc function using the sourceElement property in the options object (i.e.: shc(secureToken, callback, { sourceElement: merchantForm }).)

The function will then use this form instead of generating its own. As part of the setup, all of the listeners will be stripped from the copied fields. To make use of the shc listeners add the id of the listener you want to emulate to the field.

For example, to take advantage of shc's card formatting, add id="shc-card-input" to the custom card field. If a field is marked with the required attribute the Pay button will not be enabled until the field contains a value.

When the form is submitted the contents of all the user defined fields will be part of the response in the callback.

Custom Messaging

In a custom form, buttons that contain the attribute data-message will send the contents of that message in a message to the parent form via a message. You can use a message event listener (i.e.: window.addEventListener('message', messageEventHandler);) to listen for the event. The message will use the format { message: 'data-message contents' }.

Creating a Custom Form

No need to use the default, custom forms allow for a standardized look that matches your website


Creating your Own Custom Form

SHC allows a merchant developer to create a custom form. The form can contain both SHC fields and the merchant’s own fields. To designate a field as an SHC field, the field id must be the same as the id of an auto-generated SHC field. Valid field ids are:

  • shc-name-input: The cardholder name field.
  • shc-card-input: The card number field.
  • shc-expiry-input: The card expiry date field.
  • shc-cvv-input: The card's CVV value field.
  • shc-email-input: The cardholder's email address field.
  • shc-address-input: The cardholder's postal address field.
  • shc-postal-input: The cardholder's postal code field.

If a field has an SHC field id, all the formatting and listeners will be applied to that field. When the Pay button is clicked, the values in the user fields will be collected and returned to the caller.

  1. <div id="custom-form"> <form style="display: flex;"> <input id="secureId" name="secureId" type="hidden" value="bonJeton" /> <input type="hidden" name="name" value="JOHN DOE" /> <input type="text" id="shc-card-input" name="card" placeholder="1234 1234 1234 1234" required="required" autocomplete="cc-number" /> <div style="display: flex; flex-direction: row;"> <input type="text" id="shc-expiry-input" name="expiry" placeholder="MM / YY" required="required" /> <input type="text" id="shc-cvv-input" name="cvv" placeholder="123" required="required" autocomplete="cc-csc" /> </div> <button id="shc-pay-button" type="button">Pay</button> </form> </div>
In order to use your custom form you will need to pass the form's id to shc as an option in the third argument.
  1. shc(shcToken, response => handleResponse(response), { sourceElement : 'custom-form'})

Custom Required Fields

If you need to add a required custom field, you must set the required attribute on the field in order to prevent the Pay button from being enabled until that custom field contains a value.
  1. <input required="required" type="text" name="myRequiredField" />


Custom Forms and 3DS

When working with custom forms the merchant is responsible for adding the hidden 3DS fields.

JavaScript
<input id="purchaseAmount" name="purchaseAmount" type="hidden" value="920">
<input id="purchaseCurrency" name="purchaseCurrency" type="hidden" value="CAD">
<input id="purchaseDate" name="purchaseDate" type="hidden" value="2025-11-03T18:16:43.948Z">

All three fields must be present and all three fields must have the following names and values:

  • purchaseAmount: the monetary amount of the transaction denoted in minor units. So in the above example the value is $9.20, not $920.00.
  • purchaseCurrency: the currency that the transaction will be conducted in. For most merchant accounts the value will be “CAD” for Canadian dollars. Note that the currency must be the same as the merchant account’s currency.
  • purchaseDate: the date and time the transaction is taking place in extended ISO-8601 format (YYYY-MM-DDTHH:MM:SS.000Z)

The fields will be treated as read only by SHC so the required values can be safely pre-loaded before SHC is called.

Custom Form Security

Default security behavior for custom SHC forms

Custom Form Security Features

To protect against the possible injection of fraudulent code, SHC prevents the transfer of the following HTML tags to the SHC secure iframe:

  • <SCRIPT>
  • <IFRAME>
  • <OBJECT>
  • <A> (the anchor tag)
  • <INPUT TYPE=”SUBMIT”>
  • <BUTTON TYPE=”SUBMIT”>

As an added measure of security. the ACTION and METHOD attributes are removed from the <FORM> tag.

In addition to disallowing certain tags and attributes, no JavaScript is transferred to the SHC secure iframe. This includes JavaScript that is part of a permissible HTML tag or any events that were attached to an HTML tag before transferring the form to the SHC secure iframe.


Custom Events

Customizing what you can do with custom forms

In a custom form, buttons that contain the data-message attribute will send the contents of that message in a message to the parent form via a message.

You can use a message event listener (i.e.: window.addEventListener('message', messageEventHandler);) to listen for the event. The message will use the { message: 'data-message contents' } format.


The shcMessenger Object

Enables the SHC form to communicate with the application calling the form

shcMessenger

The shcMessenger object allows the shc form to communicate with the calling application. The shcMessenger is created when the shc function is called.

  1. let shcMessenger; getShcToken(shcToken => { shcMessenger = shc(shcToken, response => processResponse(response), options); });

Receiving Messages

The shc form emits messages during execution. The calling application can receive those messages and act on them using the shcMessenger.on method. This method takes two arguments:

  • The message being listened for
  • The callback to handle the message

The resulting call resembles the following:

  1. shcMessenger.on('shc-event', optionalData => handleEvent(optionalData));

The list of message events that the calling application can receive is:

  • shc-card-brand: The detected card brand when the cardholder enters the number. This message forwards an object containing the brand { brand : cardBrand }.
  • shc-submit: The card information has been submitted for verification.
  • shc-response: The same response being sent to the shc callback. Please refer to the callback documentation for details on what is sent in the data object.
  • shc-3ds: The three-d-secure process has started.
  • shc-3ds-challenge: The three-d-secure challenge flow is being executed.
  • shc-ready-to-submit: All of the validation passes and the form can be submitted. This message forwards an object containing the ready status { isReady: true }.
    NOTE: If the user changes a value in the required fields and validation no longer passes, the message object will contain the status { isReady: false }.

Sending Messages

The shc form can accept messages from the shcMessenger. These messages are sent via method calls on the object. The messages currently available to send are:

  • sendBlockSubmit(): The method requests that the shc form not consider itself as ready to submit until a sendUnblockSubmit() message is sent. NOTE: The Pay button will remain in a disabled state even when all the fields are valid.
  • sendUnblockSubmit(): Cancel a sendBlockSubmit() and allow the shc form to be ready to submit after all of the fields are valid.
  • sendCancel(): This method requests that the shc form destroy itself.
  • sendSubmit(): Requests that the shc form submit itself. NOTE: The form is not submitted if any of the fields in the form are not valid.

    • Related Articles

    • SHC - Secure Hosted Checkout

      Secure Hosted Checkout What is Secure Hosted Checkout? Secure Hosted Checkout (SHC) is a JavaScript library that allows merchants to collect and send cardholder information to PayFacto for authorization (pre-authorization), purchase, or verification ...

    • Construct a Secure Hosted Checkout (Legacy) Log

      This article explains how to construct and put together all the sequential activities related to a Secure Hosted Checkout transaction for debugging purposes. 1. View log You can use this view log to help locating all these info easily and by ...

    • SHP - Secure Hosted Pages

      Secure Hosted Pages Migrating from Legacy Hosted Pages In an effort to simplify redirect, The new Secure Hosted Pages (SHP) is very different from the old version. The new SHP mirrors Secure Hosted Checkout (SHC) fairly closely, making it easier to ...

    • Hosted Payment Page

      Introduction This page aims to train future users of the secure redirection of the PayFacto payment solution. You will find in this page a description of the secure redirection service, the operation, the various call and return parameters, the ...

    • SPL - Secure Pay By Link

      Secure Pay By Link Secure Pay By Link (SPL) is a new offering from PayFacto that allows a merchant to defer a SHC session to another time. It does that by creating a link that the cardholder can follow to a hosted page. When the cardholder navigates ...