Functions

configure( )

The configure( ) function allows you to configure Hosted Session interactions. You can collect payment details using proxy payment fields hosted by Tyro eCommerce Payment Gateway and rendered within an iFrame.

This function can be used to initiate the Multiple Hosted Session functionality.

Usage

PaymentSession.configure(configuration, [scope])

Example

PaymentSession.configure({
    fields: {
        // Attach hosted fields to your payment page
           card: {
              number: "#card-number",
              securityCode: "#security-code",
              expiryMonth: "#expiry-month",
              expiryYear: "#expiry-year",
              nameOnCard: "#cardholder-name"
           },
           giftCard: {
                  number: "#gift-card-number",
                  pin: "#gift-card-pin"
           },
           ach: {
                  accountType: "#ach-account-type",
                  bankAccountHolder: "#ach-account-holder",
                  bankAccountNumber: "#ach-account-number",
                  routingNumber: "#ach-routing-number"
           }
    },
    frameEmbeddingMitigation: ["javascript", "x-frame-options", "csp"],
    callbacks: {
        initialized: function(response) {
            //handle initialization response
            if(response.status === "ok") {
                // ...
            } else if (response.status === "system_error") {
                console.log(response.message);
            }
        },
        formSessionUpdate: function(response) {
            //handle session update response
        },
        visaCheckout: function(response) {
            //handle Visa Checkout response
        },
        amexExpressCheckout: function(response) {
            // handle Amex Express Checkout response
		}
    },
    interaction: {
        displayControl: {
            formatCard: "EMBOSSED",
            invalidFieldCharacters: "REJECT"
        }
    },
    order: {
        amount: 10.00,
        currency: "AUD"
    },
    wallets: {
        visaCheckout: {
            enabled: true
            // Add Visa Checkout API specific attributes here
            countryCode: "AU",
            displayName: "Display name",
            locale: "en_au",
            logoUrl: "http://logo.logo",
            payment: {
                cardBrands: [
                    "VISA"
                ]
            },
            review: {
                buttonAction: "Pay",
                message: "Message"
            },
            shipping: {
                acceptedRegions: [
                    "AU"
                ],
                collectShipping: true
            }
        }
       amexExpressCheckout: {
        enabled: true,
        // Add Amex Express Checkout API specific attributes here
        initTags: {
        "theme": "responsive",
        "env": "qa",
        "disable_btn": "false",
        "button_color": "light",
        "client_id": "398f9858-5567-434f-a929-242d6fc7fea8",
        "display_type":"custom"  // IF USING OWN IMAGE FOR BUTTON
        }
      }
   }
})

Arguments

configuration Object

The object parameter to specify the configuration for the Hosted Session interaction.

object

updateSessionFromForm()

Sends a request to store the input from the hosted field(s) for the specified payment type, into the session. The supported payment types are ‘card’, ‘ach’, ‘giftCard’. If paymentType === ‘giftCard’ then you must provide the local card brand as an additional parameter. The status of the request is returned in the formSessionUpdate callback function defined in the PaymentSession.configure( ) function.

This function supports the Multiple Hosted Session functionality.

Usage

PaymentSession.updateSessionFromForm(paymentType, [localBrand, [scope]])

Example


    PaymentSession.configure({
        callbacks: {
            formSessionUpdate: function(response) {
                // HANDLE RESPONSE FOR UPDATE SESSION
                if (response.status) {
                    if ("ok" == response.status) {
                        console.log("Session updated with data: " + response.session.id);

                        //check if the security code was provided by the user
                        if (response.sourceOfFunds.provided.card.securityCode) {
                            console.log("Security code was provided.");
                        }

                        //check if the user entered a MasterCard credit card
                        if (response.sourceOfFunds.provided.card.scheme == 'MASTERCARD') {
                            console.log("The user entered a MasterCard credit card.")
                        }
                    } else if ("fields_in_error" == response.status)  {

                        console.log("Session update failed with field errors.");
                        if (response.errors.cardNumber) {
                            console.log("Card number invalid or missing.");
                        }
                        if (response.errors.expiryYear) {
                            console.log("Expiry year invalid or missing.");
                        }
                        if (response.errors.expiryMonth) {
                            console.log("Expiry month invalid or missing.");
                        }
                        if (response.errors.securityCode) {
                            console.log("Security code invalid.");
                        }
                    } else if ("payment_type_required" == response.status)  {
                    		console.log("Payment type is required. Valid values are 'card', 'ach' or 'giftCard'.");
					} else if ("giftCard_type_required" == response.status)  {
                    		console.log("Gift card payment type requires an expected local brand parameter.");
                    } else if ("request_timeout" == response.status)  {
                        console.log("Session update failed with request timeout: " + response.errors.message);
                    } else if ("system_error" == response.status)  {
                        console.log("Session update failed with system error: " + response.errors.message);
                    }
                } else {
                    console.log("Session update failed: " + response);
                }
            }
        }
    });

    // Response handling is done in the callbacks.formSessionUpdate callback function
    PaymentSession.updateSessionFromForm('card');
