Update Session From Wallet

This operation retrieves the payer's payment details associated with a wallet interaction.

For the MasterPass wallet, provide the oauthToken, oauthVerifier and checkoutUrl returned by the MasterPass callback to retrieve the payer's payment details associated with the MasterPass interaction.The payment details collected at MasterPass Online will be stored against the payment session identified in the request.

For the Visa Checkout wallet, provide the callId returned by the Visa Checkout Lightbox to retrieve the payer's payment details associated with the Visa Checkout interaction.

The retrieved payment details are stored against the payment session identified in the request.

POST https://test-nbkpayment.mtf.gateway.mastercard.com/api/nvp/version/52

Authentication Copied to clipboard

This operation requires authentication via one of the following methods:


  • Certificate authentication.
  • To authenticate to the API two additional NVP parameters must be supplied in the request. Provide 'merchant.<your gateway merchant ID>' in the apiUsername field and your API password in the apiPassword field.

Request Copied to clipboard

Fields Copied to clipboard

apiOperation Copied to clipboard String = UPDATE_SESSION_FROM_WALLET FIXED

Any sequence of zero or more unicode characters.

correlationId Copied to clipboard String OPTIONAL

A transient identifier for the request, that can be used to match the response to the request.

The value provided is not validated, does not persist in the gateway, and is returned as provided in the response to the request.

Data can consist of any characters

Min length: 1 Max length: 100
merchant Copied to clipboard Alphanumeric + additional characters REQUIRED

The unique identifier issued to you by your payment provider.

This identifier can be up to 12 characters in length.

Data may consist of the characters 0-9, a-z, A-Z, '-', '_'

Min length: 1 Max length: 40
order Copied to clipboard REQUIRED

Details of the order.

order.amount Copied to clipboard Decimal OPTIONAL

The total amount for the order. This is the net amount plus any surcharge.

If you provide any sub-total amounts, then the sum of these amounts (order.itemAmount, order.taxAmount, order.shippingAndHandlingAmount, order.cashbackAmount, order.gratuityAmount), minus the order.discountAmount must equal the net amount.

The value of this field in the response may be zero if payer funds are not transferred.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
order.currency Copied to clipboard Upper case alphabetic text OPTIONAL

The currency of the order expressed as an ISO 4217 alpha code, e.g. USD.

This is only required for Express Checkout.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
order.walletProvider Copied to clipboard Enumeration REQUIRED

Details about the source of the payment details used for digital payment methods.

Provide this value when you process payments for:

  • • Device payment methods such as Apple Pay, Android Pay, Samsung Pay, or Google Pay.
  • • Digital wallets such as Masterpass, Visa Checkout or Amex Express Checkout.

Value must be a member of the following list. The values are case sensitive.

AMEX_EXPRESS_CHECKOUT

Amex Express Checkout wallet provider.

APPLE_PAY

Apple Pay mobile wallet provider.

CHASE_PAY

Chase Pay wallet provider.

GOOGLE_PAY

Google Pay mobile wallet provider.

MASTERPASS_ONLINE

MasterPass Online wallet provider.

SAMSUNG_PAY

Samsung Pay mobile wallet provider.

VISA_CHECKOUT

Visa Checkout wallet provider.

session.id Copied to clipboard ASCII Text REQUIRED

The identifier for the payment session as returned by the Create Session operation.The interaction details (including the return, redirect and cancel URLs) and the payment details collected at the wallet provider, following a successful interaction, will be stored against this session.

Data consists of ASCII characters

Min length: 31 Max length: 35
session.version Copied to clipboard ASCII Text OPTIONAL

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

Do this if you make business decisions based on data from the session and wish to ensure that the same data is being used for the request operation.

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.

If session.version provided by you does not match that stored against the session, the gateway will reject the operation with error.cause=INVALID_REQUEST.

See Making Business Decisions Based on Session Content.

Data consists of ASCII characters

Min length: 10 Max length: 10
wallet.amexExpressCheckout Copied to clipboard OPTIONAL

Provide the details for the Amex Express Checkout Wallet.

wallet.amexExpressCheckout.authCode Copied to clipboard String OPTIONAL

An Amex Express Checkout authorization code.

You need this to get the customer details from Amex Express Checkout.Get this value from the Amex Express Checkout Success callback, after the Amex Express Checkout interaction is completed.

Data can consist of any characters

Min length: 1 Max length: 100
wallet.amexExpressCheckout.selectedCardType Copied to clipboard String OPTIONAL

The type of card the payer selects for the payment.

Get this value from the Amex Express Checkout Success callback, after the Amex Express Checkout interaction is completed..

Data can consist of any characters

Min length: 1 Max length: 10
wallet.amexExpressCheckout.transactionId Copied to clipboard String OPTIONAL

A unique identifier provided for end to end tracking of an Amex Express Checkout interaction.

Get this value from the Amex Express Checkout Success callback, after the Amex Express Checkout interaction is completed.

Data can consist of any characters

Min length: 1 Max length: 36
wallet.amexExpressCheckout.walletId Copied to clipboard String OPTIONAL

The identifier of the wallet from which the payer selects their card.

Get this value from the Amex Express Checkout Success callback, after the Amex Express Checkout interaction is completed.

Data can consist of any characters

Min length: 1 Max length: 2
wallet.masterpass Copied to clipboard OPTIONAL

Provide the details for the MasterPass Wallet.

wallet.masterpass.checkoutUrl Copied to clipboard Url OPTIONAL

The MasterPass URL the gateway will use to retrieve the cardholder's payment details into the session.

Ensure that the URL begins with 'https' and is longer than 11 characters.

wallet.masterpass.oauthToken Copied to clipboard String OPTIONAL

Provide the value of the field oauthToken as returned by the MasterPass lightbox.

The gateway will use this, to retrieve the payer's payment details for the respective interaction from MasterPass and store them against the payment session (identified in field session.id). Mandatory for the MASTERPASS_ONLINE Wallet Provider.

Data can consist of any characters

Min length: 1 Max length: 255
wallet.masterpass.oauthVerifier Copied to clipboard String OPTIONAL

Provide the value of the field oauthVerifier as returned by the MasterPass lightbox.

The gateway will use this, to retrieve the payer's payment details for the respective interaction from MasterPass and store them against the payment session (identified in field session.id). Mandatory for the MASTERPASS_ONLINE Wallet Provider.

Data can consist of any characters

Min length: 1 Max length: 255
wallet.masterpassExpressCheckout Copied to clipboard OPTIONAL

Parameters used to obtain wallet details from MasterPass for an Express Checkout interaction.

The wallet details are added to the session.

wallet.masterpassExpressCheckout.longAccessToken Copied to clipboard String OPTIONAL

A wallet token provided by the gateway for Masterpass paired accounts.

Provide this token to obtain pre-checkout data from the payer's wallet for future interactions.

Data can consist of any characters

Min length: 1 Max length: 255
wallet.masterpassExpressCheckout.masterpassCardId Copied to clipboard String OPTIONAL

The MasterPass identifier for the card.

Provide this value to MasterPass in the cardId parameter when you initiate a 'Connected Checkout' or 'Express Checkout' MasterPass interaction for this wallet.

Data can consist of any characters

Min length: 1 Max length: 255
wallet.masterpassExpressCheckout.masterpassShippingId Copied to clipboard String OPTIONAL

The MasterPass identifier for the shipping address.

Provide this value to MasterPass in the shippingId parameter when you initiate a 'Connected Checkout' or 'Express Checkout' MasterPass interaction for this wallet.

Data can consist of any characters

Min length: 1 Max length: 255
wallet.masterpassExpressCheckout.originUrl Copied to clipboard Url OPTIONAL

The URL of the page that will initialize the MasterPass lightbox.

Ensure that the URL begins with 'https' and is longer than 11 characters.

wallet.masterpassExpressCheckout.precheckoutTransactionId Copied to clipboard String OPTIONAL

A MasterPass transaction identifier.

Provide this value to MasterPass when you initiate a 'Connected Checkout' or 'Express Checkout' MasterPass interaction for this wallet.

Data can consist of any characters

Min length: 1 Max length: 50
wallet.masterpassExpressCheckout.secondaryOriginUrl Copied to clipboard Url OPTIONAL

The URL of the outer or parent page that will initialize the MasterPass lightbox.

