script src="https://shc.titan.uat.payfacto.cloud/secure-hosted-checkout/v1/shc.js"></script>).<div id="shc-fields"></div>).https://shc.titan.uat.ca.payfacto.cloud/secure-hosted-checkout/v1/session endpoint from your server application.A fully functional example application can be found in our public Bitbucket repository.

A merchant will need the following information to get started:
This information listed above is provided to you when you create a new developer account with PayFacto.
/secure-hosted-checkout/v1/session endpoint./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.
Note: All the examples provided use JavaScript.SHC tokens are obtained by having the merchant’s server call the shc.titan.uat.ca.payfacto.cloud/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:
const endpoint = 'https://shc.titan.uat.ca.payfacto.cloud/secure-hosted-checkout/v1/session'; const payload = { method: 'POST', headers: { 'Content-Type': 'application/json', 'Accept': 'application/json', 'Access-Control-Allow-Origin': '*', 'Authorization': `Basic ${apikey}` }, body: JSON.stringify({ transactionType:'VERIFY' }) }; fetch(endpoint, payload) .then(response => response.json()) .then(response => res.send(response)) .catch(response => console.error(response));
{
brand: "Visa",
card: "411111******1111",
cvv2Cvc2Status: "M",
expiry: "1223",
name: "Test Card",
profileId: "72e042dd-a518-4ec2-8df0-58125f815a68",
secureId: "656dp9d7058gf3958hlb5e53o37hr0x8kwi",
success: true,
token: "5k46v51j238tpt5v7v4u4a18hc4f04m9926"
}A | Street address matches, ZIP/postal code does not |
M | Street address and ZIP/postal code match |
N | Street address and ZIP/postal code do not match |
Y | 5-Digit ZIP and street address match |
Z | 5-Digit ZIP matches, street address does not |
{
code: "INVALID_NUMBER",
message: "card number is incorrect",
success: false,
type: "CARD_DECLINED"
}
| HTTP Code | Error Type | Error Code |
400 | BAD_REQUEST | |
400 | CARD_DECLINED | INVALID_CARD_NUMBER |
400 | CARD_DECLINED | AVS_DECLINED |
400 | CARD_DECLINED | CARD_BRAND_NOT_SUPPORTED |
400 | CARD_DECLINED | CVV_DECLINED |
400 | CARD_DECLINED | RISK_DECLINED |
400 | CARD_DECLINED | ISSUER_DECLINED |
400 | AMOUNT_DECLINED | AMOUNT_TOO_LARGE |
400 | AMOUNT_DECLINED | AMOUNT_TOO_SMALL |
| 400 | UNAUTHORIZED | |
400 | BATCH_CLOSING | BATCH_CLOSING |
400 | RECAPTCHA_VERIFICATION_FAILED | |
429 | TOO_MANY_REQUESTS | |
500 | INTERNAL_ERROR | |
504 | INTERNAL_ERROR | ISSUER_TIMEOUT |
| HTTP Code | Error Type | Error Code |
| CARD_ERROR | NOT_VERIFIED (could not verify card number) | |
| CARD_ERROR | NOT_AUTHENTICATED (issuer rejected card) | |
| DOWNSTREAM_ERROR | NOT_VERIFIED (3DS provider is having technical issues) |
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.
const body = { language: language, avs: both'both', email: true, amount: 'editable', disableSubmitIndicator: true, expires: '2025-06-24T13:50:00.0Z', invoice: 'disabled', invoiceNumber: 'abc-123', purchaseAmount: 100, transactionType: 'PURCHASE', useRecaptcha: false, ignoreInitAuthTimedOut: true }
language
language to display fields in.
Valid values are 'en' and 'fr'.
This field is mandatory.
avs
display the address and postal fields.
Valid values are 'address', 'postal', or 'both'.
If AVS is set on the merchant accounts these values are ignored
email
When set to true the the e-mail field will be displayed.
If 3DS is active then this value is ignored
amount
Display the amount field. Valid values are ‘disabled', ‘editable’, and 'hidden’.
If the transaction type is 'PURCHASE' or 'PREAUTHORIZATION' and purchaseAmount is not passed then the amount field will be displayed.
If purchaseAmount is not empty and amount is not passed then the amount field will be hidden.
disableSubmitIndicator
When set to true the submit indicator on the Pay button will not be displayed
expires
The date and time the token will expire in ISO-8601 format.
The default is five minutes from creation time
invoice
display the invoice number field.
Valid values are ‘disabled', ‘editable’, and 'hidden’.
invoiceNumber
an invoice number, maximum 25 characters long.
If a value is passed and the invoice field is not set, then invoiceNumber will be displayed as a read only field.
purchaseAmount
if the transaction is a PURCHASE or PREAUTHORIZATION this field can contain the amount in lowest ordinal format (i.e. 1 dollar is passed in as 100)
transactionType
Valid values are 'PURCHASE', 'PREAUTHORIZATION', and 'VERIFY'.
This field is mandatory
useRecaptcha
Set to false to turn off reCAPTCHA
ignoreInitAuthTimeout
Set to true to ignore 3DS authentication initialization errors
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.
ignoreInitAuthTimeoutinitAuthTimeout 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.sourceElement
override shc-fields as the default location to add the fields in
cardholderName
when the cardholder's name is passed in the name field is hidden and the value is preserved in the hidden field
invoiceNumber
when passed in the value is preserved in a hidden field. If the invoice flag is set then the value is displayed in the field
purchaseAmount
when passed in the amount field is hidden and the value is preserved in a hidden field
sourceElement property in the options parameter.The following example shows how to use the sourceElement property as a third argument:
const options = { sourceElement: ‘custom-form’ }; shc(shcToken, response => handleResponse(response), options);
A field's generic layout resembles the following:
<label for="${name}" id="shc-${name}-label" class="confidante-field-label"> <div id="shc-${name}-img" class="confidante-field-img"></div> <input id="shc-${name}-input" required="required" type="text" class="confidante-field-input shc-field-${name}" name="${name}" placeholder="${placeholder}" /> <span id="shc-${name}-span">${label}</span> <div id="shc-${name}-validate" class="confidante-field-validate"></div> </label>
${name} represents the field name. Valid field name values are:If you want to hide all the images at the start of the field, use the following CSS code:
.confidante-field-img svg { visibility: collapse; }
To hide the image at the start of the card field only, use the following CSS code:
#shc-card-img { visibility: collapse; }
<button id="shc-pay-button" type="button" class="disabled">Pay</button>
#shc-pay-button CSS identifier, you can add different styles to the Pay button.shc-style id in a style tag, as shown in the following example:<style id="shc-style"> /* place the custom styles here */ </style>
You can customize forms and messages to suit your site and your customers.
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.
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' }.
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.
<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.
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.
When working with custom forms the merchant is responsible for adding the hidden 3DS fields.
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.
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.
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.
shcMessenger object allows the shc form to communicate with the calling application. The shcMessenger is created when the shc function is called.let shcMessenger; getShcToken(shcToken => { shcMessenger = shc(shcToken, response => processResponse(response), options); });
shcMessenger.on method. This method takes two arguments:The resulting call resembles the following:
shcMessenger.on('shc-event', optionalData => handleEvent(optionalData));
{ brand : cardBrand }.shc callback. Please refer to the callback documentation for details on what is sent in the data object.{ isReady: true }.{ isReady: false }.sendUnblockSubmit() message is sent. sendBlockSubmit() and allow the shc form to be ready to submit after all of the fields are valid.If your merchant account is configured for 3DS2, PayFacto will
automatically trigger the 3DS2 validation on every SHC transaction.
const options = { purchaseAmount: amountAsInteger, }; merchantGetShcToken(shcToken => { shc(shcToken, response => merchantProcessResponse(response), options); });
To test your 3D Secure implementation there are several card numbers that will trigger different 3D Secure responses. Below are the different test scenarios and the card numbers that will trigger them:
Frictionless Authentication without 3DS2
This scenario will return success without engaging 3D Secure.
Cardholder Name: Test Card
Card numbers:
Expiry Date: 08/25
CVV: 123 or 1234
Failed Authentication with 3DS2
This scenario will display a challenge page that will fail when the password “111111” to simulate a failure.
Cardholder Name: Test Card
Card numbers:
Expiry Date: 08/25
CVV: 123 or 1234
Authentication Unavailable
This scenario will provide an authentication unavailable.
Cardholder Name: Test Card
Card numbers:
Expiry Date: 08/25
CVV: 123 or 1234
Authentication Rejected
This scenario results in the authentication being rejected.
Cardholder Name: Test Card
Card numbers:
Expiry Date: 08/25
CVV: 123 or 1234
The legacy SHC solution used a combination of an api key in the Authorization header, plus a companyNumber and merchantNumber in the body. This new version of SHC requires the merchant api key username and password, base 64 encoded, in the Authorization header only.
The new payload is much simpler than the old payload.
In the new payload the following parameters are mandatory:
transactionType: the type of transactions SHC is to processlanguage: the language the form is to be displayed in{
transactionType: "VERIFY",
language: "fr"
}With the addition of the new transactionType parameter, SHC can now process purchases and preauthorizations directly instead of having to do additional calls to the API.
This allows the collection of card information and the required transaction to be handled as a single step with the results of the transaction being returned to the caller.
The three valid transaction types are now:
SHC now supports performing pre-authorization and purchases as well as verifications.
This eliminates the extra calls to the API.
transactionType to PURCHASE.transactionType to PREAUTHORIZATION. transactionType to VERIFY.If the request type is a CHARGE or a PREAUTHORIZATION the authCode will be returned as part of the response.
The successful response virtually the same as the response of Legacy SHC, with the exception being that a purchase or preauthorization will also return an authorization code (authCode.)
The HTTP response codes for error conditions remain the same, but an expanded set of error messages are now available.
If the e-mail field is present in the SHC Token request, SHC will forward an e-receipt to the e-mail address in the field.