JSON Example for Session Update Response
// status can be one of the following: ok, fields_in_error, system_error, request_timeout
 
// An error response (fields_in_error)
{
    "status": "fields_in_error",  
    "session": {
        "id": "SESSION000218450948092491657986"
    },
    "errors": {
        "cardNumber": "invalid",
        "securityCode": "invalid"  
    },
    version: "36"
}
 
// An error response (system_error)
{
    "status": "system_error",  
    "session": {
        "id": "SESSION000218450948092491657986"
    },
    "errors": {
        "message": "System error message." 
    },
    "version": "36"
}
  
// An error response (request_timeout)
{
    "status" : "request_timeout", 
    "session": {
        "id": "SESSION000218450948092491657986"
    },
    "errors": {
        "message": "Request timeout error message."
    },
    "version": "36"
} 
 
// An ok response
{
    "status":"ok",
    "merchant": "TESTMERCHANT",
    "session": {
        "id": "SESSION000218450948092491657986"
        "updateStatus":"SUCCESS",
        "version":"e3f144ce02"
    },
    "sourceOfFunds": {
        "provided": {
            "card": {
                "brand": "MASTERCARD",
                "expiry": {
                    "month": "5",
                    "year": "21"
                },
                "fundingMethod": "DEBIT",
                "nameOnCard": "John Smith",
                "number": "512345xxxxxx8769",
                "scheme": "MASTERCARD"
            }
        },
        "type": "CARD"
    },   
    "version": "36"
}
Arguments
object
paymentType
string
localBrand
string
scope
string

setFocus()

Instructs the specified hosted field in the iFrame to gain focus.

This function supports the Multiple Hosted Session functionality.

Usage

PaymentSession.setFocus(<HostedFieldRole>, [scope])

Example