Provide this field only when the Lightbox will be invoked from a frame that's on a merchant site, and when that frame has a different domain than the merchant site.

Ensure that the URL begins with 'https' and is longer than 11 characters.

wallet.visaCheckout Copied to clipboard OPTIONAL

Provide the details for the VisaCheckout Wallet.

wallet.visaCheckout.callId Copied to clipboard String OPTIONAL

Provide the value of the field callId as returned by the Visa Checkout lightbox.

The gateway will use this, to retrieve the payer's payment details for the respective interaction from Visa Checkout and store them against the payment session (identified in field session.id). Mandatory for the VISA_CHECKOUT Wallet Provider.

Data can consist of any characters

Min length: 1 Max length: 48

Response Copied to clipboard

Fields Copied to clipboard

3DSecure Copied to clipboard CONDITIONAL

Information on 3DSecure fields.

3DSecure.acsEci Copied to clipboard Digits CONDITIONAL

Indicates the security level of the transaction.

This is the value returned in the Electronic Commerce Indicator (ECI) field of the Payer Authentication Response (PARes) message from the card Issuer's Access Control Server (ACS). For example, 0,1, or 2. Refer to the relevant documentation for Mastercard SecureCode™, Verified by Visa™, JCB J/Secure™, American Express SafeKey™, or Diners Club ProtectBuy™.

Data is a string that consists of the characters 0-9.

Min length: 1 Max length: 2
3DSecure.authenticationRedirect Copied to clipboard CONDITIONAL

A collection of parameters required to build the HTML form that is redirected to the ACS.

There are two options to generate the redirect page used to transfer the cardholder to the card Issuer's Access Control Server (ACS) for authentication:

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.

3DSecure.authenticationRedirect.pageGenerationMode Copied to clipboard Enumeration CONDITIONAL

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.

The response to the Check 3DS Enrollment operation will include the information required for the selected option. By default, the Simple option is used.

An enumeration to allow a user to specify if they wish to adopt a customized solution or a simple solution.

Value must be a member of the following list. The values are case sensitive.

CUSTOMIZED

A strategy to indicate that the user wishes to customize the response

SIMPLE

A simple interaction model where the response is complete and no user intervention is required.

3DSecure.authenticationRedirect.responseUrl Copied to clipboard Url CONDITIONAL

The URL to which you want to redirect the payer after completing the payer authentication process.

Typically, this will be the merchant's website URL, which must be URL encoded for special characters such spaces, hyphens, etc.

Ensure that the URL begins with 'https' and is longer than 11 characters.

3DSecure.authenticationRedirect.simple Copied to clipboard CONDITIONAL

The details required by the system to generate the HTML page as specified in the Simple option.

3DSecure.authenticationRedirect.simple.expectedHtmlEncoding Copied to clipboard Enumeration CONDITIONAL

The encoding required for the HTML returned in the response, through htmlBodyContent parameter.

The available HTML Encoding options that a client may request.

Value must be a member of the following list. The values are case sensitive.

ASCII
ISO_8859_1

Latin1

UTF_8
3DSecure.authenticationRedirect.simple.redirectDisplayBackgroundColor Copied to clipboard Alphanumeric + additional characters CONDITIONAL

Background color of the page, encoded in HEX, rendered in the cardholder's browser while the browser is waiting for the authentication to commence.

By default, the color is set to #FFFFFF.

Data may consist of the characters 0-9, a-z, A-Z, '#'

Min length: 4 Max length: 7
3DSecure.authenticationRedirect.simple.redirectDisplayContinueButtonText Copied to clipboard String CONDITIONAL

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.

By default, the button text is set to "Click here to continue".

Data can consist of any characters

Min length: 1 Max length: 40
3DSecure.authenticationRedirect.simple.redirectDisplayTitle Copied to clipboard String CONDITIONAL

Title of the page rendered in the cardholder's browser while the browser is waiting for the authentication to commence.

By default, the title is set to "Process secure Payment".

Data can consist of any characters

Min length: 1 Max length: 200
3DSecure.authenticationToken Copied to clipboard Base64 CONDITIONAL

Used to verify that the 3D-Secure authentication occurred and the 3-D Secure data provided is valid.

The authentication token is generated and returned by the card issuer's Access Control Server (ACS) or the scheme's Attempts Server. It is a Base64 encoded value and must be submitted unaltered on a transaction. This field is referred to as Accountholder Authentication Value (AAV) for Mastercard SecureCode™ and JCB J/Secure™, Cardholder Authentication Verification Value (CAVV) for Verified by Visa™, American Express Verification Value (AEVV) for American Express SafeKey™, or Cardmember Authentication Verification Value (CAVV) for Diners Club ProtectBuy™.

Data is Base64 encoded

allowable lengths 28 or 32
3DSecure.goodsDescription Copied to clipboard String CONDITIONAL

An optional field that the merchant may supply in the Transaction Request as a description of the transaction.

If supported by the ACS, this description will be displayed on the authentication page where the cardholder types in their secret password.

Data can consist of any characters

Min length: 0 Max length: 30
3DSecure.paResStatus Copied to clipboard Alpha CONDITIONAL

Indicates the result of payer authentication with the issuer.

This is the value returned in the transaction status field of the Payer Authentication Response (PARes) message from the card Issuer's Access Control Server (ACS). For example, Y, N, A, or U. Refer to the relevant documentation for Mastercard SecureCode™, Verified by Visa™, JCB J/Secure™, American Express SafeKey™, or Diners Club ProtectBuy™.

Data may consist of the characters a-z, A-Z

Min length: 1 Max length: 1
3DSecure.veResEnrolled Copied to clipboard Alpha CONDITIONAL

Indicates whether or not payer authentication is available for the card number you provided.

This is the value returned in the 'enrolled' field of the Verify Enrollment Response (VERes) message from the card scheme's Directory Server. For example, Y, N, or U. Refer to the relevant documentation for Mastercard SecureCode™, Verified by Visa™, JCB J/Secure™, American Express SafeKey™, or Diners Club ProtectBuy™.

Data may consist of the characters a-z, A-Z

Min length: 1 Max length: 1
3DSecure.xid Copied to clipboard Base64 CONDITIONAL

A unique transaction identifier generated by the Payment Gateway on behalf of the merchant to identify the 3DS transaction.

This field is mandatory for Verified By Visa transactions if authentication was available. The XID should be used in operation requests unaltered.

Data is Base64 encoded

allowable length 28
3DSecureId Copied to clipboard ASCII Text CONDITIONAL

A unique identifier supplied by the merchant for the authentication.

It is first defined in the check3DSEnrollment operation, and then included in subsequent operations.It is not used when the authentication is performed externally.

Data consists of ASCII characters

Min length: 1 Max length: 64
agreement Copied to clipboard CONDITIONAL

A series of related orders that execute one commercial agreement.

For example, linking the orders for a series of recurring payments (a mobile phone subscription), split tenders (one payment using two cards), or when the merchant offers to take payments by a series of installments (hire purchase).

agreement.expiryDate Copied to clipboard Date CONDITIONAL

Date at which your agreement with the payer to process payments expires.

Data must comply with ISO 8601 extended date format, yyyy-mm-dd

agreement.id Copied to clipboard String CONDITIONAL

Your identifier for the agreement you have with the payer to process payments.

When you collect cards from your payers and store them for later use, you must provide an agreement ID when you use the stored values for:

  • Recurring payments: you have an agreement with the payer that authorizes you to automatically debit their account at agreed intervals for fixed or variable amounts. For example, gym membership, phone bills, or magazine subscriptions.
  • Installment payments: you have an agreement with the payer that authorizes you to process multiple payments over an agreed period of time for a single purchase. For example, the payer purchases an item for $1000 and pays for it in four monthly installments.
  • Unscheduled: you have an agreement with the payer that authorizes you to process future payments when required. For example, the payer authorizes you to process an account top-up transaction for a transit card when the account balance drops below a certain threshold.

Data can consist of any characters

Min length: 1 Max length: 100
agreement.recurring Copied to clipboard CONDITIONAL

Information about agreements for recurring payments.

agreement.recurring.daysBetweenPayments Copied to clipboard Integer CONDITIONAL

The minimum number of days between payments agreed with the payer under your agreement with them.

A number comprising the digits 0-9, having at least one digit. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#nonNegativeInteger.)

