Update Browser Payment

Request to retrieve updated details of a browser payment transaction from the payment provider before you request the payment provider to process the payment. For PayPal payments, use this operation to determine if the payer changed the shipping address or if the payer agreed to the payment.
You must submit the same transaction ID as when initiating the payment.

PUT https://na.gateway.mastercard.com/api/rest/version/64 / merchant / {merchantId} / order / {orderid} / transaction / {transactionid}

Authentication Copied to clipboard

This operation requires authentication via one of the following methods:


  • Certificate authentication.
  • Basic HTTP authentication as described at w3.org. Provide 'merchant.<your gateway merchant ID>' in the userid portion and your API password in the password portion.

Request Copied to clipboard

URL Parameters Copied to clipboard

{merchantId} 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
{orderid} Copied to clipboard String REQUIRED

A unique identifier for this order to distinguish it from any other order you create.


Use this identifier when referring to this order in subsequent transactions and in retrieval operations. This value must be unique for every order you create using your merchant profile.


Data can consist of any characters

Min length: 1 Max length: 40
{transactionid} Copied to clipboard String REQUIRED

Unique identifier for this transaction to distinguish it from any other transaction on the order.


An order can have transactions representing:

  • Movement of money. For example, payments and refunds.
  • Validations. For example, account verification or 3-D Secure authentication of the payer.
  • Undoing other transactions. For example, voiding a payment transaction.
  • Chargebacks.
  • Fees from your payment service provider.
Each transaction on the order must have a unique id that identifies that transaction. Some transactions also hold the transaction identifier of other transactions on the order. For example a void payment transaction references the original payment transaction that is being voided.

If you attempt an operation and it fails (eg you try to PAY on a card with no funds), then you need a new id for each retry.


Data can consist of any characters

Min length: 1 Max length: 40

Fields Copied to clipboard

apiOperation Copied to clipboard String = UPDATE_BROWSER_PAYMENT 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
session.id Copied to clipboard ASCII Text OPTIONAL

Identifier of the payment session containing values for any of the request fields to be used in this operation.

Values provided in the request will override values contained in the 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

Response Copied to clipboard

Fields Copied to clipboard

action Copied to clipboard CONDITIONAL

Actions that you want the gateway to perform.

action.refundAuthorization Copied to clipboard Boolean CONDITIONAL

Use this field to indicate that you want the gateway to authorize the Refund with the issuer before submitting it to the acquirer.

Depending on your merchant profile configuration the gateway may or may not already attempt to authorize the Refund with the issuer before submitting it to the acquirer.

JSON boolean values 'true' or 'false'.

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

You must provide this data for some types of payments (such as recurring), but you can provide it for any cases where you want to link orders together.

agreement.amountVariability Copied to clipboard Enumeration CONDITIONAL

Indicates if all the payments within the agreement use the same amount or if the amount differs between the payments.

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

FIXED

All payments in the recurring payment agreement have the same amount. Examples include magazine subscriptions or gym memberships.

VARIABLE

The amount for the payments within the recurring payment agreement differs between payments. Examples include usage-based charges like utility or phone bills.

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.
When you first establish an agreement with the payer you should also specify the type of agreement in agreement.type.

Data can consist of any characters

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

The maximum amount for a single payment in the series as agreed with the payer under your agreement with them.

The amount must be provided in the currency of the order.

Data is a decimal number.

Max value: 99999999999999 Min value: 0 Max post-decimal digits: 3
agreement.minimumDaysBetweenPayments Copied to clipboard Integer CONDITIONAL

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

JSON number data type, restricted to being positive or zero. In addition, the represented number may have no fractional part.

Min value: 1 Max value: 9999
agreement.numberOfPayments Copied to clipboard Integer CONDITIONAL

The number of merchant-initiated payments within the recurring payment agreement.

JSON number data type, restricted to being positive or zero. In addition, the represented number may have no fractional part.

Min value: 1 Max value: 999
agreement.paymentFrequency Copied to clipboard Enumeration CONDITIONAL

The frequency of the payments within the series as agreed with the payer under your agreement with them.

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

AD_HOC

The agreement if for payments on an ah-hoc basis.

DAILY

The agreement if for a daily payment.

FORTNIGHTLY

The agreement if for a fortnightly payment.

MONTHLY

The agreement if for a monthly payment.

OTHER