PaymentSession.setFocus(‘card.number’)`;

Arguments

<HostedFieldRole>String

The field role for the card field rendered in an iFrame and hosted on the Tyro eCommerce Payment Gateway.

Valid field roles: ‘card.number’,‘card.securityCode’, ‘giftCard.number’, ‘giftCard.pin’, ‘ach.bankAccountNumber’, ‘ach.bankAccountHolder’, ‘ach.routingNumber’

scope String

The optional named instance of a card payment data set within a session.

Return Value

None

setHoverStyle()

Sets the styling for the hosted field to the supplied styling attributes when the payer hovers over the hosted field in the iFrame.

This function supports the Multiple Hosted Session functionality.

Usage

PaymentSession.setHoverStyle([<HostedFieldsRole>], styles, [scope])

Example

PaymentSession.setHoverStyle(["card.number","card.securityCode"], {
  borderColor: 'red',
  borderWidth: '3px'
});

Arguments

<HostedFieldsRole>Array

An array of field roles for the hosted card fields, to be styled when the focus is gained.

Valid array of field roles: [‘card.number’,‘card.securityCode’, ‘giftCard.number’, ‘giftCard.pin’, ‘ach.bankAccountNumber’, ‘ach.bankAccountHolder’, ‘ach.routingNumber’]

styles Object

An object containing JavaScript CSS properties.

scope String

The optional named instance of a card payment data set within a session.

Return Value

None

setFocusStyle()

Sets the styling for the hosted field to the supplied styling attributes when focus on the hosted field in the iFrame is gained.

Usage

PaymentSession.setFocusStyle([<HostedFieldsRole>], styles, [scope])

Example

PaymentSession.setFocusStyle(["card.number","card.securityCode"], {
  borderColor: 'red',
  borderWidth: '3px'
});

Arguments

<HostedFieldsRole> Array

An array of field roles for the hosted card fields, to be styled when the focus is gained.

Valid array of field roles: [‘card.number’,‘card.securityCode’, ‘giftCard.number’, ‘giftCard.pin’, ‘ach.bankAccountNumber’, ‘ach.bankAccountHolder’, ‘ach.routingNumber’]

styles Object

An object containing JavaScript CSS properties.

scope String

The optional named instance of a card payment data set within a session.

Return Value

None

Callbacks

onBlur Callback

The onBlur( ) callback invokes the function registered against this event when the hosted field in the iFrame has lost focus.

Usage

PaymentSession.onBlur([<HostedFieldsRole>], function(selector), [scope])

Example

PaymentSession.onBlur(['card.number','card.securityCode'], function(selector) { //handle blur event });

Arguments

<HostedFieldsRole> Array

An array of field roles for the hosted fields where the event occurred.

Valid array of field roles: [‘card.nameOnCard’, ‘card.number’, ‘card.expiryMonth’, ‘card.expiryYear’, ‘card.securityCode’, ‘giftCard.number’, ‘giftCard.pin’, ‘ach.bankAccountNumber’, ‘ach.bankAccountHolder’, ‘ach.routingNumber’]

<callbackFunction> Function

The callback function invoked with the selector for the field whose proxy triggered the event.

scope String

The optional named instance of a card payment data set within a session.

Return Value

None

onChange Callback

The onChange( ) callback invokes the function registered against this event when the input value in the hosted field in the iFrame has changed.

Usage

PaymentSession.onChange([], function(selector), [scope])

Example

PaymentSession.onChange(['card.number','card.securityCode'], function(selector) { //handle change event });

Arguments

<HostedFieldsRole> Array

An array of field roles for the hosted fields where the event occurred.

Valid array of field roles: [‘card.nameOnCard’, ‘card.number’, ‘card.expiryMonth’, ‘card.expiryYear’, ‘card.securityCode’, ‘giftCard.number’, ‘giftCard.pin’, ‘ach.bankAccountNumber’, ‘ach.bankAccountHolder’, ‘ach.routingNumber’]

<callbackFunction> Function

The callback function invoked with the selector for the field whose proxy triggered the event.

scope String

The optional named instance of a card payment data set within a session.

Return Value

None

onMouseOut Callback

The onMouseOut( ) callback invokes the function registered against this event when the payer’s mouse pointer moves away from the hosted field in the iFrame.

Usage

PaymentSession.onMouseOut([<HostedFieldsRole>], function(selector), [scope])

Example

PaymentSession.onMouseOut(['card.number','card.securityCode'], function(selector) { //handle mouse out event });

Arguments

<HostedFieldsRole>Array

An array of field roles for the hosted fields where the event occurred.

Valid array of field roles: [‘card.nameOnCard’, ‘card.number’, ‘card.expiryMonth’, ‘card.expiryYear’, ‘card.securityCode’, ‘giftCard.number’, ‘giftCard.pin’, ‘ach.bankAccountNumber’, ‘ach.bankAccountHolder’, ‘ach.routingNumber’]

<callbackFunction> Function

The callback function invoked with the selector for the field whose proxy triggered the event.

scope String

The optional named instance of a card payment data set within a session.

Return Value

None

onMouseOver() Callback

The onMouseOver( ) callback invokes the function registered against this event when the payer’s mouse pointer moves over the hosted field in the iFrame.

Usage

PaymentSession.onMouseOver([<HostedFieldsRole>], function(selector), [scope])

Example

PaymentSession.onMouseOver(['card.number','card.securityCode'], function(selector) { //handle mouse over event });

Arguments

<HostedFieldsRole> Array

An array of field roles for the hosted fields where the event occurred.

Valid array of field roles: [‘card.nameOnCard’, ‘card.number’, ‘card.expiryMonth’, ‘card.expiryYear’, ‘card.securityCode’, ‘giftCard.number’, ‘giftCard.pin’, ‘ach.bankAccountNumber’, ‘ach.bankAccountHolder’, ‘ach.routingNumber’]

<callbackFunction>Function

The callback function invoked with the selector for the field whose proxy triggered the event.

scope String

The optional named instance of a card payment data set within a session.

Return Value

None

onFocus( ) Callback

The onFocus( ) callback invokes the function registered against this event when the hosted field in the iFrame has gained focus.

Usage

PaymentSession.onFocus([<HostedFieldsRole>],function(selector), [scope])

Example

PaymentSession.onFocus(['card.number', 'card.securityCode'], function(selector) { //handle focus event });

Arguments

<HostedFieldsRole> Array

An array of field roles for the hosted fields where the event occurred.

Valid array of field roles: [‘card.nameOnCard’, ‘card.number’, ‘card.expiryMonth’, ‘card.expiryYear’, ‘card.securityCode’, ‘giftCard.number’, ‘giftCard.pin’, ‘ach.bankAccountNumber’, ‘ach.bankAccountHolder’, ‘ach.routingNumber’]

<callbackFunction>Function

The callback function invoked with the selector for the field whose proxy triggered the event.

scopeString

The optional named instance of a card payment data set within a session.

Return Value

None