Min value: 1 Max value: 999
airline Copied to clipboard CONDITIONAL

Airline industry specific data.

airline.bookingReference Copied to clipboard Alphanumeric CONDITIONAL

The record locator used to access a specific Passenger Name Record (PNR).

PNR is a record in the database of a booking system that contains the itinerary for a passenger, or a group of passengers traveling together.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 6 Max length: 15
airline.documentType Copied to clipboard Enumeration CONDITIONAL

The type of charge associated with the transaction.

Document Type Code

Value must be a member of the following list. The values are case sensitive.

ADDITIONAL_COLLECTION

Additional Collection

AGENCY_EXCHANGE_ORDER

Agency Exchange Order

AGENCY_GROUP_TICKET

Agency Group Ticket

AGENCY_MISCELLANEOUS_CHARGE_ORDER

Agency Misc. Charge Order (MCO)

AGENCY_PASSENGER_TICKET

Agency Passenger Ticket

AGENCY_TOUR_ORDER_OR_VOUCHER

Agency Tour Order/Voucher

AIR_FREIGHT

SPD/Air Freight

ANIMAL_TRANSPORTATION_CHARGE

Animal Transportation Charge

CATALOGUE_MERCHANDISE_ORDERED

Catalogue Merchandise Ordered

CLUB_MEMBERSHIP_FEE

Club Membership Fee

COUPON_BOOK

Coupon Book

CREDIT_CLASS_SERVICE_ADJUSTMENT

Credit Class of Service Adjustment

CREDIT_DENIED_BOARDING

Credit Denied Boarding

CREDIT_EXCHANGE_REFUND

Credit Exchange Refund

CREDIT_LOST_TICKET_REFUND

Credit Lost Ticket Refund

CREDIT_MISCELLANEOUS_REFUND

Credit Misc. Refund

CREDIT_MULTIPLE_UNUSED_TICKETS

Credit Multiple Unused Tickets

CREDIT_OVERCHARGE_ADJUSTMENT

Credit Overcharge Adjustment

CREDIT_UNUSED_TRANSPORTATION

Credit Unused Transportation

DEBT_ADJUSTMENT_DUPLICATE_REFUND_OR_USE

Debt Adjustment Duplicate Refund/Use

DUTY_FREE_SALE

Duty Free Sale

EXCESS_BAGGAGE

Excess Baggage

EXCHANGE_ADJUSTMENT

Exchange Adjustment

EXCHANGE_ORDER

Exchange Order

FIREARMS_CASE

Firearms Case

FREQUENT_FLYER_FEE_OR_PURCHASE

Frequent Flyer Fee/Purchase

FREQUENT_FLYER_FULFILLMENT

Frequent Flyer Fulfillment

FREQUENT_FLYER_OVERNIGHT_DELIVERY_CHARGE

Frequent Flyer Overnight Delivery Charge

GROUP_TICKET

Group Ticket

IN_FLIGHT_ADJUSTMENT

In-flight Adjustment

IN_FLIGHT_CHARGES

In-flight Charges

IN_FLIGHT_DUTY_FREE_PURCHASE

In-flight Duty Free Purchase

IN_FLIGHT_MERCHANDISE_ORDERED

In-flight Merchandise Ordered

IN_FLIGHT_PHONE_CHARGES

In-flight Phone Charges

KENNEL_CHARGE

Kennel Charge

LOST_TICKET_APPLICATION

Lost Ticket Application

MISCELLANEOUS_CHARGE_ORDER_OR_PREPAID_TICKET_ADVICE

Misc. Charge Order (MCO) / Prepaid Ticket Auth.

MISCELLANEOUS_TAXES_FEES

Miscellaneous Tax(es) Fee(s)

PASSENGER_TICKET

Passenger Ticket

SELF_SERVICE_TICKETS

Self-Service Ticket(s)

SENIOR_CITIZEN_DISCOUNT_BOOKLETS

Senior Citizen Discount Booklets

SMALL_PACKAGE_DELIVERY

Small Package Delivery

SPECIAL_SERVICE_TICKET

Special Service Ticket

SUPPORTED_REFUND

Supported Refund

TICKET_BY_MAIL

Ticket by Mail

TOUR_DEPOSIT

Tour Deposit

TOUR_ORDER_VOUCHER

Tour Order Voucher

UNDERCHARGE_ADJUSTMENT

Undercharge Adjustment

UNSUPPORTED_REFUND

Unsupported Refund

UPGRADE_CHARGE

Upgrade Charge

VENDOR_REFUND_CREDIT

Vendor Refund Credit

VENDOR_SALE

Vendor Sale

airline.itinerary Copied to clipboard CONDITIONAL

Itinerary details

airline.itinerary.leg[n] Copied to clipboard CONDITIONAL

Travel leg details.

airline.itinerary.leg[n].carrierCode Copied to clipboard Regex CONDITIONAL

The 2-character IATA airline code or 3 digit accounting code or both of the airline carrier for the trip leg.

Data must match regex

regex \w{2}|\d{3}|\w{2}/\d{3} message Carrier code must be 2 characters, 3 digits or a combination of both in the format: ZZ/999
airline.itinerary.leg[n].conjunctionTicketNumber Copied to clipboard Alphanumeric CONDITIONAL

The ticket containing the coupon for this leg for an itinerary with more than four trip legs.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 11 Max length: 16
airline.itinerary.leg[n].couponNumber Copied to clipboard Alphanumeric CONDITIONAL

The coupon number on the ticket for the trip leg.

Each trip leg requires a separate coupon. The coupon within the series is identified by the coupon number.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 1 Max length: 1
airline.itinerary.leg[n].departureAirport Copied to clipboard Upper case alphabetic text CONDITIONAL

The 3 character IATA airport code of the departure airport for the trip leg.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
airline.itinerary.leg[n].departureDate Copied to clipboard Date CONDITIONAL

Date of departure for the trip leg.

Data must comply with ISO 8601 extended date format, yyyy-mm-dd

airline.itinerary.leg[n].departureTax Copied to clipboard Decimal CONDITIONAL

Tax payable on departure for the trip leg.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
airline.itinerary.leg[n].departureTime Copied to clipboard Time CONDITIONAL

Departure time in local time for the departure airport for this trip leg.

Data must comply with ISO 8601 extended time formats, hh:mm[:ss]Z or hh:mm[:ss](+/-)hh[:mm]

airline.itinerary.leg[n].destinationAirport Copied to clipboard Upper case alphabetic text CONDITIONAL

The 3 character IATA airport code for the destination airport for the trip leg.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
airline.itinerary.leg[n].destinationArrivalDate Copied to clipboard Date CONDITIONAL

Arrival date in local time for the destination airport for this trip leg.

Data must comply with ISO 8601 extended date format, yyyy-mm-dd

airline.itinerary.leg[n].destinationArrivalTime Copied to clipboard Time CONDITIONAL

Arrival time in local time for the destination airport for this trip leg.

Data must comply with ISO 8601 extended time formats, hh:mm[:ss]Z or hh:mm[:ss](+/-)hh[:mm]

airline.itinerary.leg[n].endorsementsRestrictions Copied to clipboard Alphanumeric CONDITIONAL

Restrictions (e.g. non-refundable) or endorsements applicable to the trip leg.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 1 Max length: 20
airline.itinerary.leg[n].exchangeTicketNumber Copied to clipboard Alphanumeric CONDITIONAL

New ticket number issued when a ticket is exchanged for the trip leg.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 11 Max length: 16
airline.itinerary.leg[n].fare Copied to clipboard Decimal CONDITIONAL

Total fare payable for the trip leg.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
airline.itinerary.leg[n].fareBasis Copied to clipboard Alphanumeric CONDITIONAL

Code defining the rules forming the basis of the fare (type of fare, class entitlement, etc.)

Data may consist of the characters 0-9, a-z, A-Z

Min length: 1 Max length: 24
airline.itinerary.leg[n].fees Copied to clipboard Decimal CONDITIONAL

Total fees payable for the trip leg.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
airline.itinerary.leg[n].flightNumber Copied to clipboard Alphanumeric CONDITIONAL

The flight number for the trip leg.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 4 Max length: 6
airline.itinerary.leg[n].stopoverPermitted Copied to clipboard Boolean CONDITIONAL

Indicates if a stopover is permitted for the trip leg.

