What you Need to Get Started

A merchant will need the following information to get started:

• An API Key

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

Secure Hosted Checkout Flow

Calling SHC

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/sessions 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/sessions endpoint, requires secret information that could be stolen if it was available to the client application. The call to /secure-hosted-checkout/v1/sessions should be done by the merchant’s server, with the result passed to the client.

Examples

---

Note: All the examples provided use JavaScript.

Obtaining an SHC Token for SHC

SHC tokens are obtained by having the merchant’s server call the shc.titan.uat.ca.payfacto.cloud/secure-hosted-checkout/v1/sessions 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:

javascript

javascript

const endpoint = 'https://uat.ca.shc.payfacto.cloud/secure-hosted-checkout/v1/sessions';
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 => console.log(response))
  .catch(response => console.error(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. merchantGetShcToken(shcToken => { shc(shcToken, response => merchantProcessResponse(response)) });

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 transaction. When the validation is successful the resulting object looks like the following example:

javascript

javascript

{
  success: true,
  response: {
    authCode: "426186",
    avs: "U",
    brand: "Visa",
    card: "411111******1111",
    cvv2Cvc2Status: "M",
    email: "test@example.com",
    expiry: "1226",
    invoiceNumber: "abc-123",
    isoResponseCode: "00",
    issuerMessage: "AP",
    lastFour: "1111",
    name: "Test Card",
    processorAvsResultCode: "",
    purchaseAmount: 1025,
    purchaseCurrency: "CAD",
    purchaseDate: "2026-01-26 17:47:44 EDT",
    secureId: "34fd08eb-cdf4-42bb-983d-ef0a386ce856",
    status: "SUCCEEDED",
    store: {
      address: "123 Some Street, Toronto, ON, A1A 1A1, CA",
      email: "contact@merchant-store.com",
      name: "Merchant Store",
      phone: "(123) 456-7890",
      website: "www.merchant.com"
    },
    success: true,
    token: "5k46v51j238tpt5v7v4u4a18hc4f04m9926",
    transactionId: "da5a34e0-793c-4c21-9fb2-f03b670eb2f8",
    transactionType: "PURCHASE",
    type: "CREDIT"
  },
  metadata: {
    algorithm: "sha256",
    HMAC: "3f7878f6b6e5e5f4e5d6c7b8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o3p4q5r6s7t8",
    timestamp: "2024-06-01T12:47:44Z"
  }
}

The contents of the response will vary depending on the operation being performed and the setup of the account.
Below is a list of properties that may be returned:

1. success: boolean indicating success or failure of the transaction
2. authCode: the authorization code
3. avs: the AVS response code
4. brand: card brand
5. card: the partial number of the card for display purposes
6. cvv2Cvc2Status: the CVV response. Valid values are ‘M' for PASS and 'N’ for FAIL
7. email: the cardholder's e-mail address
8. expiry: expiry date of the card
9. invoiceNumber: passed invoice number. If no invoice number is passed then one is generated on the fly
10. isoResponseCode: ISO response code from issuer
11. issuerMessage: message from the issuer
12. lastFour: last four digits of the card number
13. name: cardholder name
14. processorAvsResultCode: the AVS response code returned from the processor. Value varies by card brand and processor
15. purchaseAmount: the amount of the transaction
16. purchaseCurrency: the currency used to conduct the transaction
17. purchaseDate: the date and time stamp when the transaction was processed
18. secureId: the session ID
19. status: PayFacto payment platform status message
20. store.address: store address as single line
21. store.email: store support contact e-mail address
22. store.name: name of the store the merchant account is associated with
23. store.phone: store support contact phone number
24. store.website: store Website
25. token: card token automatically generated as part of the process
26. transactionId: the unique identifier of the transaction that was created
27. transactionType: the type of requested transaction. Valid values are 'PREAUTHORIZATION', PURCHASE, and 'VERIFY'
28. type: card type. Valid values are CREDIT' and 'DEBIT'
29. algorithm: the algorithm used to generate an HMAC
30. HMAC: the contents of the response converted to a string and then encrypted using the sha256 algorithm and the merchant account's private API password
31. timestamp: the time the transaction was generated.
32. receipt: an HTML receipt that can be displayed on the screen or embedded in an e-mail

AVS Response Codes

SHC returns a subset of the AVS codes. 

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
U	Address information is unavailable or AVS is not supported by downstream provider
Y	5-Digit ZIP and street address match
Z	5-Digit ZIP matches, street address does not

The Error Response

Sometimes, things don’t go as expected. When that happens, an error is returned to the calling object. The error object resembles the following example:

javascript

javascript

{
  success: false,
  response: {
    code: "INVALID_NUMBER",
    message: "card number is incorrect",
    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
  

HTTP Code	Error Type	Error Code
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

Errors Returned by 3DS

Error Type	Error Code	Description
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

// JavaScript example
function generateHmacDigest(algorithm, key, message) {
  const hmac = crypto.createHmac(algorithm, key);
  hmac.update(JSON.stringify(message));
  return hmac.digest('hex');
}

generateHmacDigest("sha256", "my-secret-key", transaction.response);

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 = {
  avs: 'both',
  amount: 'editable',
  disableSubmitIndicator: true,
  email: true,
  expires: '2025-06-24T13:50:00.0Z',
  ignoreInitAuthTimedOut: true,
  invoice: 'disabled',
  invoiceNumber: 'abc-123',
  language: language,
  purchaseAmount: 100,
  transactionType: 'PURCHASE',
  useRecaptcha: false
}

• avs: display the address and postal fields.

• Valid values are 'address', 'postal', or 'both'.
  

• If full AVS is enabled in the merchant account, ignore these values. For partial or optional AVS, pass the correct value to show the appropriate fields.

• 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: hide the submit indicator

• When set to true the submit indicator on the Pay button will not be displayed

• email: display the e-mail address field

• When set to true the the e-mail field will be displayed.
  

• If 3DS is active then this value is ignored
  

• expires: set the expiry date and time for the secure token

• The date and time the token will expire in ISO-8601 format.
  

• The default is five minutes from creation time
  

• ignoreInitAuthTimeout: ignore 3DS authentication timeout errors

• Set to true to ignore 3DS authentication initialization errors

• 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.
  

• language: language to display fields in.

• Valid values are 'en' and 'fr'.
  

• This field is mandatory.

• purchaseAmount: value of the transaction to be performed

• 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)
  

• NOTE: If the transaction type is 'PREAUTHORIZATION' or 'PURCHASE', then purchaseAmount is a mandatory value.

• transactionType: type of transaction to perform

• Valid values are 'PURCHASE', 'PREAUTHORIZATION', and 'VERIFY'.
  

• This field is mandatory
  

• useRecaptcha: disable reCAPTCHA

• Is set to true by default
  

• Set to false to turn off reCAPTCHA
  

A Note on purchaseAmount

When the purchaseAmount is part of the session request then that is the value used when the transaction is processed rather than the value passed down by the form. This means that setting purchaseAmount as an option will have no effect.

A Note on Verify Transactions

If a purchase or preauthorization is required after a verify, the response contains a token which can be used. See below for an example of how to perform a purchase or preauthorization.

Payment tokens generated by SHC can be used in subsequent calls to generate a purchase or a pre-authorization.

function postCharge(amount, invoiceNumber, token, isPurchase) {
  const capture = isPurchase === true;  // if capture is true then it is a purchase,
                                        // else it is a pre-authorization
  const endpoint = `https://uat.ca.api.payfacto.cloud/payments/v1/charges`;
  const body = {
    amount: amount,
    cature: capture,
    invoiceNumber: invoiceNumber,
    paymentMethod: {
      type: "PAYMENT_TOKEN",
      paymentToken: { storedCredential: { type: "CIT_INITIAL", tokenId: token } }
    }
  };
  const payload = {
    method: 'POST',
    headers: {
      Authorization: 'Basic YOUR API KEY HERE',
      Accept: 'application/json',
      'Content-Type': 'application/json; charset=utf-8',
      'idempotency-key': crypto.randomBytes(16).toString('base64')
    },
    body: JSON.stringify(body)
  }

  fetch(endpoint, payload)
    .then(response => {console.log( response.status); return response.json() })
    .then(data => console.log(JSON.stringify(data, null, 2)))
    .catch(error => console.error(error));
}

Disabling useRecaptcha