Hosted Payment Session: API Reference

Sets the merchant account that will be used to transact.

setMerchant(merchantID)

Parameters:

merchantId
Required. The merchant identifier provided to you by Mastercard Payment Gateway.

Returns:

Void

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)

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)

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.

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

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
        }
      }

The response object returned by the Mastercard 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 Mastercard 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
 }

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"
  	}
  }