The agreement is for payments according to a schedule other than the ones listed in the other enumeration values for this field.

QUARTERLY

The agreement if for a quarterly payment.

TWICE_YEARLY

The agreement if for a payment twice a year.

WEEKLY

The agreement if for a weekly payment.

YEARLY

The agreement if for a yearly payment.

agreement.type Copied to clipboard Enumeration CONDITIONAL

The type of commercial agreement that the payer has with you.

Specify the agreement type when you have provided a value for agreement.id and this payment is the first in a series of payments. The default value is OTHER.

The gateway will use the value you specify for subsequent payments in the series.

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

INSTALLMENT

An agreement where the payer authorizes the payment for a single purchase to be split into a number of payments processed at agreed intervals. For example, pay for a purchase in six monthly installments.

OTHER

An agreement where the merchant wants to link related payments for any purpose other than processing recurring, installment, or unscheduled payments. For example, split tender payments.

RECURRING

An agreement where the payer authorizes the merchant to process payments for recurring bills or invoices at agreed intervals (for example, weekly, monthly). The amount might be fixed or variable.

UNSCHEDULED

An agreement where the payer authorizes the merchant to automatically deduct funds for a payment for an agreed purchase when required (unscheduled). For example, auto top-ups when the account value falls below a threshold.

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.

JSON boolean values 'true' or 'false'.

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.

JSON boolean values 'true' or 'false'.

airline.ticket.eTicket Copied to clipboard Boolean CONDITIONAL

Indicates if an electronic ticket was issued.

JSON boolean values 'true' or 'false'.

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.

JSON boolean values 'true' or 'false'.

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.3ds Copied to clipboard CONDITIONAL

Information about payer authentication using 3-D Secure authentication.

Parameters in this group apply to both 3-D Secure authentication version 1 and 3-D Secure Authentication version 2.

Depending on the 3-D Secure authentication version applicable you will also need additional parameters:

  • 3-D Secure authentication version 1: see the authentication.3ds1 parameter group.
  • 3-D Secure authentication version 2: see the authentication.3ds2 parameter group.

authentication.3ds.acsEci Copied to clipboard Alphanumeric CONDITIONAL

Indicates the security level of the transaction.

This is the Electronic Commerce Indicator (ECI) value provided by the issuer's Access Control Server (ACS) to indicate the results of the attempt to authenticate the payer.

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

Min length: 1 Max length: 2
authentication.3ds.authenticationToken Copied to clipboard Base64 CONDITIONAL

The base64 encoded value generated by the issuer.

The authentication token Included in subsequent transaction request messages and used by the card scheme to verify that the authentication occurred and the values provided are valid. The token should be used unaltered. For 3DS version 1, 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.

For 3DS version 2, this field corresponds to the Authentication Value.

Data is Base64 encoded

allowable lengths 28 or 32
authentication.3ds.transactionId Copied to clipboard String CONDITIONAL

A unique identifier for the 3-D Secure authentication transaction.

For 3DS version 1, this field corresponds to the XID. The XID is an identifier generated by the gateway on behalf of the merchant.

For 3DS version 2, this field corresponds to the identifier assigned by the scheme directory server.


This identifier should be used in subsequent operation requests unaltered.

An XID submitted in this field must be in base64 format.

Data can consist of any characters

Min length: 1 Max length: 50
authentication.3ds1 Copied to clipboard CONDITIONAL

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

authentication.3ds1.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
authentication.3ds1.veResEnrolled Copied to clipboard Alpha ALWAYS PROVIDED

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

This is for experts only - most users should use the response.gatewayRecommendation field.

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
authentication.3ds2 Copied to clipboard CONDITIONAL

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

authentication.3ds2.3dsServerTransactionId Copied to clipboard String CONDITIONAL

You can ignore this field unless you want to build your own mobile SDK for EMV 3DS using the gateway's API.

The field contains the unique identifier assigned by the 3DS Server for this authentication. This is referred to in the EMVCo specification for 3-D Secure as threeDSServerTransID.

Data can consist of any characters

Min length: 1 Max length: 50
authentication.3ds2.acsTransactionId Copied to clipboard String CONDITIONAL

A unique transaction identifier assigned by the Access Control Server to identify the 3DS transaction.

The ACS transaction id should be used in subsequent operation requests unaltered.

Data can consist of any characters

