updateSession()
Sends a request to store the input from the hosted field into the session.
Usage Copied to clipboard
PaymentSession.updateSession(updateSessionCallback)
Example Copied to clipboard
PaymentSession.updateSession(function (updateSessionResponse) {
// handle response
});
JSON Example for Session Update Response Copied to clipboard
// status can be one of the following: ok, fields_in_error, system_error, request_timeout
// An error response (fields_in_error)
{
"status": "fields_in_error",
"session": {
"id": "SESSION000218450948092491657986"
},
"errors": {
"cardNumber": "invalid",
"securityCode": "invalid"
},
version: "36"
}
// An error response (system_error)
{
"status": "system_error",
"session": {
"id": "SESSION000218450948092491657986"
},
"errors": {
"message": "System error message."
},
"version": "36"
}
// An error response (request_timeout)
{
"status" : "request_timeout",
"session": {
"id": "SESSION000218450948092491657986"
},
"errors": {
"message": "Request timeout error message."
},
"version": "36"
}
// An ok response
{
"status":"ok",
"merchant": "TESTMERCHANT",
"session": {
"id": "SESSION000218450948092491657986"
"updateStatus":"SUCCESS",
"version":"e3f144ce02"
},
"sourceOfFunds": {
"provided": {
"card": {
"brand": "MASTERCARD",
"expiry": {
"month": "1",
"year": "39"
},
"fundingMethod": "DEBIT",
"nameOnCard": "John Smith",
"number": "512345xxxxxx8769",
"scheme": "MASTERCARD"
}
},
"type": "CARD"
},
"version": "36"
}
Arguments Copied to clipboard
The function to handle the response from PaymentSession.updateSession( ) call. Defined as updateSessionCallback = function(updateSessionResponse).
The overall status of the PaymentSession.updateSession( ) request. Possible values are:
ok
fields_in_error
system_error
request_timeout
The version of the DirectAPI used to retrieve the session details.
The errors object returned if the PaymentSession.updateSession( ) request failed to update the session successfully.
Indicates the name of the field that failed validation, returned only if the response status is fields_in_error.
Cause of the error. Possible values are:
missing
invalid
Example Copied to clipboard
// An error response (fields_in_error)
"errors": {
"cardNumber": "invalid",
"securityCode": "invalid"
},
The error message returned if the response status is system_error or request_timeout.
Example Copied to clipboard
// An error response (request_timeout)
"errors": {
"message": "Request timeout error message."
},
// An error response (system_error)
"errors": {
"message": "System error message."
},
Information on 3DSecure fields.
The Electronic Commerce Indicator returned by the card issuer in the authentication response message.
A collection of parameters required to build the HTML form that is redirected to the ACS.
1. Simple: submit the form generated by the gateway. In this case, only the htmlBodyContent parameter is required.
2. Customized: for those merchants who wish to customise the submission. In this case, the acsURL and paReq parameters will be required to formulate the submission.
Note: This field will only be returned in the event of a successful directory server lookup.
Indicates the option (Simple or Customized) used to generate the page that redirects the cardholder to the card Issuer's Access Control Server (ACS) for authentication.
CUSTOMIZEDA strategy to indicate that the user wishes to customize the responseSIMPLEA simple interaction model where the response is complete and no user intervention is required.The URL to which you want to redirect the payer after completing the payer authentication process.
The details required by the system to generate the HTML page as specified in the Simple option.
The encoding required for the HTML returned in the response, through htmlBodyContent parameter.
ASCIIISO_8859_1Latin1UTF_8Background color of the page, encoded in HEX, rendered in the cardholder's browser while the browser is waiting for the authentication to commence.
Text on the button that the cardholder can use to redirect the browser to the card Issuer's Access Control Server (ACS) if JavaScript is disabled for their browser.
Title of the page rendered in the cardholder's browser while the browser is waiting for the authentication to commence.
Indicates if the cardholder verification was successful.
The PARes message is the response received from the card Issuer's Access Control Server (ACS) after the cardholder has completed the authentication process.
AUTHENTICATION_ATTEMPTEDAuthentication was attempted but the card issuer did not perform the authentication.AUTHENTICATION_NOT_AVAILABLEAn internal error occurred and Authentication is not currently available.AUTHENTICATION_SUCCESSFULThe cardholder was successfully authenticated.The base64 encoded value generated by the card issuer.
This field corresponds to the Cardholder Authentication Verification Value (CAVV) for Visa, the Accountholder Authentication Value (AAV) for MasterCard and JCB, or the American Express Verification Value (AEVV) for American Express.
Indicates if the cardholder is enrolled for 3-D Secure authentication.
ENROLLEDThe card is enrolled for 3DS authentication.ENROLLMENT_STATUS_UNDETERMINEDThe Issuer's ACS was unable to process the request to check enrollment or the card is ineligible.NOT_ENROLLEDThe card is not enrolled for 3DS authentication.An optional field that the merchant may supply in the Transaction Request as a description of the transaction.
A unique transaction identifier generated by the Payment Gateway on behalf of the merchant to identify the 3DS transaction.
A unique identifier supplied by the merchant for the authentication.
Airline industry specific data.
The record locator used to access a specific Passenger Name Record (PNR).
The type of charge associated with the transaction.
ADDITIONAL_COLLECTIONAdditional CollectionAGENCY_EXCHANGE_ORDERAgency Exchange OrderAGENCY_GROUP_TICKETAgency Group TicketAGENCY_MISCELLANEOUS_CHARGE_ORDERAgency Misc. Charge Order (MCO)AGENCY_PASSENGER_TICKETAgency Passenger TicketAGENCY_TOUR_ORDER_OR_VOUCHERAgency Tour Order/VoucherAIR_FREIGHTSPD/Air FreightANIMAL_TRANSPORTATION_CHARGEAnimal Transportation ChargeCATALOGUE_MERCHANDISE_ORDEREDCatalogue Merchandise OrderedCLUB_MEMBERSHIP_FEEClub Membership FeeCOUPON_BOOKCoupon BookCREDIT_CLASS_SERVICE_ADJUSTMENTCredit Class of Service AdjustmentCREDIT_DENIED_BOARDINGCredit Denied BoardingCREDIT_EXCHANGE_REFUNDCredit Exchange RefundCREDIT_LOST_TICKET_REFUNDCredit Lost Ticket RefundCREDIT_MISCELLANEOUS_REFUNDCredit Misc. RefundCREDIT_MULTIPLE_UNUSED_TICKETSCredit Multiple Unused TicketsCREDIT_OVERCHARGE_ADJUSTMENTCredit Overcharge AdjustmentCREDIT_UNUSED_TRANSPORTATIONCredit Unused TransportationDEBT_ADJUSTMENT_DUPLICATE_REFUND_OR_USEDebt Adjustment Duplicate Refund/UseDUTY_FREE_SALEDuty Free SaleEXCESS_BAGGAGEExcess BaggageEXCHANGE_ADJUSTMENTExchange AdjustmentEXCHANGE_ORDERExchange OrderFIREARMS_CASEFirearms CaseFREQUENT_FLYER_FEE_OR_PURCHASEFrequent Flyer Fee/PurchaseFREQUENT_FLYER_FULFILLMENTFrequent Flyer FulfillmentFREQUENT_FLYER_OVERNIGHT_DELIVERY_CHARGEFrequent Flyer Overnight Delivery ChargeGROUP_TICKETGroup TicketIN_FLIGHT_ADJUSTMENTIn-flight AdjustmentIN_FLIGHT_CHARGESIn-flight ChargesIN_FLIGHT_DUTY_FREE_PURCHASEIn-flight Duty Free PurchaseIN_FLIGHT_MERCHANDISE_ORDEREDIn-flight Merchandise OrderedIN_FLIGHT_PHONE_CHARGESIn-flight Phone ChargesKENNEL_CHARGEKennel ChargeLOST_TICKET_APPLICATIONLost Ticket ApplicationMISCELLANEOUS_CHARGE_ORDER_OR_PREPAID_TICKET_ADVICEMisc. Charge Order (MCO) / Prepaid Ticket Auth.MISCELLANEOUS_TAXES_FEESMiscellaneous Tax(es) Fee(s)PASSENGER_TICKETPassenger TicketSELF_SERVICE_TICKETSSelf-Service Ticket(s)SENIOR_CITIZEN_DISCOUNT_BOOKLETSSenior Citizen Discount BookletsSMALL_PACKAGE_DELIVERYSmall Package DeliverySPECIAL_SERVICE_TICKETSpecial Service TicketSUPPORTED_REFUNDSupported RefundTICKET_BY_MAILTicket by MailTOUR_DEPOSITTour DepositTOUR_ORDER_VOUCHERTour Order VoucherUNDERCHARGE_ADJUSTMENTUndercharge AdjustmentUNSUPPORTED_REFUNDUnsupported RefundUPGRADE_CHARGEUpgrade ChargeVENDOR_REFUND_CREDITVendor Refund CreditVENDOR_SALEVendor SaleItinerary details
Travel leg details.
The 2-character IATA airline code or 3 digit accounting code or both of the airline carrier for the trip leg.
The ticket containing the coupon for this leg for an itinerary with more than four trip legs.
The coupon number on the ticket for the trip leg.
The 3 character IATA airport code of the departure airport for the trip leg.
Date of departure for the trip leg.
Tax payable on departure for the trip leg.
Departure time in local time for the departure airport for this trip leg.
The 3 character IATA airport code for the destination airport for the trip leg.
Arrival date in local time for the destination airport for this trip leg.
Arrival time in local time for the destination airport for this trip leg.
Restrictions (e.g. non-refundable) or endorsements applicable to the trip leg.
New ticket number issued when a ticket is exchanged for the trip leg.
Total fare payable for the trip leg.
Code defining the rules forming the basis of the fare (type of fare, class entitlement, etc.)
Total fees payable for the trip leg.
The flight number for the trip leg.
Indicates if a stopover is permitted for the trip leg.
Total taxes payable for the trip leg.
The industry code indicating the class of service (e.g. Business, Coach) for the leg.
Number of passengers associated with this booking.
The 3 character ISO 3166-1 alpha-3 country code of the country of origin for the itinerary.
Passenger details
First name of the passenger to whom the ticket is being issued.
Frequent Flyer or Loyalty Program number for this passenger.
Last name of the passenger to whom the ticket is being issued.
Middle name of the passenger to whom the ticket is being issued.
Passenger specific information recorded on the ticket.
Title of the passenger to whom the ticket is being issued.
Plan number supplied by the airline for this booking.
Ticket details
Indicates if a conjunction ticket with additional coupons was issued.
Indicates if an electronic ticket was issued.
The original ticket number when this is a transaction for an exchanged ticket.
Ticket issue information.
The address where the ticket was issued.
The 2-character IATA airline code or 3 digit accounting code or both of the airline carrier issuing the ticket.
Name of airline carrier issuing the ticket.
The city/town where the ticket was issued.
The 3 character ISO 3166-1 alpha-3 country code of the country where the ticket was issued.
The date the ticket was issued.
Industry code of the travel agent issuing the ticket.
Name of the travel agent issuing the ticket.
Indicates if the issued ticket is refundable.
The airline ticket number associated with the transaction.
Total fare for all trip legs on the ticket.
Total fee for all trip legs on the ticket.
Total taxes for all trip legs on the ticket.
The type of transaction performed against this airline booking.
EXCHANGE_TICKETExchange TicketMISCELLANEOUS_CHARGEMiscellaneous ChargeREFUNDRefundREVERSALReversalTICKET_PURCHASETicket PurchaseTOUR_ORDERTour OrderDetails of the payer's billing address.
The payer's billing address.
The city portion of the address.
The name of the company associated with this address.
The 3 letter ISO standard alpha country code of the address.
The post code or zip code of the address.
The state or province of the address.
The first line of the address.
The second line of the address (if provided).
Information about any constraints that apply to this transaction.
Information about the payment plan constraints which apply for this transaction.
The allowable number of deferral months for the payment plan.
The allowable number of installments for the payment plan.
The identifiers for the payment plans supported for this transaction.
See Payment Plans for the supported payment plans and their identifiers.
A transient identifier for the request, that can be used to match the response to the request.
Information specific to the use of dynamic currency conversion (DCC).
You can only provide DCC information on the initial transaction for an order. If provided on subsequent transactions or an order, DCC information will be ignored.
The timestamp of when the conversion rate is effective.
The foreign exchange markup applied as a percentage to the transaction amount for providing the conversion service.
The total amount of the transaction in the payer's currency.
The currency of the DCC rate quote provided by your DCC Service Provider.
The exchange rate used to convert the transaction amount into the payer's currency.
This identifies the name of the provider of the DCC quote.
FEXCOTRAVELEX_CURRENCY_SELECTThe quote provider's unique reference to the rate quote.
The unique identifier for your DCC quote request as returned in the PAYMENT_OPTIONS_INQUIRY response.
Indicates how DCC applies to the order.
ACCEPTEDThe payer accepted the DCC offer and pays in their own currency. The conditions of the rate quote are applied in the processing of this transaction.DECLINEDThe payer declined the DCC offer and pays in your transaction currency.NOT_AVAILABLEA rate quote was requested, but no DCC offer was provided. For rate quotes via the gateway the PAYMENT_OPTION_INQUIRY response contains a currencyConversion.gatewayCode other than QUOTE_PROVIDED.NOT_REQUIREDDCC is not required for this transaction.Information associated with the customer's source of transaction.
The email address of the customer.
The payer's first name.
The payer's last or surname.
The contact person's mobile phone or cell phone number.
The phone number of the person to whom the order is being billed.
Information associated with the device's source of transaction.
The telephone number captured by ANI (Automatic Number Identification) when the customer calls to place the order.
The 2 digit ANI information identifier provided by the telephone company to indicate the call type, for example, cellular (61-63), toll free (24,25), etc.
The User-Agent header of the browser the customer used to place the order.
Information collected about a remote computing device for the purpose of providing a unique identifier for the device.
The name of the server to which the customer is connected.
The IP address of the computer used by the customer, in nnn.nnn.nnn.nnn format.
A language identifier or IETF language tag to control the language of the payment interaction with the payer (e.g. en_US, es, fr-CA).
See Dynamic Currency Conversion for more detail.
The unique identifier issued to you by your payment provider.
Information about the order associated with this transaction.
Indicates whether you will accept a payment less than order.amount, e.g. when using a gift card.
Unless you have been advised by your payment service provider that the gateway supports partial approvals for your acquirer, you can ignore this field.
If the gateway supports partial approvals for your acquirer you must set this field to TRUE else the transaction is rejected by the gateway.
The total amount for the order.
The currency of the order expressed as an ISO 4217 alpha code, e.g. USD.
Information about this order that is of interest to you.
A note from the payer about this order.
The date the payer placed the order.
The payer's own reference for the order (for example, the purchase order number).
Short textual description of the contents of the order.
Information about a price reduction you have applied to the order.
The total amount of the discount you have applied to the order.
The code you use to identify the reason for the discount.
A description of your reason for the discount.
A unique identifier for this order to distinguish it from any other order you create.
The URL to which the gateway will send Webhook notifications when an order is created or updated.
Unique SKU (Stock Keeping Unit) for the single, most expensive product associated with this order.
Your reference to the contract or agreement you have with the payer to process recurring payments.
The identifier of the order.
The name of the person who requested the goods or services.
The total shipping and handling amount for the order.
Allows you to provide a breakdown of the types of taxes and amount per type of tax included in order.taxAmount.
Provide the amount for this type of tax.
Provide the name for the type of tax for order.taxAmount.
The total tax amount for the order.
If you provide both this value and line item data, then the order.taxAmount MUST equal the total tax amount.
This data may be used to qualify for better interchange rates on corporate purchase card transactions.
Your tax registration identifier provided by the tax authority (for example, federal tax identification number, ABN).
The wallet indicator as returned by the wallet provider.
Select the wallet provider for this interaction.
MASTERPASS_ONLINEMasterPass Online wallet provider.VISA_CHECKOUTVisa Checkout wallet provider.If, when integrating with the gateway, you are using a solution (e.g. a shopping cart or e-commerce solution) provided, supported or certified by your payment service provider, enter the solution ID issued by your payment service provider here.
Information about the payment plan selected by the cardholder.
The number of months for which the payment is deferred.
The number of monthly payments payable by the cardholder.
The identifier for the payment plan.
The payment method the payer wishes to use to pay for this order.
ACHBANCANETCREDITGIFT_CARDGIROPAYPAYPALSOFORTContainer for fields that control the response returned for the request.
Indicates how sensitive data is returned in the response.
Information relevant to risk assessment.
The risk rules you wish to bypass when performing risk assessment for an order.
ALLAdditional data passed to third-party risk assessment providers.
Field: risk.custom.headOfficeLocation
Value: London UK
Session Information
The identifier of the session
A summary of the outcome of the last attempt to modify the session.
FAILUREThe last 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 payment gateway.NO_UPDATENo attempt has been made to place data into the session. A request operation using this session will be rejected by the payment gateway.SUCCESSThe last attempt to update the session was successful. You may submit a request operation using this session.Use this field to implement optimistic locking of the session content.
To use optimistic locking, record session.version when you make your decisions, and then pass that value in session.version when you submit your request operation to the gateway.
See Making Business Decisions Based on Session Content.
Information on the shipping address including the contact details of the addressee.
The address to which the goods contained in this order are being shipped.
The city portion of the address.
The name of the company associated with this address.
The 3 letter ISO standard alpha country code of the address.
The post code or zip code of the address.
The state or province of the address.
The first line of the address.
The second line of the address (if provided).
Details of the contact person at the address the goods will be shipped to.
The contact person's email address.
The first name of the person to whom the order is being shipped.
The last name or surname of the person to whom the order is being shipped.
The contact person's mobile phone or cell phone number.
The phone number of the person to whom the order is being shipped.
The shipping method code to indicate the time frame and the priority of the order.
ELECTRONICElectronic delivery.GROUNDGround (4 or more days).OVERNIGHTOvernight (next day).PRIORITYPriority (2-3 days).SAME_DAYSame day.The details describing the source of the funds to be used.
Information about the source of funds when it is directly provided (as opposed to via a token or session).
For ACH payments (sourceOfFunds.type=ACH) you must provide values for all fields within this parameter group, including details about the payers bank account as well as the type of ACH payment.
An indicator identifying the type of bank account.
- Consumer (checking or savings), or
- Business
For pre-arranged payments (sourceOfFunds.provided.ach.secCode=PPD) retrieve this information from the payer.
If payments were telephone-initiated (sourceOfFunds.provided.ach.secCode=TEL) or internet-initiated (sourceOfFunds.provided.ach.secCode=WEB) you may choose to limit the payer's options (e.g. only support consumer checking accounts), depending on your type of business (e.g. B2C online webshop).
CONSUMER_CHECKING Consumer Checking AccountCONSUMER_SAVINGSConsumer Savings AccountCORPORATE_CHECKINGBusiness Checking AccountThe name of the bank account holder, as it appears on the account at the receiving financial institution.
The identifier of the bank account at the receiving financial institution.
The identifier of the receiving financial institution.
- Routing number,
- Transit number, or
- ABA number
Retrieve this information from the payer.
See also http://en.wikipedia.org/wiki/Routing_transit_number.
Identifies the Standard Entry Class (SEC) code to be sent to the issuer.
PPDAn ACH debit or credit payment (B2C) that has been authorized by an authenticated customer in written form (signed or similarly authenticated). PPD is used for pre-arranged payments (e.g. employee payroll, mortgage payments, expense reimbursement).TELAn ACH debit payment (B2C) that has been authorized by an authenticated customer via phone.
TEL may only be used if a relationship already exists between you and the consumer, or, the consumer initiates the contact with you.
WEBAn ACH debit payment (B2C) that has been authorized by an authenticated customer via the internet or a wireless network.Details as shown on the card.
You can provide this field for card types that have a savings/checking option, such as Maestro cards.
CHECKINGSAVINGSExpiry date, as shown on the card.
Month, as shown on the card.
Year, as shown on the card.
The cardholder's name as printed on the card.
Credit card number as printed on the card.
The first 6 digits of the card number up to a maximum of 9 digits, as printed on the card.
Card verification code, as printed on the back or front of the card.
The card sequence number for transactions where the data is read through a chip on the EMV card.
If the payer chose to pay using a gift card, you must submit sourceOfFunds.type=GIFT_CARD and provide the payer's gift card details in this parameter group.
Do not provide this field in your request unless instructed to do so by your payment service provider.
Card number as printed or embossed on the gift card.
PIN number for the gift card.
Uniquely identifies a card and associated details.
The payment method your payer has chosen for this payment.
ACHThe payer chose to pay using an electronic fund transfer, to be processed via the Automated Clearing House (ACH) Network. You must provide the payer's bank account details and information about the type of ACH payment under the sourceOfFunds.provided.ach parameter group.CARDThe payer selected to pay using a credit or debit card. The payer's card details must be provided.GIFT_CARDThe payer chose to pay using gift card. The payer's gift card details must be provided under the sourceOfFunds.provided.giftCard parameter group.Uniquely identifies a card and associated details.
Information about this transaction.
Additional information to be passed to acquirer.
Additional information requested by the acquirer which cannot be passed using other available data fields.
Transaction Amount.
Value generated by the issuing bank in response to a proposal to transfer funds.
Set this flag if the transaction is a manual cash disbursement transaction, i.e. cash is disbursed upon the acceptance of a card by a financial institution teller.
The currency which should be used for acquirer card verification.
Indicates the frequency of the transaction offered to the payer.
INSTALLMENTIndicates an installment transaction where the payer authorizes you to deduct multiple payments over an agreed period of time for a single purchase.RECURRINGIndicates a recurring transaction where the payer authorizes you to automatically debit their accounts for bill or invoice payments.SINGLEIndicates a single transaction where a single payment is used to complete the order.Unique identifier for this transaction to distinguish it from any other transactions on the order.
Information about the items the payer purchases with the order.
The brand of the item.
The category of the item.
Description for the item with information such as size, color, etc.
A short name describing the item.
The quantity of the item.
The SKU (Stock Keeping Unit) or the item identifier for this item.
The cost price for the item.
The tax amount for the item.
Your note about this transaction.
Indicates that a transaction requires approval to proceed with the order.
REQUESTEDRequestedAn optional identifier for this transaction.
Indicates the source through which you received the transaction.
CALL_CENTRETransaction conducted via a call centre.CARD_PRESENTTransaction where the card is presented to the merchant.INTERNETTransaction conducted over the Internet.MAIL_ORDERTransaction received by mail.MOTOTransaction received by mail or telephone.TELEPHONE_ORDERTransaction received by telephone.VOICE_RESPONSETransaction conducted by a voice/DTMF recognition system.The identifier for the transaction you wish to refund.
If you do not provide a target transaction ID the gateway will try to identify a transaction. If no transaction can be found or more than one transaction is identified, the request is rejected.
Allows you to provide a breakdown of the types of taxes and amount per type of tax included in transaction.taxAmount.
Provide the amount for this type of tax.
Provide the name for the type of tax for transaction.taxAmount.
The amount of tax included in this transaction, if different to the default value.
The source through which the order has been received.
CALL_CENTRETransaction conducted via a call centre.CARD_PRESENTTransaction where the card is presented to the merchant.INTERNETTransaction conducted over the Internet.MAIL_ORDERTransaction received by mail.MOTOTransaction received by mail or telephone.TELEPHONE_ORDERTransaction received by telephone.VOICE_RESPONSETransaction conducted by a voice/DTMF recognition system.The person who initiated this transaction.
The strategy used to verify the payment instrument details before they are stored.
ACQUIRERThe gateway performs a Web Services API Verify request. Depending on the payment type, you may need to provide additional details to enable the submission of a Verify request.BASICThe gateway verifies the syntax and supported ranges of the payment instrument details provided, .e.g for a card it validates the card number format and checks if the card number falls within a valid BIN range.NONEThe gateway does not perform any validation or verification of the payment instrument details provided.The URL to which you want the payer's browser to be redirected if the payer cancels the interaction on the wallet provider's website.
The URL to which you want the payer's browser to be redirected after completing the interaction on the wallet provider's website.
Response fields from Visa Checkout Open Wallet operation.
Provide the value of the field callId as returned by the Visa Checkout lightbox.
Card artwork details as returned by Visa Checkout, including the URL of the card art, and height and width of the card art in pixels, for example {"cardArt":[{"baseImageFileName":"<Image URL>","height":50,"width":77}]}.
Card brand returned by Visa Checkout indicating the card brand selected by the payer at Visa Checkout.
Return Value Copied to clipboard
None