The values 'true' or 'false'. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#boolean.)

airline.itinerary.leg[n].taxes Copied to clipboard Decimal CONDITIONAL

Total taxes payable for the trip leg.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
airline.itinerary.leg[n].travelClass Copied to clipboard Alphanumeric CONDITIONAL

The industry code indicating the class of service (e.g. Business, Coach) for the leg.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 1 Max length: 3
airline.itinerary.numberInParty Copied to clipboard Digits CONDITIONAL

Number of passengers associated with this booking.

Data is a string that consists of the characters 0-9.

Min length: 1 Max length: 3
airline.itinerary.originCountry Copied to clipboard Upper case alphabetic text CONDITIONAL

The 3 character ISO 3166-1 alpha-3 country code of the country of origin for the itinerary.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
airline.passenger[n] Copied to clipboard CONDITIONAL

Passenger details

airline.passenger[n].firstName Copied to clipboard String CONDITIONAL

First name of the passenger to whom the ticket is being issued.

Data can consist of any characters

Min length: 1 Max length: 50
airline.passenger[n].frequentFlyerNumber Copied to clipboard String CONDITIONAL

Frequent Flyer or Loyalty Program number for this passenger.

Data can consist of any characters

Min length: 1 Max length: 20
airline.passenger[n].lastName Copied to clipboard String CONDITIONAL

Last name of the passenger to whom the ticket is being issued.

Data can consist of any characters

Min length: 1 Max length: 20
airline.passenger[n].middleName Copied to clipboard String CONDITIONAL

Middle name of the passenger to whom the ticket is being issued.

Data can consist of any characters

Min length: 1 Max length: 50
airline.passenger[n].specificInformation Copied to clipboard Alphanumeric CONDITIONAL

Passenger specific information recorded on the ticket.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 1 Max length: 59
airline.passenger[n].title Copied to clipboard String CONDITIONAL

Title of the passenger to whom the ticket is being issued.

Data can consist of any characters

Min length: 1 Max length: 20
airline.planNumber Copied to clipboard Alphanumeric CONDITIONAL

Plan number supplied by the airline for this booking.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 2 Max length: 2
airline.ticket Copied to clipboard CONDITIONAL

Ticket details

airline.ticket.conjunctionTicketIndicator Copied to clipboard Boolean CONDITIONAL

Indicates if a conjunction ticket with additional coupons was issued.

Conjunction ticket refers to two or more tickets concurrently issued to a passenger and which together constitute a single contract of carriage.

The values 'true' or 'false'. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#boolean.)

airline.ticket.eTicket Copied to clipboard Boolean CONDITIONAL

Indicates if an electronic ticket was issued.

The values 'true' or 'false'. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#boolean.)

airline.ticket.exchangedTicketNumber Copied to clipboard Alphanumeric CONDITIONAL

The original ticket number when this is a transaction for an exchanged ticket.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 11 Max length: 16
airline.ticket.issue Copied to clipboard CONDITIONAL

Ticket issue information.

airline.ticket.issue.address Copied to clipboard String CONDITIONAL

The address where the ticket was issued.

Data can consist of any characters

Min length: 1 Max length: 16
airline.ticket.issue.carrierCode Copied to clipboard Regex CONDITIONAL

The 2-character IATA airline code or 3 digit accounting code or both of the airline carrier issuing the ticket.

Data must match regex

regex \w{2}|\d{3}|\w{2}/\d{3} message Carrier code must be 2 characters, 3 digits or a combination of both in the format: ZZ/999
airline.ticket.issue.carrierName Copied to clipboard Alphanumeric CONDITIONAL

Name of airline carrier issuing the ticket.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 1 Max length: 25
airline.ticket.issue.city Copied to clipboard Alphanumeric CONDITIONAL

The city/town where the ticket was issued.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 1 Max length: 18
airline.ticket.issue.country Copied to clipboard Upper case alphabetic text CONDITIONAL

The 3 character ISO 3166-1 alpha-3 country code of the country where the ticket was issued.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
airline.ticket.issue.date Copied to clipboard Date CONDITIONAL

The date the ticket was issued.

Data must comply with ISO 8601 extended date format, yyyy-mm-dd

airline.ticket.issue.travelAgentCode Copied to clipboard Alphanumeric CONDITIONAL

Industry code of the travel agent issuing the ticket.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 8 Max length: 9
airline.ticket.issue.travelAgentName Copied to clipboard Alphanumeric CONDITIONAL

Name of the travel agent issuing the ticket.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 1 Max length: 30
airline.ticket.restricted Copied to clipboard Boolean CONDITIONAL

Indicates if the issued ticket is refundable.

The values 'true' or 'false'. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#boolean.)

airline.ticket.taxOrFee[n] Copied to clipboard CONDITIONAL

Breakdown of the ticket taxes, airport taxes, charges and fees for an airline ticket purchase.

The total of the amounts in this group should equal the sum of the airline.ticket.totalFees and airline.ticket.totalTaxes fields.

airline.ticket.taxOrFee[n].amount Copied to clipboard Decimal CONDITIONAL

The tax, charge or fee amount payable.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
airline.ticket.taxOrFee[n].type Copied to clipboard Alphanumeric CONDITIONAL

The tax, charge or fee type code as assigned by IATA.

For example, the IATA tax/ charge/ fee type for Passenger Movement Charge (PMC) in Australia is TT1.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 3 Max length: 3
airline.ticket.ticketNumber Copied to clipboard Alphanumeric CONDITIONAL

The airline ticket number associated with the transaction.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 11 Max length: 16
airline.ticket.totalFare Copied to clipboard Decimal CONDITIONAL

Total fare for all trip legs on the ticket.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
airline.ticket.totalFees Copied to clipboard Decimal CONDITIONAL

Total fee for all trip legs on the ticket.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
airline.ticket.totalTaxes Copied to clipboard Decimal CONDITIONAL

Total taxes for all trip legs on the ticket.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
airline.transactionType Copied to clipboard Enumeration CONDITIONAL

The type of transaction performed against this airline booking.

Transaction Type

Value must be a member of the following list. The values are case sensitive.

EXCHANGE_TICKET

Exchange Ticket

MISCELLANEOUS_CHARGE

Miscellaneous Charge

REFUND

Refund

REVERSAL

Reversal

TICKET_PURCHASE

Ticket Purchase

TOUR_ORDER

Tour Order

authentication Copied to clipboard CONDITIONAL

Information about how the payer's identity is verified.

For example, using 3-D Secure authentication.

This parameter group include payer authentication options available to you, parameters you need to perform payer authentication for an available method, and the results of payer authentication.

authentication.3ds2 Copied to clipboard CONDITIONAL

Information about payer authentication using 3-D Secure authentication version 2.

authentication.3ds2.sdk Copied to clipboard CONDITIONAL

Information provided by the 3-D Secure Software Development Kit (SDK) that is used by an app on the payer's device to enable 3-D Secure authentication of the payer to be performed in-app.

You must populate the fields in this parameter group when you authenticate the payer in-app using 3-D Secure authentication version 2.

authentication.3ds2.sdk.appId Copied to clipboard String CONDITIONAL

A unique identifier for the app on the payer's device.

The 3-D Secure SDK generates this identifier each time the app is installed or updated.

This field corresponds to EMVCo field sdkAppID

Data can consist of any characters

Min length: 36 Max length: 36
authentication.3ds2.sdk.encryptedData Copied to clipboard String CONDITIONAL

Information about the payer's device collected and encrypted by the 3-D Secure SDK.

The data is a JSON Web Encryption (JWE) object in JSON format. When using the REST/JSON gateway API, express this as a JSON string (i.e. the embedded quotes will be escaped).

This field corresponds to EMVCo field sdkEncData

Data can consist of any characters

Min length: 0 Max length: 64000
authentication.3ds2.sdk.ephemeralPublicKey Copied to clipboard JSON Text CONDITIONAL

A public key generated by the 3-D Secure SDK.

This key is used to establish a secure session between the 3DS SDK and the issuer's Access Control Server (ACS) when the payer is required to be presented with an authentication challenge.

The key is a JSON Web Key (JWK) object in JSON format. When using the REST/JSON gateway API, express this as a JSON string (i.e the embedded quotes will be escaped).

This field corresponds to EMVCo field sdkEphemPubKey

Data is valid Json Format