Min length: 36 Max length: 36
authentication.3ds2.custom Copied to clipboard JSON Text CONDITIONAL

Additional information returned by the scheme or issuer in the authentication response that must be included (together with the standard authentication details) when submitting the transaction for processing by the acquirer.

Data is valid Json Format

Min length: 1 Max length: 4000
authentication.3ds2.directoryServerId Copied to clipboard String CONDITIONAL

Unique identifier for the Directory Server (also called Registered Application Provider Identifier or RID).

This value is applicable when you authenticate the payer in-app using 3-D Secure authentication version 2.

In this case, provide this value in the directoryServerId field on the createTransaction method request message sent from the app on the payer's device to the 3-D Secure Software Development Kit (SDK).

Data can consist of any characters

Min length: 10 Max length: 10
authentication.3ds2.dsTransactionId Copied to clipboard String CONDITIONAL

A unique transaction identifier assigned by the scheme Directory Server to identify the 3DS transaction.

The DS transaction id should be used in subsequent operation requests unaltered.

Data can consist of any characters

Min length: 1 Max length: 50
authentication.3ds2.methodCompleted Copied to clipboard Boolean ALWAYS PROVIDED

Indicates if the issuer's Access Control Server (ACS) completed the method call to obtain additional information about the payer's browser.

JSON boolean values 'true' or 'false'.

authentication.3ds2.methodSupported Copied to clipboard Enumeration ALWAYS PROVIDED

Indicates if the issuer's Access Control Server (ACS) support the method call.

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

NOT_SUPPORTED

The ACS does not support the method call protocol.

SUPPORTED

The ACS supports the method call protocol.

authentication.3ds2.protocolVersion Copied to clipboard Alphanumeric + additional characters CONDITIONAL

The version of the EMV 3-D Secure protocol used to perform 3-D Secure authentication, in the format specified by EMVCo.

For example, 2.1.0.

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

Min length: 1 Max length: 20
authentication.3ds2.requestorId Copied to clipboard String ALWAYS PROVIDED

The unique identifier assigned to the merchant by the card scheme directory server when the merchant registered to use 3-D Secure authentication version 2 with their acquirer.

Do not provide this value for Mastercard SecureCode or Verified by Visa, For these authentication schemes, it will be generated by the gateway.

Data can consist of any characters

Min length: 1 Max length: 35
authentication.3ds2.requestorName Copied to clipboard String ALWAYS PROVIDED

The unique name assigned to the merchant by the card scheme directory server when the merchant registered to use 3-D Secure authentication version 2 with their acquirer.

Do not provide this value for Mastercard SecureCode or Verified by Visa, For these authentication schemes, it will be generated by the gateway.

Data can consist of any characters

Min length: 1 Max length: 40
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.challengeCompletionCallbackUrl Copied to clipboard Url CONDITIONAL

This value is only returned when you authenticate the payer in-app using 3-D Secure authentication version 2 and a challenge is required (authentication.channel = PAYER_APP and authentication.3ds2.transactionStatus = C).

You must call this URL after the challenge has been completed; for example, when the ACS has confirmed the challenge completion.
This allows the gateway to retrieve the authentication result after the challenge has been completed.

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

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

JSON number data type, restricted to being positive or zero. In addition, the represented number may have no fractional part.

Min value: 300 Max value: 900
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.3ds2.statusReasonCode Copied to clipboard String CONDITIONAL

A code indicating the reason for the transaction status returned in authentication.3ds2.transactionStatus.

Refer to the EMVCo specification for 3-D Secure.

Data can consist of any characters

Min length: 2 Max length: 2
authentication.3ds2.transactionStatus Copied to clipboard Alpha CONDITIONAL

Indicates the result of payer authentication with the issuer.

This is the value returned in the transaction status field from the issuer's Access Control Server (ACS). For example, Y, N, U, A, R

Refer to the EMVCo specification for 3-D Secure.

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

Min length: 1 Max length: 1
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.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.method Copied to clipboard Enumeration CONDITIONAL

The method that the issuer will use to authenticate the payer.

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

DYNAMIC

The payer is authenticated using dynamic data. For example, a code sent to the payer's phone.

OUT_OF_BAND

The payer is authenticated by the issuer using another method. For example, by using a bank app on the payer's mobile device.

STATIC

The payer is authenticated using static data. For example, by providing responses to security questions for the payer's account.

