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
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.
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.
invalidFieldCharacters
Enum
OPTIONAL
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.
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.