Hyper Widget

In this Article:

  1. initWidget() Method
  2. onApprove() Method
  3. onValidPreference() Method
  4. onError() Method

API Methods

initWidget()

This method is used to specify an operation configuration for the Hyper widget.

Input
FieldTypeRequiredNotes
configObjectYESRefer to widget config.
Example
//payment gateways
var gateways = [
    {type:"card",gatewayId:"<your-gateway-id>"},
    {type:"zipPay",gatewayId:"<zipPay-gateway-id>"},
    {type:"stripeGP",gatewayId:"<googlepay-gateway-id>"},
    {type:"stripeAP",gatewayId:"<applepay-gateway-id>"},
]

//Hyper config
var config = {
    //remove useSandbox declaration for production
    publicKey:"<hyper-public-key>",
    useSandbox: true,
    gateways: gateways,
};

document.addEventListener("DOMContentLoaded", function (event) {
    var widget = hyper.initWidget(config);
    // continue widget configuration
    // ....
});

onApprove()

This listener is called once the user has agreed to accept the Charge and corresponding a vaultToken is available for the use.

Response
FieldTypeRequiredNotes
vaultTokenStringYESUsed to create a Charge or Subscription linked to the user’s payment source
traceIdStringYESIf provided by Hyper API. Use it when requesting support about an issue related to Hyper.
userDetailObjectYESRefer to userDetail
Example
document.addEventListener("DOMContentLoaded", function (event) {
    var widget = hyper.initWidget(config);
    // continue widget configuration
    // ....
    widget.onApprove = function(res) {
        //replace this with code to handle successful pay authroization
        console.log('Response:', res);
    };
});

onValidPreference()

This method is called when any user preference information is available to personalise the checkout experience.

Response
FieldTypeRequiredNotes
skuStringNOIf available, provides user preference information. For e.g. preferred product SKU
Example
document.addEventListener("DOMContentLoaded", function (event) {
    var widget = hyper.initWidget(config);
    // continue widget configuration
    // ....
    //if a valid user profile is available, it can be used to optimize the checkout experience
    widget.onValidPreference = function(data) {
        //select the preferred product from the card
        console.log('Preferred SKU:', data.sku);
    };
});

onError()

This listener passes any error that occurs during widget operation.

Response
FieldTypeRequiredNotes
typeStringYESRefer to Error Types.
reasonStringYESRefer to Error Types.
traceIdStringYESIf provided by Hyper API. Use it when requesting support about an issue related to Hyper.
Example
document.addEventListener("DOMContentLoaded", function (event) {
    var widget = hyper.initWidget(config);
    // continue widget configuration
    // ....
    //when an unrecoverable error occurs
    widget.onError = function(err) {
        //cutomize this section to take recovery action
        console.log('Error occurred:', err);
    };
});
Error Types
TypeReason
CONFIG_GATEWAY_ID_INVALIDOne or more gatewayId contains invalid value.
CONFIG_GATEWAY_ID_REQUIREDgatewayId is missing or empty on one or more of the gateway entries.
CONFIG_GATEWAY_TYPE_REQUIREDGateway type is missing or empty on one or more of the gateway entries.
CONFIG_INVALID_PUBLIC_KEYMerchant publicKey is invalid.
CONFIG_MISSING_GATEWAYSgateways is missing from the configuration.
CONFIG_MISSING_PUBLIC_KEYpublicKey is missing from the configuration.
ORDER_NULLThe userOrder set with setOrder() method is null or undefined.
ORDER_NO_ITEMS_FOUNDNo items found in the order.
ORDER_TOTAL_AMOUNT_UNDEFINEDPlease check because the order total amount is zero or undefined.
ORDER_ITEM_AMOUNT_UNDEFINEDOne or more item amount is zero or undefined.
ORDER_ITEM_QUANTITY_UNDEFINEDOne or more item has a quantity of zero or undefined.
ORDER_TOTAL_AMOUNT_NOT_EQUALTotal amount is not equal to the total amount of items in the order.

API Objects

config

Hyper widget configuration

Fields
NameTypeRequiredNotes
publicKeyStringYESYour account’s public key, available from Hyper Merchant portal.
useSandboxBooleanYESIf true, Sandbox environment is used for operation. Default is false
gatewaysObjectYESDefines payment Gateways to use. At least one gateway is required.
gateways
NameTypeRequiredNotes
typeStringYESSee Gateway Types for Hyper supported gateways.
gatewayIdStringYESYour the gateway’s ID, available from Hyper Merchant portal.
gatewayType
ValueTypeRequiredNotes
cardStringYESUse for all credit card processors like Stripe, eWay, etc.
zipPayStringYESUse for Zip payments.
stripeGPStringYESSupport to be released in Q2 2021.
stripeAPStringYESSupport to be released in Q2 2021.

userDetail

Contains User’s details provided to Hyper. The checkout page can use these to complete the order process.

Fields
NameTypeRequiredNotes
fullNameStringYESE.g. John Stark
mobileStringYESE.g. +61400400400
emailStringYESE.g. john.stark@email.com

userOrder

Hyper order details.

Fields
NameTypeRequiredNotes
amountNumberYESTotal order amount, for e.g. 10.00
currencyStringYESOrder currency, for e.g. AUD
referenceStringYESOrder or quote reference, for e.g. Q-12345
itemsObjectYESRefer to userOrderItems.

userOrderItems

Hyper order item details.

Fields
NameTypeRequiredNotes
nameStringYESItem’s brief description, for e.g. its name Gadget ABC
amountNumberYESItem price, for e.g. 10.00
quantityNumberYESQuantity being purchased, for e.g. AUD
referenceStringYESItem reference, for e.g. SKU data A123 stealth drone