Min length: 0 Max length: 256
authentication.3ds2.sdk.interface Copied to clipboard Enumeration CONDITIONAL

The User Interface (UI) formats that the payer's device supports.

These are the formats that can be used to render the screens presented to the payer during an authentication challenge.

You only need to provide this value if you only support one of these formats.

This field corresponds to EMVCo data element sdkInterface in the field deviceRenderOptions.

Value must be a member of the following list. The values are case sensitive.

HTML

The device supports HTML format.

NATIVE

The device supports the UI format native to the payer's device.

authentication.3ds2.sdk.referenceNumber Copied to clipboard String CONDITIONAL

An identifier of the vendor and version of the 3-D Secure SDK assigned by EMVCo.

This field corresponds to EMVCo field sdkReferenceNumber

Data can consist of any characters

Min length: 32 Max length: 32
authentication.3ds2.sdk.timeout Copied to clipboard Integer CONDITIONAL

The duration (in seconds) available to the payer to authenticate.

Will default to 900 if not provided. Note: The value will be rounded up to the nearest minute.

This field corresponds to EMVCo field sdkMaxTimeout

A number comprising the digits 0-9, having at least one digit. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#nonNegativeInteger.)

Min value: 300 Max value: 900
authentication.3ds2.sdk.transactionId Copied to clipboard String CONDITIONAL

A unique identifier assigned by the 3-D Secure SDK for the transaction.

This field corresponds to EMVCo field sdkTransID

Data can consist of any characters

Min length: 36 Max length: 36
authentication.3ds2.sdk.uiType Copied to clipboard Comma separated enumeration CONDITIONAL

Indicates the UI types which the SDK supports for displaying authentication challenges within the app.

A comma separated list of the payer authentication methods that you will accept for this payment.

You only need to provide this value if all of these values are not supported.

Note: OTHER_HTML is only supported when authentication.3ds2.sdk.interface allows a HTML UI format.

This field corresponds to EMVCo data element sdkUiType in the field deviceRenderOptions.

Value must be one or more comma separated members of the following list. The values are case sensitive.

TEXT

The payer is asked to enter text into a field displayed on the UI. For example, ask the payer to enter a One Time Password sent to their registered mobile phone number.

SINGLE_SELECT

The payer is asked to select a single option from a number of presented options. For example, ask the payer if they want a One Time Password to be sent to either their email address or mobile phone number registered with their issuer.

MULTI_SELECT

The payer is asked to select multiple options from a number of presented options. For example, ask the payer to select valid responses to a question.

OUT_OF_BAND

The payer is presented with screens rendered by an out-of-band service during an authentication challenge, For example, the payer is asked to confirm the payment from their banking app.

OTHER_HTML

The payer is presented with an authentication challenge using other mechanisms supported in HTML but not in the native UI format. For example, the payer is asked to confirm an image presented on the screen.

authentication.acceptVersions Copied to clipboard Comma Separated Enumeration CONDITIONAL

A comma separated list of the payer authentication methods that you will accept for this payment.

You only need to provide a value if you want to restrict the authentication methods you will accept.

If you do not specify a value, then the gateway treats it as if you will accept all available authentication methods.

If you accept both 3DS2 and 3DS1, then the gateway will use 3-D Secure version 2 if supported by the issuer and fallback to use 3-D Secure version 1 if it is not.

Value must be one or more comma separated members of the following list. The values are case sensitive.

3DS1

3-D Secure Version 1

3DS2

3-D Secure Version 2

authentication.challengePreference Copied to clipboard Enumeration CONDITIONAL

Indicates if you want the payer to be presented with an authentication challenge for this transaction.

You can use this to support local mandates or your risk tolerance. For example, you may prefer that a challenge is always performed when you store card details on file.

If you do not provide a value, the gateway will use NO_PREFERENCE. If there is no payer present (for example, recurring payments), then the gateway will ignore this field and use NO_CHALLENGE.

Note: 'challenge' means requiring the payer to take action to identify themselves, for example, entering a password.

Value must be a member of the following list. The values are case sensitive.

CHALLENGE_MANDATED

The merchant requires that the payer is presented with an authentication challenge.

CHALLENGE_PREFERRED

The merchant prefers that the payer is presented with an authentication challenge.

NO_CHALLENGE

The merchant prefers that the payer is not presented with an authentication challenge.

NO_PREFERENCE

The issuer determines whether or not the payer should be presented with an authentication challenge. The merchant does not have a preference.

authentication.channel Copied to clipboard Enumeration CONDITIONAL

Indicates the channel in which the authentication request is being initiated.

Value must be a member of the following list. The values are case sensitive.

MERCHANT_REQUESTED

The merchant is requesting authentication of a cardholder without the payer being available for interaction (for example. as part of processing of a recurring payment).

PAYER_APP

Payer is interacting via an application on their device which uses an EMVCo-certified SDK.

PAYER_BROWSER

