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
A selector for the type of the bank account.
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
This field controls the formatting of the card number field.
invalidFieldCharacters Enum OPTIONAL
Controls the behavior when invalid characters are entered by the
payer.
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
The status of the Hosted Session initialization.
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
Status being returned from the callback.
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
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.
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
The type of the bank account.
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