Hooks are custom JavaScript functions provided by the merchant that can be “hooked-up” (hence the name) to a certain point the payment workflow. In other words, using Check-out Hooks, it is possible to subscribe to certain events (as per the table below) by providing your own JavaScript function. The function then gets called by Check-out, once the event occurs.

When to Use Hooks

A typical use case is when a merchant wants to make sure that all the goods that the customer is about to buy are on stock and prevent the payment from completing if not.

Events Available for Subscribing

beforeCompleteHook

If you subscribe for this event, your hook function will get called when the customer clicks the Complete button, right before the actual logic is executed.

Your function must have the following signature:

function (result, purchaseId) {
    // Your implementation
}

When the event occurs, we will pass the following parameters into your function:

1. result: an object with two methods: continue() and cancel().
2. purchaseId: a string with the unique Purchase ID.

If you subscribe for this event, it is your responsibility to decide whether to continue with the flow or cancel it. The decision has to be made by calling either the continue or the cancel functions on the result object passed into your function.

cancel(customMessage) function – has an optional string input parameter customMessage that can be used to replace default generic user message which is displayed to user when .cancel() function is called. The default generic user message is: “Order could not be confirmed. Please reload shopping cart.” See example on the bottom of the page.

Result will contain a data object (result.message.data) with following properties that can be checked:

deliveryZip (if no additional delivery address has bee choosen this property contains the zipCode to were the customer wants the good shipped.

selectedPaymentMethod: values Invice,Loan, DirectInvoice,PartPayment,PayPal, Card. Swish, MobilePay, Vipps, MasterPass, DirectBank.

deliveryCountry: example values are Sweden, Norway, Denmark, Finland, Germany, Poland…

message:
type: "question"
question: "beforeCompleteHook"
data:
externalId: "fc26991eab230d217dec2a631c0165a5"
selectedPaymentMethod: "Invoice"
deliveryZip: "12345"
deliveryCountry: "Sweden"

The decision can (and should) be made asynchronously if it involves an AJAX request. E.g., if you use the hook to verify that all the products that the customer is going to buy are on stock, you will probably need an answer from your back-end. In that case, you should just fire an AJAX request inside the hook function and call either result.continue() or result.cancel() after the AJAX call completes, in its callback.

A loading animation is shown while Check-out is waiting for your decision. If you fail to call either continue or cancel, the loading animation will be shown indefinitelly and the customer will not be able to complete the payment.

updateDeliveryAddressHook

Called when the customer changes the delivery address. Your hook function must have the following signature:

function (result, customerInfo) {
    // Your implementation
}

When the event occurs, we will pass the following parameters into your function:

1. result: an object with two methods: continue() and cancel().
2. customerInfo: an object with the structure as described below that describes the new delivery address provided by the customer:

{
    FirstName: string,
    LastName: string,
    Address: string,
    ZipCode: string,
    City: string,
    Country: string
}

The same general rules applies as for the beforeCompleteHook.

personalInfoLoadedHook

If you subscribe for this event, your hook function will get called when the customer personal information is loaded.

This can happen for example if:

• customer personal info is loaded automatically
• customer fills in the personal info manually and click “Next” button

Your hook function must have the following signature:

function (customerInfo) {
    // Your implementation
}

CustomerInfo will contain a data object with following properties that can be checked:

• zipCode: invoicing zip code, example value “25669”
• country: invoicing country name, example value “Sweden”

{
  "zipCode": "25669",
  "country": "Sweden"
}

Example

var options = {
  // ID of the <div> inside which to render the form
  divId: 'checkOutDiv',
  // The Purchase ID obtained in the previous step
  purchaseId: '489ea341e23941089e6d0378c708512a',
 
  // Other important parameters omitted for readability.
 
  beforeCompleteHook: function (result, purchaseId) {
    checkIfAllProductsAreOnStock(purchaseId).andThenWhenTheAjaxFinishes(
      function (areOnStock) {
        if (areOnStock) {
          result.continue();
        } else {
          result.cancel('Sorry, the product is sold out.');
        }
      },
    );
  },
 
  updateDeliveryAddressHook: function (result, customerInfo) {
    if (isAddressOK(customerInfo)) {
      result.continue();
    } else {
      result.cancel();
    }
  },
 
  personalInfoLoadedHook: function (customerInfo) {
    prefillPickupLocation(customerInfo);
  },
};
 
AvardaCheckOutClient.init(options);