authentication.payerInteraction Copied to clipboard Enumeration CONDITIONAL

Indicates if payer interaction was used to complete the authentication process.

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

NOT_POSSIBLE

Payer interaction was either not possible or not applicable to completing the authentication process. For example, there was a technical problem, or the authentication method is not supported for this payment method.

NOT_REQUIRED

No payer interaction was required to complete the authentication process. The issuer was able to make a decision based on the data provided.

REQUIRED

Payer interaction was required to complete the authentication process. For example, the payer was presented with a challenge to verify their identity.

authentication.psd2 Copied to clipboard CONDITIONAL

This parameter group is only applicable if you are subject to the Regulatory Technical Standards (RTS) requirements for Strong Customer Authentication (SCA) under the Payment Services Directive 2 (PSD2) regulations in the European Economic Area.

It provides details about SCA exemptions under PSD2.

authentication.psd2.exemption Copied to clipboard Enumeration CONDITIONAL

Indicates why this payment qualifies for exemption from Strong Customer Authentication (SCA) under the Payment Services Directive 2 (PSD2).

Note:

  • For recurring payments provide the RECURRING_PAYMENT value only if the amount is the same. If the amount varies, provide MERCHANT_INITIATED_TRANSACTION instead.

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

AUTO

If either a LOW_RISK or LOW_VALUE_PAYMENT exemption applies to the transaction, it is automatically claimed by the gateway on behalf of the merchant.

LOW_RISK

Exemption is claimed because the acquirer has a low fraud rate.

LOW_VALUE_PAYMENT

Exemption is claimed as the amount is below 30 Euro.

MERCHANT_INITIATED_TRANSACTION

The transaction is excluded as it was initiated by the merchant based on an agreement with the payer. For example, a recurring payment (for a varied or fixed amount), installment payment, or account top-up. In these cases, the payer is not present and cannot participate in an authentication interaction. Merchant initiated transactions are only applicable to subsequent transactions on the order and are out of scope of the PSD2 RTS on Strong Customer Authentication (SCA). The payer must be authenticated during the first transaction that established the agreement.

NONE

An exemption is not claimed for this transaction. The merchant requires Strong Customer Authentication (SCA) be performed.

RECURRING_PAYMENT

The transaction is exempt as it was initiated by the merchant based on an agreement with the payer for a recurring payment for a fixed amount. This value is only applicable to subsequent transactions on the order. In this case, the payer is not present and cannot participate in an authentication interaction. The payer must be authenticated during the first transaction that established the agreement.

SECURE_CORPORATE_PAYMENT

The transaction is exempt as it is a corporate or Business-to-Business (B2B) payment performed using dedicated payment processes and protocols that are not available to consumers and offer at least equivalent security levels.

WHITELISTED_MERCHANT

The transaction is exempt because the payer has added you to the list of their trusted merchants (as maintained by the issuer).

authentication.psd2.whitelistStatus Copied to clipboard Enumeration CONDITIONAL

Indicates if the payer has whitelisted you with the issuer and has opted-out of Strong Customer Authentication (SCA).

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

NOT_WHITELISTED

The payer has not whitelisted the merchant with the issuer or the merchant's whitelist status is unknown.

WHITELISTED

The payer has whitelisted the merchant with the issuer.

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.
  • • If you set this to REFRESH_AUTHENTICATION then when you perform the subsequent Authenticate Payer operation you must provide details of the original authentication, either by providing the authentication data explicitly via the fields customer.account.history.issuerAuthentication.acsTransactionId, customer.account.history.issuerAuthentication.authenticationToken, customer.account.history.issuerAuthentication.time and customer.account.history.issuerAuthentication.type, or by providing the gateway reference of the original authentication operation in customer.account.history.issuerAuthentication.transactionId.

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.

REFRESH_AUTHENTICATION

Authentication performed in order to obtain a new authentication token to replace one previously obtained for the order which is no longer valid (for example, because the order amount has changed in the time between originally performing authentication and submitting the financial transaction).

authentication.redirect.domainName Copied to clipboard String CONDITIONAL

The domain name of the site where payer authentication was performed.

For example, the domain-name of the issuer's Access Control Server (ACS) used for payer authentication using 3-D Secure authentication.

Data can consist of any characters

Min length: 1 Max length: 253
authentication.transactionId Copied to clipboard String CONDITIONAL

The transactionId you used for the Initiate Authentication operation.

