Session configure()

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 Copied to clipboard

PaymentSession.configure(configuration, [scope])


Example Copied to clipboard

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 Copied to clipboard

configuration Copied to clipboard Object

Specifies the configuration for the Hosted Session interaction.

session Copied to clipboard 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 Copied to clipboard Object

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 Copied to clipboard String

A container for the card fields.

number Copied to clipboard String

A selector for the card number field.

securityCode Copied to clipboard String

A selector for the security code field.

expiryMonth Copied to clipboard String

A selector for the expiry month field.

expiryYear Copied to clipboard String

A selector for the expiry year field.

nameOnCard Copied to clipboard String

A selector for the cardholder name field.

giftCard Copied to clipboard String

A container for the gift card fields.

number Copied to clipboard String

A selector for the gift card number field.

pin Copied to clipboard String

A selector for the gift card PIN field.

ach Copied to clipboard String

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

accountType Copied to clipboard String

A selector for the ACH account type field.

bankAccountHolder Copied to clipboard String

A selector for the ACH account holder field.

bankAccountNumber Copied to clipboard String

A selector for the ACH account number field.

bankAccountNumberConfirmation Copied to clipboard String

A selector for the ACH account number confirmation field.

routingNumber Copied to clipboard String

A selector for the ACH routing number field.

directDebitCanada Copied to clipboard Object

A container for the Direct Debit Canada payment fields.

accountType Copied to clipboard Enum

A selector for the type of the bank account.

Value must be a member of the following list. The values are case-sensitive.
CONSUMER_CHECKINGConsumer Checking Account.
CONSUMER_SAVINGSConsumer Savings Account.
bankAccountHolder Copied to clipboard String

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

bankAccountNumber Copied to clipboard String

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

financialInstitutionNumber Copied to clipboard String

A selector for the identifier of the receiving financial institution.

transitNumber Copied to clipboard String

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

bankAccountNumberConfirmation Copied to clipboard String

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 Copied to clipboard String REQUIRED

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

interaction Copied to clipboard Object

Controls the payer's interaction with the payment process.

displayControl Copied to clipboard Object

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

formatCard Copied to clipboard Enum

This field controls the formatting of the card number field.

Set the value to PLAIN to format the field with no character spacing. For example:

  • 375987654321002
  • 5412750123450988

Set the value to EMBOSSED to format the field with the same character spacing as embossed on a card. For example:

  • 3759 876543 21002
  • 5412 7501 2345 0988

By default, this field is set to PLAIN.

PLAINThe card number is displayed with no spacing between characters.
EMBOSSEDThe card number is displayed with the same character spacing as embossed on a card.
invalidFieldCharacters Copied to clipboard Enum

Controls the behavior when invalid characters are entered by the payer.

For example, when an X character is passed in a credit card number field.

The default value is REJECT. Consider using ALLOW for a better experience for payers using assistive technology.

Value must be a member of the following list. The values are case-sensitive.
ALLOWThe character will be accepted and included in the field. If not corrected, then an error will be generated on submission.
REJECTThe character will not be accepted and will not be included in the input field.
lineOfBusiness Copied to clipboard String

Your payment service 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 Copied to clipboard Object

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

initialized Copied to clipboard Function REQUIRED

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

Arguments Copied to clipboard

The function will be invoked with the following object:

response Copied to clipboard object
status Copied to clipboard Enum

The status of the Hosted Session initialization.

Value must be a member of the following list. The values are case-sensitive.
OKIndicates that Hosted Session was successfully initialized.
SYSTEM_ERRORIndicates that Hosted Session was not successfully initialized.
message Copied to clipboard String

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

Return Value Copied to clipboard

None

formSessionUpdate Copied to clipboard Function REQUIRED

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 Copied to clipboard

The function will be invoked with the following object:

response Copied to clipboard object
status Copied to clipboard Enum

Status being returned from the callback.

Value must be a member of the following list. The values are case-sensitive.
OKThe value of the fields have been updated successfully into the session.
FIELDS_IN_ERRORError occurred when updating the value into session.
merchant Copied to clipboard Alphanumeric + additional characters

The unique identifier issued to you by your payment provider.

session Copied to clipboard object

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

id Copied to clipboard ASCII TEXT

Identifier of the session.

updateStatus Copied to clipboard String

A summary of the outcome of the attempt to update the session. In order to perform an operation using this session this value must be SUCCESS.

FAILUREThe attempt to place data into the session was unsuccessful. The session may contain invalid data. A request operation using this session will be rejected by the gateway.
NO_UPDATENo attempt has been made to place data into the session. A request operation using this session will be rejected by the gateway.
SUCCESSThe attempt to update the session was successful. You may submit a request operation using this session.
sourceOfFunds Copied to clipboard object

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

provided Copied to clipboard Object

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

ach Copied to clipboard Object

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.

accountType Copied to clipboard Enumeration

An indicator identifying the type of bank account.

bankAccountHolder Copied to clipboard String

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

bankAccountNumber Copied to clipboard Alphanumeric + additional characters

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

routingNumber Copied to clipboard Digits

The identifier of the receiving financial institution.

secCode Copied to clipboard Enumeration

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

card Copied to clipboard Object

Details about the card using for payment.

brand Copied to clipboard Enumeration

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.

expiry Copied to clipboard Object

Expiry date, as shown on the card.

month Copied to clipboard Digits

Month, as shown on the card.

year Copied to clipboard Digits

Year, as shown on the card.

fundingMethod Copied to clipboard Enumeration

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.

nameOnCard Copied to clipboard String

The cardholder's name as printed on the card.

scheme Copied to clipboard Enumeration

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

number Copied to clipboard Masked digits

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

giftCard Copied to clipboard Object

Details about the gift card using for payment.

brand Copied to clipboard Enumeration

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.

localBrand Copied to clipboard String

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

number Copied to clipboard Masked digits

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

scheme Copied to clipboard Enumeration

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

directDebitCanada Copied to clipboard Object

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

accountType Copied to clipboard Enumeration

The type of the bank account.

CONSUMER_CHECKINGConsumer Checking Account.
CONSUMER_SAVINGSConsumer Savings Account.
bankAccountHolder Copied to clipboard String

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

bankAccountNumber Copied to clipboard String

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

financialInstitutionNumber Copied to clipboard String

The identifier of the receiving financial institution.

transitNumber Copied to clipboard String

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

bankAccountNumberConfirmation Copied to clipboard Enumeration

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.

type Copied to clipboard Enumeration

The payment method used for this payment.

version Copied to clipboard ASCII TEXT

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

Return Value Copied to clipboard

None

scope Copied to clipboard String

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


Return Value Copied to clipboard

None