configure()

Allows you to define for which of the input fields you are presenting to the payer on your payment page you want the gateway to collect the payment details. These fields will then be proxied using iFrames hosted by the gateway. The result of the request is returned in the initialized callback.

Usage

PaymentSession.configure(configuration, [scope])

Example

PaymentSession.configure({
    session: "<your_session_ID>",
    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",
                  bankAccountNumberConfirmation: "#ach-account-number-confirmation",
                  routingNumber: "#ach-routing-number"
           },
           directDebitCanada: {
                  accountType: "#account-type",
                  bankAccountHolder: "#bank-account-holder",
                  bankAccountNumber: "#bank-account-number",
                  transitNumber: "#transit-number",
                  financialInstitutionNumber: "#financial-institution-number",
                  bankAccountNumberConfirmation: "#bank-account-number-confirmation"
            }
        },
    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
        }
    },
    interaction: {
        displayControl: {
            formatCard: "EMBOSSED",
            invalidFieldCharacters: "REJECT"
        }
    }
})
  

Arguments

configuration Object COMPULSORY

Specifies the configuration for the Hosted Session interaction.

Fields:

session String

The unique identifier for the session. Before calling configure() you must create a session using the Create Session request. The API version you use when submitting the Create Session request must be the same as the API version of the session.js you are using.

fields Object OPTIONAL

An object containing selectors for the fields you want to replace with the corresponding proxy fields. Hosted Session will replace these fields with an iFrame and store any content provided by the payer in these fields in a Payment Session. The proxy fields will have the same look and feel as the replaced fields.

card String OPTIONAL

A container for the card fields.

number String OPTIONAL

A selector for the card number field.

securityCode String OPTIONAL

A selector for the security code field.

expiryMonth String OPTIONAL

A selector for the expiry month field.

expiryYear String OPTIONAL

A selector for the expiry year field.

nameOnCard String OPTIONAL

A selector for the cardholder name field.

giftCard String OPTIONAL

A container for the gift card fields.

number String OPTIONAL

A selector for the gift card number field.

pin String OPTIONAL

A selector for the gift card PIN field.

ach String OPTIONAL

A container for the Automated Clearing House (ACH) payment fields.

accountType String OPTIONAL

A selector for the ACH account type field.

bankAccountHolder String OPTIONAL

A selector for the ACH account holder field.

bankAccountNumber String OPTIONAL

A selector for the ACH account number field.

bankAccountNumberConfirmation String OPTIONAL

A selector for the ACH account number confirmation field.

routingNumber String OPTIONAL

A selector for the ACH routing number field.

directDebitCanada Object OPTIONAL

A container for the Direct Debit Canada payment fields.

accountType Enum OPTIONAL

bankAccountHolder String OPTIONAL

A selector for the name of the bank account holder, as it appears on the account at the receiving financial institution.

bankAccountNumber String OPTIONAL

A selector for the identifier of the bank account at the receiving financial institution.

financialInstitutionNumber String OPTIONAL

A selector for the identifier of the receiving financial institution.

transitNumber String OPTIONAL

A selector for the transit number identifying the branch of the receiving financial institution where the bank account is held.

bankAccountNumberConfirmation String OPTIONAL

A selector for the bank account number confirmation field. Allows you to request an additional "bank account number confirmation" field to be displayed. Hosted Session will validate if the bankAccountNumber and bankAccountNumberConfirmation fields match.If they do not match then an error is returned in the validate function and onValidityChange callback.

frameEmbeddingMitigation String COMPULSORY

Specifies the mitigation option(s) for clickjacking prevention. For more information, see Implementing a Hosted Session Integration.

interaction Object OPTIONAL

Controls the payer's interaction with the payment process.

displayControl Object OPTIONAL

Controls the visibility of, and payer interaction with, the displayed information.

formatCard Enum OPTIONAL

invalidFieldCharacters Enum OPTIONAL

lineOfBusiness String OPTIONAL

Your Payment Services Provider might have configured your merchant profile to support several lines of business. Each line of business can have different payment parameters, such as bank account, supported cards or such. For example, lineOfBusiness = TICKET_SALES can have a different bank account from lineOfBusiness = MERCHANDISING. One line of business on your profile might be "null". To use that, do not provide the lineOfBusiness field.

callbacks Object

Specifies the functions that will be invoked for various Hosted Session events.

initialized Function COMPULSORY

This function is invoked after the configure() function and informs you about the outcome of that function.

Arguments

The function will be invoked with the following object:

response object OPTIONAL

response.status Enum OPTIONAL

response.message String OPTIONAL

Textual description of the error. Only returned if response.status is SYSTEM_ERROR.

Return Value : None

formSessionUpdate Function COMPULSORY

This function is invoked after the updateSessionFromForm() function and informs you about the outcome of the attempt to update the session with the payment details collected in the Hosted Session fields.