Payer is interacting via web browser (for example, with the merchant's ecommerce web-site).

authentication.goodsDescription Copied to clipboard String CONDITIONAL

Description of the goods being purchased.

If supported, this description will be displayed on the authentication UI presented to the payer.

Data can consist of any characters

Min length: 0 Max length: 30
authentication.purpose Copied to clipboard Enumeration CONDITIONAL

Indicates the context in which payer authentication is being requested.

If you do not provide a value, the gateway will use PAYMENT_TRANSACTION as the default.

Note:

  • • If you set this value to ADD_CARD or MAINTAIN_CARD, then set order.amount to zero and order.currency to any currency you support.
  • • If the authentication scheme that applies to the account does not support the purpose that you have requested, this call will return an authenticationStatus of AUTHENTICATION_NOT_SUPPORTED.

Value must be a member of the following list. The values are case sensitive.

ADD_CARD

Authentication performed before a payer's card is stored on file either directly by the merchant or using the gateway's tokenization feature. A payment is not being processed.

MAINTAIN_CARD

Authentication performed before updating details of a payer's card stored on file either directly by the merchant or using the gateway's tokenization feature. A payment is not being processed.

PAYMENT_TRANSACTION

Authentication performed when of processing a card payment.

authentication.redirectResponseUrl Copied to clipboard Url CONDITIONAL

The URL to which you want to redirect the payer after completing the payer authentication process.

This will be a URL on your website, with the URL encoded as defined in RFC3986. This means special characters such spaces, hyphens, etc must be encoded.

You must provide this URL, unless you are certain that there will be no interaction with the payer.

Ensure that the URL begins with 'https' and is longer than 11 characters.

authorizationResponse Copied to clipboard CONDITIONAL

Authorisation response fields for a standalone capture request.

authorizationResponse.avsCode Copied to clipboard ASCII Text CONDITIONAL

The acquirer AVS response code generated by the card issuing institution.

Data consists of ASCII characters

Min length: 1 Max length: 100
authorizationResponse.cardLevelIndicator Copied to clipboard String CONDITIONAL

Indicates the card level result returned by the issuer.

Data can consist of any characters

Min length: 1 Max length: 2
authorizationResponse.cardSecurityCodeError Copied to clipboard String CONDITIONAL

CSC Incorrect Indicator.

An indicator, provided by the Issuer in the authorization response, to identify the presence of an invalid card security code (CSC). If there is an error, the Issuer will respond with the 1-byte CSC Error Code (Y).

Data can consist of any characters

Min length: 1 Max length: 1
authorizationResponse.cardSecurityCodePresenceIndicator Copied to clipboard Alphanumeric CONDITIONAL

An Indicator, if a Card security code was provided for the Transaction, as returned by the acquirer.

Data may consist of the characters 0-9, a-z, A-Z

Min length: 1 Max length: 2
authorizationResponse.commercialCard Copied to clipboard String CONDITIONAL

Indicates if the card used is a commercial card.

Data can consist of any characters

Min length: 1 Max length: 3
authorizationResponse.commercialCardIndicator Copied to clipboard String CONDITIONAL

Indicates the type of commercial card as returned by the card issuer.

Data can consist of any characters

Min length: 1 Max length: 1
authorizationResponse.financialNetworkCode Copied to clipboard String CONDITIONAL

Indicates the code of the financial network that was used to process the transaction with the issuer.

Data can consist of any characters

Min length: 1 Max length: 3
authorizationResponse.financialNetworkDate Copied to clipboard Date CONDITIONAL

The date for the Authorization as returned by the financial network.

For transactions processed via the MasterCard Network this is the MasterCard Network Reference Date.

Data must comply with ISO 8601 extended date format, yyyy-mm-dd

authorizationResponse.marketSpecificData Copied to clipboard String CONDITIONAL

Indicates the market or the industry associated with the payment.

For example, B may indicate "bill payment" depending on the acquirer.

Data can consist of any characters

Min length: 1 Max length: 1
authorizationResponse.posData Copied to clipboard String CONDITIONAL

Indicates the specific card information conditions for capture that are available when the card transaction occurs at point of service.

Data can consist of any characters

Min length: 1 Max length: 13
authorizationResponse.posEntryMode Copied to clipboard String CONDITIONAL

The POS Entry Mode provided to Discover (JCB (US Domestic only), and Diners) for the authorization.

Bytes 1-2: Discover (JCB (US Domestic only), and Diners) POS Entry Mode
Byte 3: Discover (JCB (US Domestic only), and Diners) Pin Entry Capability
Byte 4: RFU (Always zero)

Note: Only the first 3 bytes are required for settlement processing.

Data can consist of any characters

Min length: 1 Max length: 4
authorizationResponse.processingCode Copied to clipboard String CONDITIONAL

Identifies the type of Card Transaction sent to Card Acceptor.

Data can consist of any characters

Min length: 1 Max length: 6
authorizationResponse.responseCode Copied to clipboard String CONDITIONAL

The response code which indicates the status of the transaction.

Data can consist of any characters

Min length: 1 Max length: 3
authorizationResponse.returnAci Copied to clipboard String CONDITIONAL

The ACI (Authorization Characteristics Indicator) returned by the issuer.

Data can consist of any characters

Min length: 1 Max length: 1
authorizationResponse.trackQuality Copied to clipboard String CONDITIONAL

Indicates the magnetic stripe condition and the vulnerability for fraud in Discover Network Card Transactions.

Data can consist of any characters

Min length: 1 Max length: 2
authorizationResponse.transactionIdentifier Copied to clipboard String CONDITIONAL

The unique identifier for the transaction returned by the issuer.

Data can consist of any characters

Min length: 1 Max length: 15
authorizationResponse.validationCode Copied to clipboard String CONDITIONAL

The validation code returned by the issuer.

This value must be stored to be sent with the capture transaction.

Data can consist of any characters

Min length: 1 Max length: 4
billing Copied to clipboard CONDITIONAL

Details of the payer's billing address.

billing.address Copied to clipboard CONDITIONAL

The payer's billing address.

This data may be used to qualify for better interchange rates on corporate purchase card transactions.

billing.address.city Copied to clipboard String CONDITIONAL

The city portion of the address.

Data can consist of any characters

Min length: 1 Max length: 100
billing.address.company Copied to clipboard String CONDITIONAL

The name of the company associated with this address.

Data can consist of any characters

Min length: 1 Max length: 100
billing.address.country Copied to clipboard Upper case alphabetic text CONDITIONAL

The 3 letter ISO standard alpha country code of the address.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
billing.address.postcodeZip Copied to clipboard Alphanumeric + additional characters CONDITIONAL

The post code or zip code of the address.

Data may consist of the characters 0-9, a-z, A-Z, ' ', '-'

Min length: 1 Max length: 10
billing.address.stateProvince Copied to clipboard String CONDITIONAL

The state or province of the address.

Data can consist of any characters

Min length: 1 Max length: 20
billing.address.stateProvinceCode Copied to clipboard String CONDITIONAL

The three character ISO 3166-2 country subdivision code for the state or province of the address.

Providing this field might improve your payer experience for 3-D Secure payer authentication.

Data can consist of any characters

Min length: 1 Max length: 3
billing.address.street Copied to clipboard String CONDITIONAL

The first line of the address.

For example, this may be the street name and number, or the Post Office Box details.

Data can consist of any characters

Min length: 1 Max length: 100
billing.address.street2 Copied to clipboard String CONDITIONAL

The second line of the address (if provided).

Data can consist of any characters

Min length: 1 Max length: 100
browserPayment Copied to clipboard CONDITIONAL

Information required by the gateway to manage interactions with a browser payment provider's website.

browserPayment.operation Copied to clipboard Enumeration CONDITIONAL

The type of transaction you want to create for this payment.You can choose between an Authorization and a Payment transaction.

For a successful Authorization transaction, you must submit a CAPTURE request to move the funds from the payer's account to your account.

Value must be a member of the following list. The values are case sensitive.

AUTHORIZE

The transaction created in the gateway is an AUTHORIZATION transaction.

PAY

The transaction created in the gateway is a PAYMENT transaction.

browserPayment.paypal Copied to clipboard CONDITIONAL

Additional information you can provide to control the user interaction flow presented to the payer by PayPal.

browserPayment.paypal.agreementConfirmation Copied to clipboard Enumeration CONDITIONAL

Indicates the action that PayPal displays to the payer prior to being redirected back to your website.

This field is only required when requesting a PayPal billing agreement.

Value must be a member of the following list. The values are case sensitive.

AGREE

After the payer has approved the billing agreement and their browser has been returned to your website, you will not process a payment against this billing agreement at that time.

AGREE_AND_PAY

After the payer has approved the billing agreement and their browser has been returned to your website, you will process a payment against this billing agreement.

browserPayment.paypal.displayShippingAddress Copied to clipboard Boolean CONDITIONAL

Indicates whether you want PayPal to display the shipping address to the payer on the PayPal website.

By default, the shipping address is displayed to the payer. For more detailed information about displaying the shipping address on the PayPal website, see PayPal Integration: Display/Override Shipping Address.

The values 'true' or 'false'. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#boolean.)

browserPayment.paypal.overrideShippingAddress Copied to clipboard Boolean CONDITIONAL

Indicates whether you want to allow the payer to change the shipping address for the payment on the PayPal website.

By default, the payer is allowed to change the shipping address. For more detailed information about the payer overriding the shipping address on the PayPal website, see PayPal Integration: Display/Override Shipping Address.

The values 'true' or 'false'. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#boolean.)

browserPayment.paypal.paymentConfirmation Copied to clipboard Enumeration CONDITIONAL

Indicates where in the checkout flow you want the payer to commit to the payment - on the PayPal website or on your website after returning from the PayPal website.

With the latter option, you must confirm the payment using the CONFIRM_BROWSER_PAYMENT operation.

Value must be a member of the following list. The values are case sensitive.

CONFIRM_AT_MERCHANT

The payer commits to the payment on your website.

CONFIRM_AT_PROVIDER

The payer commits to the payment on the PayPal website.

browserPayment.preferredLanguage Copied to clipboard String CONDITIONAL

The language that you prefer the payment provider to use for pages displayed to the payer.

Provide the IETF language tag for the language in accordance with RFC 5646. You can provide either the two-letter primary language tag (for example, en, fr) or the two-letter primary language tag plus the region sub-tag (for example, en-US, fr-CA).

Data must be a language identifier or IETF language tag

Min length: 2 Max length: 35
browserPayment.returnUrl Copied to clipboard Url CONDITIONAL

The URL to which you want the payer's browser to be redirected on completing the payment at the payment provider's website.

The same redirect URL will be used by the gateway to redirect the payer's browser irrespective of the success or otherwise of the payment.

Ensure that the URL begins with 'https' and is longer than 11 characters.

constraints Copied to clipboard CONDITIONAL

Information about any constraints that apply to this transaction.

Specify constraints to ensure that the transaction conforms to predefined criteria. This is useful if your integration does not directly collect all the transaction values (e.g. a session-based integration or a checkout integration).

constraints.paymentPlans Copied to clipboard CONDITIONAL

Information about the payment plan constraints which apply for this transaction.

Specify payment plan constraints to restrict the available payment plan options for this transaction.

constraints.paymentPlans.numberOfDeferrals Copied to clipboard Integer CONDITIONAL

The allowable number of deferral months for the payment plan.

A number comprising the digits 0-9, having at least one digit. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#nonNegativeInteger.)

Min value: 0 Max value: 99
constraints.paymentPlans.numberOfPayments Copied to clipboard Integer CONDITIONAL

The allowable number of installments for the payment plan.

A number comprising the digits 0-9, having at least one digit. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#nonNegativeInteger.)

Min value: 1 Max value: 99
constraints.paymentPlans.supported[n] Copied to clipboard String CONDITIONAL

The identifiers for the payment plans supported for this transaction.

If you wish to offer any payment plans to the payer, provide the plan identifiers in this field else pass it as empty.

See Payment Plans for the supported payment plans and their identifiers.

Data can consist of any characters

Min length: 1 Max length: 40
correlationId Copied to clipboard String CONDITIONAL

A transient identifier for the request, that can be used to match the response to the request.

The value provided is not validated, does not persist in the gateway, and is returned as provided in the response to the request.

Data can consist of any characters

Min length: 1 Max length: 100
currencyConversion Copied to clipboard CONDITIONAL

Information specific to the use of dynamic currency conversion (DCC).

If you requested a rate quote via the gateway, provide the requestId as returned in the PAYMENT_OPTIONS_INQUIRY response. For rate quote requests performed outside the gateway, you must at least provide payer amount, payer currency, provider and payer exchange rate.

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.

currencyConversion.exchangeRateTime Copied to clipboard DateTime CONDITIONAL

The timestamp of when the conversion rate is effective.

The timestamp may need to be displayed to the payer on the merchant site to satisfy regulatory requirements.

An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"

currencyConversion.marginPercentage Copied to clipboard Decimal CONDITIONAL

The foreign exchange markup applied as a percentage to the transaction amount for providing the conversion service.

The margin percentage may need to be displayed to the payer on the merchant site to satisfy regulatory requirements.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 8
currencyConversion.payerAmount Copied to clipboard Decimal CONDITIONAL

The total amount of the transaction in the payer's currency.

You must include this field if the payer accepted the DCC offer you presented to them.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
currencyConversion.payerCurrency Copied to clipboard Upper case alphabetic text CONDITIONAL

The currency of the DCC rate quote provided by your DCC Service Provider.

The currency must be expressed as an ISO 4217 alpha code, e.g. USD and must be different to that provided for transaction currency. You must include this field if the payer accepted the DCC offer you presented to them.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
currencyConversion.payerExchangeRate Copied to clipboard Decimal CONDITIONAL

The exchange rate used to convert the transaction amount into the payer's currency.

The payer exchange rate includes the foreign exchange markup (marginPercentage). The payer exchange rate is displayed to the payer on the merchant site.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 19
currencyConversion.provider Copied to clipboard Enumeration CONDITIONAL

This identifies the name of the provider of the DCC quote.

This data is for information purposes, and may be useful if you use multiple DCC providers.

Value must be a member of the following list. The values are case sensitive.

FEXCO
FTT
GLOBAL_PAYMENTS
IBM
TRAVELEX_CURRENCY_SELECT
UNICREDIT
currencyConversion.providerReceipt Copied to clipboard String CONDITIONAL

The quote provider's unique reference to the rate quote.

Data can consist of any characters

Min length: 1 Max length: 100
currencyConversion.requestId Copied to clipboard String CONDITIONAL

The unique identifier for your DCC quote request as returned in the PAYMENT_OPTIONS_INQUIRY response.

Data can consist of any characters

Min length: 1 Max length: 100
currencyConversion.uptake Copied to clipboard Enumeration CONDITIONAL

Indicates how DCC applies to the order.

If not provided, this value defaults to NOT_REQUIRED.

Value must be a member of the following list. The values are case sensitive.

ACCEPTED

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

DECLINED

The payer declined the DCC offer and pays in your transaction currency.

NOT_AVAILABLE

A 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_REQUIRED

DCC is not required for this transaction.

customer Copied to clipboard CONDITIONAL

Information associated with the customer's source of transaction.

customer.ani Copied to clipboard String CONDITIONAL

The telephone number captured by ANI (Automatic Number Identification) when the customer calls to place the order.

Data can consist of any characters

Min length: 1 Max length: 10
customer.aniCallType Copied to clipboard String CONDITIONAL

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.

Data can consist of any characters

Min length: 1 Max length: 2
customer.browser Copied to clipboard String CONDITIONAL

The User-Agent header of the browser the customer used to place the order.

For example, MOZILLA/4.0 (COMPATIBLE; MSIE 5.0; WINDOWS 95)

Data can consist of any characters

Min length: 1 Max length: 255
customer.dateOfBirth Copied to clipboard Date CONDITIONAL

The payer's date of birth.

Data must comply with ISO 8601 extended date format, yyyy-mm-dd

customer.email Copied to clipboard Email CONDITIONAL

The email address of the customer.

The field format restriction ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses.

Ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses

customer.firstName Copied to clipboard String CONDITIONAL

The payer's first name.

Data can consist of any characters

Min length: 1 Max length: 50
customer.hostname Copied to clipboard String CONDITIONAL

The name of the server to which the customer is connected.

Data can consist of any characters

Min length: 1 Max length: 60
customer.ipAddress Copied to clipboard String CONDITIONAL

The IP address of the computer used by the customer, in nnn.nnn.nnn.nnn format.

Data can consist of any characters

Min length: 7 Max length: 15
customer.lastName Copied to clipboard String CONDITIONAL

The payer's last or surname.

Data can consist of any characters

Min length: 1 Max length: 50
customer.mobilePhone Copied to clipboard Telephone Number CONDITIONAL

The payer's mobile phone or cell phone number in ITU-T E123 format, for example +1 607 1234 5678

The number consists of:

  • '+'
  • country code (1, 2 or 3 digits)
  • 'space'
  • national number ( which may embed single spaces characters for readability).

Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)

