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 Object

Specifies the configuration for the Hosted Session interaction.

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

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

A container for the card fields.

number String

A selector for the card number field.

securityCode String

A selector for the security code field.

expiryMonth String

A selector for the expiry month field.

expiryYear String

A selector for the expiry year field.

nameOnCard String

A selector for the cardholder name field.

giftCard String

A container for the gift card fields.

number String

A selector for the gift card number field.

pin String

A selector for the gift card PIN field.

ach String

A container for the ACH (ACH) payment fields.

accountType String

A selector for the ACH account type field.

bankAccountHolder String

A selector for the ACH account holder field.

bankAccountNumber String

A selector for the ACH account number field.

bankAccountNumberConfirmation String

A selector for the ACH account number confirmation field.

routingNumber String

A selector for the ACH routing number field.

directDebitCanada Object

A container for the Direct Debit Canada payment fields.

accountType 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 String

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

bankAccountNumber String

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

financialInstitutionNumber String

A selector for the identifier of the receiving financial institution.

transitNumber String

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

bankAccountNumberConfirmation 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 String REQUIRED

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

interaction Object

Controls the payer's interaction with the payment process.

displayControl Object

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

formatCard 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 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.

callbacks Object

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

initialized 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 object

status 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 String

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

Return Value Copied to clipboard

None

formSessionUpdate 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 object

status 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 Alphanumeric + additional characters

The unique identifier issued to you by your payment provider.

session object

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

id ASCII TEXT

Identifier of the session.

updateStatus 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 object

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

provided Object

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

ach 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 Enumeration

An indicator identifying the type of bank account.

bankAccountHolder String

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

bankAccountNumber Alphanumeric + additional characters

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

routingNumber Digits

The identifier of the receiving financial institution.

secCode Enumeration

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

card Object

Details about the card using for payment.

brand 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 Object

Expiry date, as shown on the card.

month Digits

Month, as shown on the card.

year Digits

Year, as shown on the card.

fundingMethod 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 String

The cardholder's name as printed on the card.

scheme Enumeration

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

number Masked digits

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

giftCard Object

Details about the gift card using for payment.

brand 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 String

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

number Masked digits

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

scheme Enumeration

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

directDebitCanada 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 Enumeration

The type of the bank account.

CONSUMER_CHECKINGConsumer Checking Account.

CONSUMER_SAVINGSConsumer Savings Account.

bankAccountHolder String

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

bankAccountNumber String

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

financialInstitutionNumber String

The identifier of the receiving financial institution.

transitNumber String

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

bankAccountNumberConfirmation Enumeration

type Enumeration

The payment method used for this payment.

version ASCII TEXT

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

Return Value Copied to clipboard

None

scope 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