Arguments

The function will be invoked with the following object:

response object OPTIONAL

response.status Enum OPTIONAL

merchant Alphanumeric + additional characters OPTIONAL

The unique identifier issued to you by your payment provider.

session object OPTIONAL

Details about the session that has been updated with the payment details.

session.id ASCII TEXT OPTIONAL

Identifier of the session.

session.updateStatus String OPTIONAL

sourceOfFunds Object OPTIONAL

Information about the payment type selected by the payer for this payment and the source of the funds.

sourceOfFunds.provided Object OPTIONAL

Information about the source of funds when it is directly provided (as opposed to via a token or session).

sourceOfFunds.provided.ach Object OPTIONAL

For ACH payments, the details about the payers bank account used for the payment as well as the type of ACH payment are provided in this parameter group.

sourceOfFunds.provided.ach.accountType Enumeration OPTIONAL

An indicator identifying the type of bank account.

sourceOfFunds.provided.ach.bankAccountHolder String OPTIONAL

The name of the bank account holder, as it appears on the account at the receiving financial institution.

sourceOfFunds.provided.ach.bankAccountNumber Alphanumeric + additional characters OPTIONAL

The identifier of the bank account at the receiving financial institution.

sourceOfFunds.provided.ach.routingNumber Digits OPTIONAL

The identifier of the receiving financial institution.

sourceOfFunds.provided.ach.secCode Enumeration OPTIONAL

Identifies the Standard Entry Class (SEC) code to be sent to the issuer.

sourceOfFunds.provided.card Object OPTIONAL

Details about the card using for payment.

sourceOfFunds.provided.card.brand Enumeration OPTIONAL

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 card.localBrand). 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.

sourceOfFunds.provided.card.expiry Object OPTIONAL

Expiry date, as shown on the card.

sourceOfFunds.provided.card.expiry.month Digits OPTIONAL

Month, as shown on the card.

sourceOfFunds.provided.card.expiry.year Digits OPTIONAL

Year, as shown on the card.

sourceOfFunds.provided.card.fundingMethod Enumeration OPTIONAL

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.

sourceOfFunds.provided.card.nameOnCard String OPTIONAL

The cardholder's name as printed on the card.

sourceOfFunds.provided.card.scheme Enumeration OPTIONAL

The organization that owns a card brand and defines operating regulations for its use.

sourceOfFunds.provided.card.number Masked digits OPTIONAL

The 6.4 masked account number of the payer's account used for the payment.

sourceOfFunds.provided.giftCard Object OPTIONAL

Details about the gift card using for payment.

sourceOfFunds.provided.giftCard.brand Enumeration OPTIONAL

The brand name used to describe the card that is recognized and accepted globally. For gift cards this will always be set to LOCAL_BRAND_ONLY.

sourceOfFunds.provided.giftCard.localBrand String OPTIONAL

The brand name used to describe a card as determined by the gateway, based on the BIN range of the card.

sourceOfFunds.provided.giftCard.number Masked digits OPTIONAL

The 6.4 masked card number as printed or embossed on the gift card.

sourceOfFunds.provided.giftCard.scheme Enumeration OPTIONAL

The organization that owns a card brand and defines operating regulations for its use.

sourceOfFunds.provided.directDebitCanada Object OPTIONAL

For Direct Debit payments in Canada, the details about the payers bank account used for the payment are provided in this parameter group.

sourceOfFunds.provided.directDebitCanada.accountType Enum OPTIONAL

sourceOfFunds.provided.directDebitCanada.bankAccountHolder String OPTIONAL

The name of the bank account holder, as it appears on the account at the receiving financial institution.

sourceOfFunds.provided.directDebitCanada.bankAccountNumber String OPTIONAL

The identifier of the bank account at the receiving financial institution.

sourceOfFunds.provided.directDebitCanada.financialInstitutionNumber String OPTIONAL

The identifier of the receiving financial institution.

sourceOfFunds.provided.directDebitCanada.transitNumber String OPTIONAL

The transit number identifying the branch of the receiving financial institution where the bank account is held.

sourceOfFunds.provided.directDebitCanada.bankAccountNumberConfirmation Enumeration OPTIONAL

A selector for the bank account number confirmation field. Allows you to request an additional "bank account number confirmation" field to be displayed. Hosted Session will validate if the bankAccountNumber and bankAccountNumberConfirmation fields match.If they do not match then an error is returned in the validate function and onValidityChange callback.

sourceOfFunds.type Enumeration OPTIONAL

The payment method used for this payment.

version ASCII TEXT OPTIONAL

Use this field to implement optimistic locking of the session content.

Return Value : None

scope String OPTIONAL

The optional named instance of a card payment data set within a session. See Multiple Hosted Sessions for more information.

Return Value

None

Copyright © 2023 Commonwealth Bank of Australia