Data can consist of any characters

Min length: 1 Max length: 40
authentication.version Copied to clipboard Enumeration CONDITIONAL

If online authentication of the payer is available, then this field shows the type.

If no such authentication is available, the value is NONE.

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

3DS1

3-D Secure Version 1 authentication is available.

3DS2

3-D Secure Version 2 authentication is available.

RUPAY

RuPay authentication is available.

NONE

No authentication is available.

authorizationResponse Copied to clipboard CONDITIONAL

Information about the Authorization received from the acquirer or issuer.

You can use this data if you want to understand the authorization in more detail, or with less interpretation by the gateway.

This data must be provided to the acquirer in the Capture request for this Authorization.

  • For a subsequent Capture the gateway takes care of this for you.
  • For a Standalone Capture request you need to provide this data.
  • When performing the Capture outside the the gateway you must ensure that the data is provided in the Capture request to the acquirer.

authorizationResponse.autoExpiry Copied to clipboard DateTime CONDITIONAL

The date and time when the gateway considers the authorization obtained for the order to have expired.

After this time, the gateway will reject your attempts to capture funds against this order. It will also void any authorized amount that has not been captured, to release the payer's funds.

This capability is to assist you in scheme compliance, and must be enabled by your payment provider. The gateway only populates this field if it is expiring the authorization.

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

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.date Copied to clipboard String CONDITIONAL

The local date, in MMDD format, on which the transaction occurred.

Data can consist of any characters

Min length: 1 Max length: 4
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 scheme.

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.merchantAdviceCode Copied to clipboard String CONDITIONAL

This field contains data returned by the issuer or card network to clearly communicate to merchants the reason for declining a MasterCard or Visa transaction.

Merchants can use this information to determine the best action to take. Please refer to Troubleshooting & FAQs - What if my transaction gets declined? for the list of values and their meaning.

Data can consist of any characters

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

Payment Service Data required in settlement request.

Data can consist of any characters

Min length: 1 Max length: 23
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.posEntryModeChanged Copied to clipboard String CONDITIONAL

If the entry mode has changed, the Issuer will respond with the 1-byte POS Entry Mode Change (Y).

Data can consist of any characters

Min length: 1 Max length: 1
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.responseMessage Copied to clipboard String CONDITIONAL

Textual description of the acquirer response code for displaying on terminals.

Data can consist of any characters

Min length: 1 Max length: 16
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.stan Copied to clipboard String CONDITIONAL

The System Trace Audit Number is assigned by a transaction originator to assist in identifying a Card Transaction.

The trace number remains unchanged for the life of the Card Transaction.

Data can consist of any characters

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

The local time, in HHMMSS format, during which the transaction occurred.

Data can consist of any characters

Min length: 1 Max length: 6
authorizationResponse.timezone Copied to clipboard Time Offset CONDITIONAL

The local time zone, in +hhmm or -hhmm format, in which the authorization was received from the acquirer, issuer or local terminal.

Data must comply with ISO 8601 UTC time offset format, +hhmm or -hhmm.

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: 30
authorizationResponse.transactionIntegrityClass Copied to clipboard Alphanumeric CONDITIONAL

The Transaction Integrity Class (TIC) is an indicator defined by the scheme to evaluate the safety and security of the transaction.

The indicator is only supported by some schemes and for all regions.

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

Min length: 1 Max length: 2
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
authorizationResponse.vpasResponse Copied to clipboard String CONDITIONAL

The response returned by the issuer indicating whether the 3DSecure authentication token was validated or not.

Data can consist of any characters

Min length: 1 Max length: 1
availableBalance Copied to clipboard CONDITIONAL
availableBalance.ebt[n] Copied to clipboard CONDITIONAL

The amount and currency of available balance on the EBT card.

availableBalance.ebt[n].amount Copied to clipboard Decimal CONDITIONAL

The available amount for this type of account balance.

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

Min length: 1 Max length: 14
availableBalance.ebt[n].currency Copied to clipboard Upper case alphabetic text CONDITIONAL

The currency the available amount is provided in for this type of account balance.

Expressed as an ISO 4217 alpha code, e.g. USD.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
availableBalance.ebt[n].type Copied to clipboard Enumeration CONDITIONAL

Indicates the type of account balance.

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

CASH_BENEFITS_AVAILABLE_BALANCE

