Classic-integration icon

Logic

Include additional logic in your payment form using hooks.

The classic Checkout SDK integrations are being phased out
This means we are:

  • No longer developing the classic Checkout SDK integration.
  • Not accepting new classic Checkout SDK integrations.

You have until March 31, 2024 to migrate.

Invoke hooks when the following events occur:

EventHook triggered

The shopper requests more payment methods

toggleExcessPaymentMethods - Customize the Show more payment methods button of your Checkout.

The shopper selects Pay

getDataFromSubmissionProcess - Intercept JSON data that is generated when the shopper selects Pay.showProcessingAnimation - Customize how a processing payment is indicated.(available in Checkout SDK 1.2.1 and later)onSubmitAction - Customize the behaviour of your Checkout form when the shopper selects Pay.(available in Checkout SDK 1.2.1 and later)

The payment is submitted

beforePendingInitiation - Customize what is displayed when the shopper's payment is submitted.handleError - Know when an unexpected error occurs from the time a shopper provides card details to when the payment is submitted. 

The payment reaches a final state

afterPendingInitiation - Leave the payment in a Pending state. This allows you to execute other tasks.beforeComplete - Customize what happens when the payment reaches a final state.beforePendingRedirect - Customize what is displayed on your Checkout form when the shopper is redirected to an external website.(available in Checkout SDK 1.2.1 and later)beforeRedirect - Redirect the shopper away from your website to complete the payment.

More information and code examples for the hooks are provided below.

toggleExcessPaymentMethods

The following example shows configuring the text on the Show more payment methods button to Show less and Show more:

chckt.hooks.toggleExcessPaymentMethods = function(buttonNode/*HTML Node*/, excessNodesAreVisible/*Boolean*/) {
  var textField = buttonNode.querySelector('.chckt-more-pm-button__text');
  textField.innerText = (excessPMsAreVisible)? 'Show less': 'Show more';
  return false;
};

getDataFromSubmissionProcess

To use this hook, set the SDK configuration option initiatePayment to false.

This example shows how you can configure the Checkout form to intercept JSON data.

chckt.hooks.getDataFromSubmissionProcess = function(checkoutNode/*HTML Node*/, formData/*JSON string*/) {
  // Add your logic here
  return false;
}

showProcessingAnimation

This will not be called if you block the default onSubmitAction behaviour.

In the following example, when the shopper clicks the Pay button:

  • The text Payment in progress is displayed
  • The button color changes to blue
chckt.hooks.showProcessingAnimation = function(actionButton/*HTML Node*/) {
  actionButton.innerText = 'Payment in progress'
  actionButton.style['background-color'] = '#22A';
  return false;
};

onSubmitAction

When using this hook, chckt.submitPaymentForm() needs to be called for the payment to be submitted.

In the following example, when the Pay button is selected:

  • The Pay and Show more payment methods buttons will be hidden
  • Payment method divs are disabled
  • The payment initiation is blocked
chckt.hooks.onSubmitAction = function(actionButton/*HTML Node*/, extraData/*Object*/) {

  // Hide the 'pay' & 'show more payment methods' buttons
  chckt.toggleActionButton(false);
  chckt.toggleShowMorePMsButton(false);

  // Give all paymentMethod divs a disabled state
  chckt.toggleEnableAllPaymentMethods(false);

  // Block default functionality
  return false;
};

You can also customize elements of your Checkout. In the following example:

  • The payment method divs are disabled
  • Review and Show more payment methods buttons are hidden
  • An extra step is created, where the shopper can review their order
  • An Edit button is displayed, allowing the shopper to modify their order