Mandatory country code: true Max total digits: 15
customer.nationalId Copied to clipboard String CONDITIONAL

An identifier for the payer assigned by a government authority.

For example, in Mexico this could be the CURP (Clave Única de Registro de Población), RFC (Registro Federal del Contribuyente), or INE (Instituto Nacional Electoral) number. In Brazil this could be the CPF (Cadastro de Pessoas Físicas) or CNPJ (Cadastro Nacional de Pessoas Jurídicas).

Data can consist of any characters

Min length: 1 Max length: 30
customer.phone Copied to clipboard Telephone Number CONDITIONAL

The payer's phone number in ITU-T E123 format, for example +1 607 1234 456

The number consists of:

  • '+'
  • country code (1, 2 or 3 digits)
  • 'space'
  • national number ( which may embed single spaces characters for readability).

Data consists of '+', country code (1, 2 or 3 digits), 'space', and national number (which may embed single space characters for readability)

Mandatory country code: true Max total digits: 15
customer.taxRegistrationId Copied to clipboard String CONDITIONAL

The tax registration identifier of the customer.

Data can consist of any characters

Min length: 1 Max length: 30
device Copied to clipboard CONDITIONAL

Information about the device used by the payer for this transaction.

device.ani Copied to clipboard String CONDITIONAL

The telephone number captured by ANI (Automatic Number Identification) when the customer calls to place the order.

Data can consist of any characters

Min length: 1 Max length: 10
device.aniCallType Copied to clipboard String CONDITIONAL

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.

Data can consist of any characters

Min length: 1 Max length: 2
device.browser Copied to clipboard String CONDITIONAL

The User-Agent header of the browser the customer used to place the order.For example, MOZILLA/4.0 (COMPATIBLE; MSIE 5.0; WINDOWS 95)

You must provide a value in this field if you are performing 3-D Secure authentication of the payer and set authentication.channel = PAYER_BROWSER.

Data can consist of any characters

Min length: 1 Max length: 255
device.browserDetails Copied to clipboard CONDITIONAL

Detailed information about the payer's browser.

If you are using 3-D Secure authentication to authenticate the payer, then this information is used by the issuer's Access Control Server (ACS) to identify the capabilities of the payers browser so that it can render content appropriately when authenticating the payer.

You must provide values for fields in this parameter group if you are performing 3-D Secure authentication of the payer and set authentication.channel = PAYER_BROWSER.

device.browserDetails.3DSecureChallengeWindowSize Copied to clipboard Enumeration CONDITIONAL

Dimensions of the challenge window (in width x height in pixels) displayed to the payer during 3D-Secure authentication.

Value must be a member of the following list. The values are case sensitive.

250_X_400
390_X_400
500_X_600
600_X_400
FULL_SCREEN
device.browserDetails.acceptHeaders Copied to clipboard String CONDITIONAL