The current available balance of the cash benefits account associated with the EBT card. Typically, this amount is the balance less any outstanding authorizations.

CASH_BENEFITS_BEGINNING_BALANCE

The initial balance of the cash benefits account associated with the EBT card.

CASH_BENEFITS_ENDING_BALANCE

The ending balance of the cash benefits account associated with the EBT card.

EWIC_DISCOUNT

The monetary value of discounts received from use of coupons/discounts against WIC approved foods when making an eWIC transaction.

SNAP_AVAILABLE_BALANCE

The current available balance of the Supplemental Nutrition Assistance Program (SNAP) account associated with the EBT card. Typically, this amount is the balance less any outstanding authorizations.

SNAP_BEGINNING_BALANCE

The initial balance of the Supplemental Nutrition Assistance Program (SNAP) account associated with the EBT card.

SNAP_ENDING_BALANCE

The ledger balance of the Supplemental Nutrition Assistance Program (SNAP) account associated with the EBT card.

availableBalance.funds Copied to clipboard CONDITIONAL

The amount and currency of available balance on the card.

availableBalance.funds.amount Copied to clipboard Decimal CONDITIONAL

The available balance on the card.

If provided, this is the amount available to the payer to spend after this payment.

Data is a decimal number.

Max value: 1000000000000 Min value: 0 Max post-decimal digits: 3
availableBalance.funds.currency Copied to clipboard Upper case alphabetic text CONDITIONAL

The currency of available balance on the card expressed as an ISO 4217 alpha code, e.g. USD.

Data must consist of the characters A-Z

Min length: 3 Max length: 3
billing Copied to clipboard CONDITIONAL

Information on the billing address including the contact details of the payer.

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.interaction Copied to clipboard CONDITIONAL

Provides details about the interaction of your system and the providers system when initiating the browser payment, redirecting the customer's browser to the provider's system, back to the merchant's website and completing the browser payment.

browserPayment.interaction.status Copied to clipboard Enumeration ALWAYS PROVIDED

The status of the interaction between the merchant's system and the payment provider's system.

Defines the interaction state of the transaction.

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

COMPLETED

This browser payment has been completed, i.e. the gateway has been informed about the payment result.

INITIATED

This browser payment has successfully been initiated.

REDIRECTED_TO_PROVIDER

The payer's browser has been redirected to the payment provider's website.

RETURNED_TO_MERCHANT

The payer's browser has been redirected back from the payment provider's website to the merchant's website.

browserPayment.interaction.timeCompleted Copied to clipboard ASCII Text CONDITIONAL

The date and time the browser payment was completed, i.e. the gateway has been informed about the payment result.

Data consists of ASCII characters

Min length: 0 Max length: 29
browserPayment.interaction.timeInitiated Copied to clipboard ASCII Text CONDITIONAL

The date and time the browser payment was initiated.

Provided only, if initiating the browser payment was successful (response.gatewayCode=SUBMITTED).

Data consists of ASCII characters

Min length: 0 Max length: 29
browserPayment.interaction.timeRedirected Copied to clipboard ASCII Text CONDITIONAL

The date and time the customer's browser was received from the merchant's website and redirected to the provider's website.

Data consists of ASCII characters

Min length: 0 Max length: 29
browserPayment.interaction.timeReturned Copied to clipboard ASCII Text CONDITIONAL

The date and time the customer's browser was received from the provider's website and redirected back to the merchant's website.

Data consists of ASCII characters

Min length: 0 Max length: 29
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.

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.accountId Copied to clipboard String CONDITIONAL

The ID provided to you by PayPal when you create a PayPal account.

This identifies you as the merchant in messages that the gateway submits to PayPal.

Data can consist of any characters

Min length: 1 Max length: 50
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.

JSON boolean values 'true' or 'false'.

browserPayment.paypal.interactionId Copied to clipboard String CONDITIONAL

PayPal's unique identifier for the interaction between the payer and PayPal.

Data can consist of any characters

Min length: 1 Max length: 255
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.

JSON boolean values 'true' or 'false'.

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.

By default this is set to CONFIRM_AT_PROVIDER.

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.redirectUrl Copied to clipboard Url CONDITIONAL

The URL issued by the gateway to which you must redirect the payer's browser.

The redirect URL is not applicable for PayPal. For PayPal payments implement the createOrder callback in the JavaScript SDK instead.

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

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.