chckt.hooks.onSubmitAction = function(actionButton/*HTML Node*/, extraData/*Object*/) {

  // Give all paymentMethod divs a disabled state
  chckt.toggleEnableAllPaymentMethods(false);

  // Hide the 'review' & 'show more payment methods' buttons
  chckt.toggleActionButton(false);
  chckt.toggleShowMorePMsButton(false);

  // Find parent element for the Payments list in the SDK
  var holder = document.body.querySelector('.chckt-payment-holder');

  // Create empty Review element and add to Payments list parent element
  var reviewDiv = document.createElement('div');
  reviewDiv.style.position = 'relative';
  reviewDiv.style.top = '20px';
  holder.appendChild(reviewDiv);

  // Add text to Review element
  var textDiv = document.createElement('div');
  textDiv.innerText = 'Review your order before it is final. By clicking "Pay" you agree to all terms & conditions';
  reviewDiv.appendChild(textDiv);

  // Add an 'edit order' button that on click will restore payments list to previous state (no Review element, 'review order' button)
  var editBtn = document.createElement('div');
  editBtn.innerHTML = '<span><u>Edit order</u></span>';
  editBtn.style.cursor = 'pointer';

  var editFn = function() {

    // Renable payment methods
    chckt.toggleEnableAllPaymentMethods(true);

    // Show 'show more payment methods' button (if it was visible)
    chckt.toggleShowMorePMsButton(true);

    // Show the original 'review order' button
    chckt.toggleActionButton(true);

    document.body.querySelector('.js-chckt-button-container').style.display = 'block';
    holder.removeChild(reviewDiv);
  };

  if( typeof editBtn.addEventListener === 'function' ) {
    editBtn.addEventListener( 'click', editFn );
  }else{
     if(editBtn.attachEvent) {
        editBtn.attachEvent( 'onclick', editFn );
     }
  }

  reviewDiv.appendChild(editBtn);

  // Add 'Pay' button to Review element
  // (This particular Pay button recreates the one in the SDK, with a loading animation when clicked)
  var payBtnHtmlStr = '<button type="button" class="chckt-button chckt-pm-list__button chckt-button--submit js-chckt-button--submit">';
  payBtnHtmlStr += '<span class="chckt-button__text">Pay</span>';
  payBtnHtmlStr += '<span class="chckt-button__loading-icon">';
  payBtnHtmlStr += '<div class="circle1"></div>';
  payBtnHtmlStr += '<div class="circle2"></div>';
  payBtnHtmlStr += '<div class="circle3"></div>';
  payBtnHtmlStr += '</span></button>';

  var payDiv = document.createElement('div');
  payDiv.innerHTML = payBtnHtmlStr;
  reviewDiv.appendChild(payDiv);

  var payBtn = reviewDiv.querySelector('.chckt-button--submit');

  var payFn = function() {

    // Remove text and edit btn
    reviewDiv.removeChild(textDiv);
    reviewDiv.removeChild(editBtn);
    reviewDiv.style.top = '0px';

    chckt.submitPaymentForm();

    // Add loading class to activate animatiion
    payBtn.className += 'chckt-pm-list__button--loading';
  };

  if(typeof payBtn.addEventListener === 'function') {
    payBtn.addEventListener('click', payFn);
  }else{
    if(payBtn.attachEvent) {
      payBtn.attachEvent('onclick', payFn);

  }

  return false;
};

beforePendingInitiation

In the following example the payment method remains visible on screen, with reduced opacity. The opacity of the Pay button is also reduced.

chckt.hooks.beforePendingInitiation = function(selectedPMNode/*HTML Node*/, extraData/*Object*/) {
  selectedPMNode.style.opacity = '0.2';
  extraData.actionButton.style.opacity = '0.5';
  return false;
}

afterPendingInitiation

Allows you to execute other tasks. Such as beforeComplete.

chckt.hooks.afterPendingInitiation = function() {
  return false;
}

beforeComplete

The following example shows a payload from an authorised result being directed through merchantwebsite.com to the verify endpoint. The PSP reference is then displayed.

chckt.hooks.beforeComplete = function(checkoutNode/*HTML Node (.chckt-sdk)*/, responseData/*Object*/) {
  if (responseData.resultCode.toLowerCase() === 'authorised') {
    $.ajax({
      url: 'http://merchantwebsite.com/verifyPayment.php',
      data: { payload: responseData.payload },
      dataType: 'json',
      method: 'POST',
      success:function(data) {
        var verifiedJsonObj = data;
        if(verifiedJsonObj.authResponse.toLowerCase() === 'authorised') {
          $(checkoutNode).html('<div style="color:blue;"> Verified! pspReference: ' + verifiedJsonObj.pspReference + '</div>')
        }
      },
      error: function(e) {}
    });
  }
  return false;
}

The following example shows a payload from an refused result being directed through merchantwebsite.com to the verify endpoint. The refusal reason is also displayed.

chckt.hooks.beforeComplete = function(checkoutNode/*HTML Node (.chckt-sdk)*/, responseData/*Object*/) {
  if (responseData.resultCode.toLowerCase() === 'refused') {
    $.ajax({
      url: 'http://merchantwebsite.com/verifyPayment.php',
      data: { payload: responseData.payload },
      dataType: 'json',
      method: 'POST',
      success: function(data) {
        var verifiedJsonObj = data;
        if (verifiedJsonObj.authResponse.toLowerCase() === 'refused') {
          $(checkoutNode).html('<div style="color:red;">Refused! refusal reason: "+verifiedJsonObj.additionalData.refusalReasonRaw+"</div>')
        }
      },
      error: function(e) {}
    });
  }
  return false;
}

beforePendingRedirect

The following example keeps the selected payment method displayed, at a reduced opacity. The opacity of the Pay button is also reduced.

chckt.hooks.beforePendingRedirect = function(selectedPMNode/*HTML Node*/, extraData/*Object*/) {
  selectedPMNode.style.opacity = '0.2';
  extraData.actionButton.style.opacity = '0.2';
  return false;
};

beforeRedirect

This example shows how you can configure the Checkout form to redirect the shopper.

chckt.hooks.beforeRedirect = function() {
  // Add your logic here
  return false;
}

handleError

This example shows how you can write an unexpected error message to the console.

chckt.hooks.handleError = function(node, paymentMethod, errorResponse) {
  console.log("Node: ", node);
  console.log("Payment method: ", paymentMethod);
  console.log("Error response: ", errorResponse);
  return false;
}