Hosted Payment Session: API Reference

The Hosted Payment Session with JavaScript model uses the following JavaScript methods and objects to return a session identifier containing the payer's card details. You must submit the returned session identifier to your web server to initiate a payment or a storage transaction. For more information, see Perform an Operation Using the Session.

Calling the methods described below does not actually initiate a payment or a storage transaction.

Methods

HostedForm.setMerchant( )

Sets the merchant account that will be used to transact.

setMerchant(merchantID)

Parameters:

merchantId
Required. The merchant identifier provided to you by CommWeb payment gateway.

Returns:

Void

HostedForm.createSession( )

Sends a request to create a session and update it with card details.

createSession(sessionDetails, createSessionCallback)

Parameters:

sessionDetails
Required. The object parameter to specify the card details.

createSessionCallback
Required. The function to handle the response. Defined as createSessionCallback = function(createSessionResponse)

HostedForm.updateSession( )

Sends a request to create or update a session.

updateSession([sessionId], sessionDetails, updateSessionCallback)

Parameters:

sessionId
Optional. If you pass the sessionId parameter, then the details for the session, if it exists, are updated. If you do not pass a session identifier, a new session is created.

sessionDetails
Required. The object parameter to specify the card details.

updateSessionCallback
Required. The function to handle the response. Defined as updateSessionCallback = function(updateSessionResponse)

HostedForm.showVisaCheckout( )

Launches the Visa Checkout Lightbox and populates the payment details from the interaction into a payment session.

showVisaCheckout([sessionId], options, callback)

Parameters:

sessionId
Optional. An identifier for a payment session, if none is provided, a new payment session is created.

options
Required. Allows you to control the options offered in the Visa Checkout Lightbox. If you do not wish to control the options, you may set it to null or an empty object.

Supported Options
Option Data Type Description Values
options.acceptedCards enum Controls the type of cards that can be selected by the payer in the Visa Checkout Lightbox. MASTERCARD
AMEX
DISCOVER
VISA
options.paymentConfirmation enum Controls if the confirmation button on the last page displays as "Pay" or "Continue" CONFIRM_AT_PROVIDER - displays 'Pay' on the Visa Checkout Lightbox
CONFIRM_AT_MERCHANT - displays 'Continue' on the Visa Checkout Lightbox
options.paymentConfirmationMessage String The message displayed to the payer next to the confirmation button in the Visa Checkout Lightbox. Provide this text in the language defined in options.locale. Continue to the merchant to complete your purchase
options.merchant.logo URL The merchant logo displayed in the Visa Checkout Lightbox https://test.te
options.merchant.displayName String The merchant name you want to be displayed as the default message on the Visa Checkout Lightbox. Typically, this is the name of your company. the merchant
options.locale String Determines the locale used to display the Visa Checkout Lightbox. By default, the locale of the payer's browser en_us
en_au
en_ca
fr_ca
options.country 3-letter ISO country code Determines the country flag displayed at the top right-hand side of the Visa Checkout Lightbox. AUS
USA
options.order.amount Decimal Displays an order amount in the Visa Checkout Lightbox 10.50, 200.00
options.order.currency 3-letter ISO currency code Displays an order currency in the Visa Checkout Lightbox

USD
AUD

callback
Required. A function to retrieve the result of the Lightbox interaction.

Objects

sessionDetails

The required sessionDetails object parameter contains card details to store in the newly created session. It's not mandatory to specify all the fields — you can collect partial card details; however, cardExpiryMonth and cardExpiryYear are mandatory if either of them is specified.


Fields:

String cardNumber
Optional. Credit card number as printed on the card. Accepts up to 30 characters including digits and the symbols '-' and ' ' as input.

String cardSecurityCode
Optional. Card verification code, as printed on the back or front of the card.

String cardExpiryMonth
Required if value for cardExpiryYear is specified. Month, as shown on the card. Months are numbered January=1, through to December=12.

String cardExpiryYear
Required if value for cardExpiryMonth is specified. Year, as shown on the card.

Example

 var sessionDetails = function() {
    return {
        cardNumber: document.getElementById('cardNumber').value,
        cardSecurityCode: document.getElementById('cardSecurityCode').value,
        cardExpiryMonth: document.getElementById('expiryMonth').value,
        cardExpiryYear: document.getElementById('expiryYear').value
        }
      }

createSessionResponse/updateSessionResponse

The response object returned by the CommWeb payment gateway in response to HostedForm.createSession( )/HostedForm.updateSession( ) call.


Fields:

String status
The overall status of the HostedForm.createSession( )/HostedForm.updateSession( ) request as returned by CommWeb payment gateway.

String session
The session identifier containing the card details. You must use this identifier in place of card details when initiating a payment transaction.

String cardBrand
The brand name used to describe the card that is recognized and accepted globally. For many major card types this will match the scheme name. In some markets, a card may also be co-branded with a local brand that is recognized and accepted within its country/region of origin (see cardLocalBrand).
You may use this information to support surcharging decisions. This information is gathered from 3rd party sources and may not be accurate in all circumstances.

String cardScheme
The card scheme for the card used in the HostedForm.createSession( )/HostedForm.updateSession( ) request.

String cardFundingMethod
The method used by the payer to provide the funds for the payment.
You may use this information to support surcharging decisions. This information is gathered from 3rd party sources and may not be accurate in all circumstances.

String cardLocalBrand
The brand name used to describe a card that is recognized and accepted within its country/region of origin. The card may also be co-branded with a brand name that is recognized and accepted globally (see cardBrand).
You may use this information to support surcharging decisions. This information is gathered from 3rd party sources and may not be accurate in all circumstances.

Object fieldsInError
An object whose properties match the names of the fields in error. The values indicate the error cause.

Example

 {
  "status":"ok",
  "session":"SESSION000264159551414428148515",
  "cardFundingMethod":"credit", //possible values: CHARGE, CREDIT, DEBIT, UNKNOWN 
  "cardScheme":"visa",// possible values AMEX, DINERS_CLUB, DISCOVER, JCB, MASTERCARD, UATP, VISA, OTHER 
  "cardBrand":"visa"  //possible values: AMEX, DINERS_CLUB, DISCOVER, JCB, MAESTRO,  MASTERCARD, VISA, UATP, LOCAL_BRAND_ONLY, UNKNOWN
 }

fieldsInError

The fieldsInError object parses field errors returned in the response. The errors are returned in the following format: {"field_name":"error_code", ...}, for example, {cardNumber:"invalid", cardExpiryYear:"missing"}

Fields:

String cardNumber
Credit card number as passed in the sessionDetails object.

String cardSecurityCode
Card verification code, as passed in the sessionDetails object.

String cardExpiryMonth
Expiry month, as passed in the sessionDetails object.

String cardExpiryYear
Expiry year, as passed in the sessionDetails object.

Enumeration Values

String invalid
Indicates the field is invalid.

String missing
Indicates a mandatory field is missing.

Example

 //fields_in_error example
  {
	"status":"fields_in_error",
	"fieldsInError": {
	"cardExpiryYear":"invalid",
	"cardSecurityCode":"invalid",
	"cardExpiryMonth":"invalid",
	"cardNumber":"invalid"
  	}
  }

Copyright © 2020 Commonwealth Bank of Australia