You must provide this field for all browser payments, apart from PayPal. For PayPal payments use the JavaScript SDK to present the PayPal payer interaction in a modal window on top of your payment page.

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.

JSON number data type, restricted to being positive or zero. In addition, the represented number may have no fractional part.

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

The allowable number of installments for the payment plan.

JSON number data type, restricted to being positive or zero. In addition, the represented number may have no fractional part.

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
cruise Copied to clipboard CONDITIONAL

Cruise industry data.

cruise.bookingReference Copied to clipboard String CONDITIONAL

The cruise booking reference.

Data can consist of any characters

Min length: 1 Max length: 12
cruise.company Copied to clipboard CONDITIONAL

Information about the cruise line.

cruise.company.contact Copied to clipboard CONDITIONAL

Contact details of the cruise line.

cruise.company.contact.companyPhone Copied to clipboard Telephone Number CONDITIONAL

The cruise line registered office telephone number in ITU-T E123 format.

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
cruise.company.contact.customerServicePhone Copied to clipboard Telephone Number CONDITIONAL

The customer service phone number in ITU-T E123 format.

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
cruise.departureDate Copied to clipboard Date CONDITIONAL

The cruise departure/ sail date.

This field is required when cruise industry data is provided.

The value entered must be equal to or earlier than cruise.returnDate.

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

cruise.departurePort Copied to clipboard CONDITIONAL

A departurePort is the port where the passenger(s) boarded the cruise ship when the cruise trip started

cruise.departurePort.address Copied to clipboard CONDITIONAL

Address of the cruise line.

cruise.departurePort.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
cruise.departurePort.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
cruise.departurePort.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
cruise.departurePort.address.stateProvinceCode Copied to clipboard String CONDITIONAL

The state or province code of the address.

The value must match the second part of the ISO 3166-2 code. For an address in the United States provide the 2-letter ISO 3166-2 state code. For US military bases provide one of AE, AA, AP. For an address in Canada provide the 2-letter ISO 3166-2 province code.

Data can consist of any characters

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

The first line of the address.

Data can consist of any characters

Min length: 1 Max length: 100
cruise.departurePort.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
cruise.passenger[n] Copied to clipboard CONDITIONAL

Cruise passenger details.

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

The first name of the passenger.

Data can consist of any characters

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

The folio number assigned to the passenger.

Data can consist of any characters

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

The last name of the passenger.

Data can consist of any characters

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

The middle name of the passenger.

Data can consist of any characters

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

The title of the passenger.

Data can consist of any characters

Min length: 1 Max length: 50
cruise.returnDate Copied to clipboard Date CONDITIONAL

The cruise return/ sail end date.

This field is required when cruise.departureDate is provided and the value must be equal to or later than cruise.departureDate.

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

cruise.shipName Copied to clipboard String CONDITIONAL

The name of the cruise ship.

Data can consist of any characters

Min length: 1 Max length: 50
cruise.travelAgentCode Copied to clipboard Alphanumeric CONDITIONAL

The industry code of the travel agent booking the cruise.

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

Min length: 8 Max length: 9
cruise.travelAgentName Copied to clipboard String CONDITIONAL

The name of the travel agent booking the cruise.

Data can consist of any characters

Min length: 1 Max length: 30
cruise.travelPackageItems Copied to clipboard Comma separated enumeration CONDITIONAL

A comma separated list of the travel items that are included as part of a cruise travel package.

If the value CRUISE_ONLY is provided then other items are not permitted in the list.

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

CAR_RENTAL

Car rental is included in the travel package.

CRUISE_ONLY

No additional items are included in the cruise travel package.

FLIGHT

Flights are included in the travel package.

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 decimal number.

Max value: 10000000 Min value: 0 Max post-decimal digits: 5
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 decimal number.

Max value: 1000000000000 Min value: 0 Max post-decimal digits: 3
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 decimal number.

Max value: 1000000000000000000 Min value: 0 Max post-decimal digits: 12
currencyConversion.payerReceiptText Copied to clipboard String CONDITIONAL

This is a piece of HTML markup that can be included as part of the receipt where the payer has accepted the currency conversion quote.

It contains information necessary to comply with scheme requirements.

Data can consist of any characters

Min length: 1 Max length: 4096
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.uptake Copied to clipboard Enumeration ALWAYS PROVIDED

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 about the customer, including their contact details.