The content of the Accept request-header field as sent from the payer's browser.

This is used to determine which content types are supported by the browser.

Data can consist of any characters

Min length: 1 Max length: 2048
device.browserDetails.colorDepth Copied to clipboard Integer CONDITIONAL

The bit depth (in bits per pixel) of the color palette for displaying images.

You obtain this value from the screen.colorDepth property of the payer's browser.

A number comprising the digits 0-9, having at least one digit. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#nonNegativeInteger.)

Min value: 1 Max value: 48
device.browserDetails.javaEnabled Copied to clipboard Boolean CONDITIONAL

Indicates whether or not the payer's browser supports Java.

You obtain this value from the navigator.javaEnabled property of the payer's browser

The values 'true' or 'false'. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#boolean.)

device.browserDetails.language Copied to clipboard String CONDITIONAL

The language supported for the payer's browser as defined in IETF BCP47.

You obtain this value from the navigator.language property of the payer's browser.

Data can consist of any characters

Min length: 1 Max length: 8
device.browserDetails.screenHeight Copied to clipboard Integer CONDITIONAL

The total height of the payer's browser screen in pixels.

You obtain this value from the screen.height property of the payer's browser

A number comprising the digits 0-9, having at least one digit. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#nonNegativeInteger.)

Min value: 1 Max value: 999999
device.browserDetails.screenWidth Copied to clipboard Integer CONDITIONAL

The total width of the payer's browser screen in pixels.

You obtain this value from the screen.width property of the payer's browser

A number comprising the digits 0-9, having at least one digit. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#nonNegativeInteger.)

Min value: 1 Max value: 999999
device.browserDetails.timeZone Copied to clipboard Browser Time Zone Offset CONDITIONAL

Time difference between UTC time and the Cardholder browser local time, in minutes.

The time zone offset is the difference, in minutes, between UTC and local time. Note that this means that the offset is positive if the local time zone is behind UTC and negative if it is ahead. For example, for time zone UTC+10:00 (Australian Eastern Standard Time, Vladivostok Time, Chamorro Standard Time), -600 would be presented.

Browser time zone offset between -840 to +840.

device.fingerprint Copied to clipboard String CONDITIONAL

Information collected about a remote computing device for the purpose of providing a unique identifier for the device.

For example, session ID, blackbox ID.

Data can consist of any characters

Min length: 1 Max length: 4000
device.hostname Copied to clipboard String CONDITIONAL

The name of the server to which the customer is connected.

Data can consist of any characters

Min length: 1 Max length: 60
device.ipAddress Copied to clipboard String CONDITIONAL

The IP address of the device used by the payer, in nnn.nnn.nnn.nnn format.

Data can consist of any characters

Min length: 7 Max length: 15
device.mobilePhoneModel Copied to clipboard String CONDITIONAL

The mobile phone manufacturer's identifier for the model of the mobile device used to initiate the payment.

Data can consist of any characters

Min length: 1 Max length: 255
gatewayEntryPoint Copied to clipboard Enumeration CONDITIONAL

The interface through which the transaction is submitted to the gateway.

Value must be a member of the following list. The values are case sensitive.

AUTO

The transaction was automatically generated by the gateway. For example, a Capture transaction for Auto-Capture or an order reversal transaction for risk rejected orders.

BATCH

The transaction was submitted as part of a merchant batch. Batches can either be uploaded via Batch or via Merchant Administration.

CHECKOUT

The transaction was created via checkout integration.

MERCHANT_ADMINISTRATION

The transaction was initiated in the Merchant Administration.

SERVICE_PROVIDER_API

The transaction was reported by an acquirer or alternate payment provider.

WEB_SERVICES_API

The transaction was submitted via Web Services API.

lineOfBusiness Copied to clipboard String CONDITIONAL

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.

Data can consist of any characters except space

Min length: 1 Max length: 100
locale Copied to clipboard String CONDITIONAL

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

By default, the language is determined from your configuration. Supply a value for this field only if you wish to override the default behavior. If the language you specify is not supported by the gateway, the payment is displayed in the best matching language.

See Dynamic Currency Conversion for more detail.

Data must be a language identifier or IETF language tag

Min length: 2 Max length: 5
merchant Copied to clipboard Alphanumeric + additional characters ALWAYS PROVIDED

The unique identifier issued to you by your payment provider.

This identifier can be up to 12 characters in length.

Data may consist of the characters 0-9, a-z, A-Z, '-', '_'

Min length: 1 Max length: 40
order Copied to clipboard ALWAYS PROVIDED

order

order.acceptPartialAmount Copied to clipboard Boolean CONDITIONAL

Indicates whether you will accept a payment less than order.amount, e.g. when using a gift card.

If not set or set to FALSE, and the full amount is not available, the transaction will be rejected.
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 values 'true' or 'false'. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#boolean.)

order.amount Copied to clipboard Decimal CONDITIONAL

The total amount for the order. This is the net amount plus any surcharge.

If you provide any sub-total amounts, then the sum of these amounts (order.itemAmount, order.taxAmount, order.shippingAndHandlingAmount, order.cashbackAmount, order.gratuityAmount), minus the order.discountAmount must equal the net amount.

The value of this field in the response may be zero if payer funds are not transferred.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
order.cashAdvance Copied to clipboard Boolean CONDITIONAL

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 values 'true' or 'false'. (For a complete description, see http://www.w3.org/TR/xmlschema-2/#boolean.)

order.cashbackAmount Copied to clipboard Decimal CONDITIONAL

The amount the payer has chosen to receive as cash in addition to the amount they are paying for the goods or services they are purchasing from you.

The cash back amount is included in the total amount of the order you provide in order.amount.

This field corresponds to EMV tag 9F03

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
order.certainty Copied to clipboard Enumeration CONDITIONAL

Indicates if you expect to capture the full order amount for which you are requesting authorization.

If you do not provide a value for order.certainty the default configured for you by your payment service provider will be used. The value provided in the response shows the value the gateway sent to the acquirer

Value must be a member of the following list. The values are case sensitive.

ESTIMATED

The amount authorized is an estimate of the amount that will be captured. It is possible that the amount captured will be less, or might not be captured at all.

FINAL

The full authorized amount is expected to be captured within the mandated time. The order will only be cancelled in exceptional circumstances (for example, the payer cancelled their purchase).

order.currency Copied to clipboard Upper case alphabetic text CONDITIONAL

The currency of the order expressed as an ISO 4217 alpha code, e.g. USD.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
order.custom Copied to clipboard String CONDITIONAL

Information about this order that is of interest to you.

For example order.custom.X, where 'X' is defined by you and must be less than 100 characters from the set A-Z, a-z, 0-9. For example, order.custom.salesRegion. You can specify up to 50 such fields. They are not sent to acquirers.

Data can consist of any characters

Min length: 1 Max length: 250
order.customerNote Copied to clipboard String CONDITIONAL

A note from the payer about this order.

Data can consist of any characters

Min length: 1 Max length: 250
order.customerOrderDate Copied to clipboard Date CONDITIONAL

The date the payer placed the order.

Data must comply with ISO 8601 extended date format, yyyy-mm-dd.

order.customerReference Copied to clipboard ASCII Text CONDITIONAL

The payer's own reference for the order.

This reference may assist the payer to identify the order in their system. For example, a purchase order number, project identifier, or cost center.

Data consists of ASCII characters

Min length: 0 Max length: 25
order.description Copied to clipboard String CONDITIONAL

Short textual description of the contents of the order for display to the payer on the payment provider's website.

Data can consist of any characters

Min length: 1 Max length: 127
order.discount Copied to clipboard CONDITIONAL

Information about a price reduction you have applied to the order.

For example, you may apply discounts for trade, employees, bulk purchase, or a sales promotion.

order.discount.amount Copied to clipboard Decimal CONDITIONAL

The total amount of the discount you have applied to the order.

Data is a string that consists of the characters 0-9 and '.' and represents a valid decimal number.

Min length: 1 Max length: 14
order.discount.code Copied to clipboard String CONDITIONAL

The code you use to identify the reason for the discount.

Data can consist of any characters

Min length: 1 Max length: 40
order.discount.description Copied to clipboard String CONDITIONAL

A description of your reason for the discount.

Data can consist of any characters

Min length: 1 Max length: 127
order.expectedNumberOfCaptures </