Retrieve Order

Request to retrieve the details of an order and all transactions associated with this order.

GET https://eu-gateway.mastercard.com/api/rest/version/74 / merchant / {merchantId} / order / {orderid}

Authentication

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

URL Parameters

{merchantId} 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} 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

Fields

To view the optional fields, please toggle on the "Show optional fields" setting.

correlationId 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
responseControls OPTIONAL

Container for fields that control the response returned for the request.

responseControls.sensitiveData String OPTIONAL

Indicates how sensitive data is returned in the response.

Data can consist of any characters

Min length: 1 Max length: 50

Response

Fields

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

JSON boolean values 'true' or 'false'.

accountFunding CONDITIONAL

Additional details for account funding transactions (order.purchaseType=ACCOUNT_FUNDING).

Account funding transactions are transactions that pull money from the sender's card account for the purpose of funding another account, the recipient's account. Depending on the type of account funding transaction you may be required to provide some or all the details in this parameter group.

accountFunding.purpose Enumeration CONDITIONAL

Defines the purpose of the account funding payment.If not provided the value is defaulted to OTHER.

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

CRYPTOCURRENCY_PURCHASE

The funds from this account funding transaction will exclusively be used to purchase cryptocurrency.

MERCHANT_SETTLEMENT

The funds from this account funding transaction will be used to settle the proceeds of processing card transactions.

OTHER

The funds from this account funding transaction will be used for any other purpose, e.g. transferring funds from a person to a person or transferring funds into a staged wallet. This is the default value.

PAYROLL

The funds from this account funding transaction will be used to pay salaries.

accountFunding.recipient CONDITIONAL

Details about the recipient who will subsequently receive the funds that you are debiting from the sender in this transaction.

accountFunding.recipient.country Upper case alphabetic text CONDITIONAL

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

Data must consist of the characters A-Z

Min length: 3 Max length: 3
accountFunding.recipient.dateOfBirth Date CONDITIONAL

The date of birth of the recipient in yyyy-mm-dd format.

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

accountFunding.recipient.firstName String CONDITIONAL

First name of the recipient.

Data can consist of any characters

Min length: 1 Max length: 50
accountFunding.recipient.lastName String CONDITIONAL

Last name of the recipient.

Data can consist of any characters

Min length: 1 Max length: 50
accountFunding.recipient.middleName String CONDITIONAL

Middle name of the recipient.

Data can consist of any characters

Min length: 1 Max length: 50
accountFunding.recipient.postCodeZip String CONDITIONAL

The post code or zip code of the recipient.

Data can consist of any characters

Min length: 1 Max length: 10
accountFunding.recipient.stateProvinceCode String CONDITIONAL

The state or province code of the recipient.

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
accountFunding.reference String ALWAYS PROVIDED

An reference for this account funding transaction.

This reference is generated by the gateway. You may be required to provide this reference when subsequently crediting the funds to the recipient's account.

Data can consist of any characters

Min length: 1 Max length: 50
accountFunding.senderIsRecipient Boolean CONDITIONAL

Defines if the sender and recipient of the account funding payment are the same or not.

If not provided the value is defaulted to FALSE.

JSON boolean values 'true' or 'false'.

accountFunding.senderType Enumeration CONDITIONAL

Defines if the sender is a person, a commercial organization, a non-profit organization or a government

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

COMMERCIAL_ORGANIZATION

The sender is a commercial organization. Examples include account to account transfers initiated by a commercial organization for the purpose of transferring funds to one of their accounts, business to business payments, and disbursements for insurance claims, payroll, investment dividends, merchant rebates.

GOVERNMENT

The sender is a government or government agency. Examples include government agencies paying salaries, pensions, social benefits or tax credits.

NON_PROFIT_ORGANIZATION

The sender is a non-profit organization. Examples include non-profit organizations delivering emergency aid payments.

PERSON

The sender is a person. Examples include account to account transfers initiated by a person to their own account or a different person's account and adding funds to a staged wallet.

agreement CONDITIONAL

A commercial agreement you have with the payer that allows you to store and use their payment details for later payments.

For example, an agreement to a series of recurring payments (a mobile phone subscription), an agreement to take payment for a purchase by a series of installments (hire purchase), an agreement to make additional payments when required (account top up), or to fulfil a standard industry practice (no show penalty charge).

Do not provide this parameter group if you are storing the payment details for subsequent payer-initiated payments only.

See Credential on File, Cardholder, and Merchant Initiated Transactions for details.

agreement.amountVariability Enumeration CONDITIONAL

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

The field must be provided for recurring payment agreements.

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.customData String CONDITIONAL

Additional information requested for the agreement which cannot be passed using other available data fields.

This field must not contain sensitive data.

Data can consist of any characters, but sensitive data will be rejected

Min length: 1 Max length: 2048
agreement.expiryDate 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 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.
  • Industry Practice: you have an agreement with the payer that authorizes you to initiate additional transactions to fulfil a standard business practice related to an original payment initiated by the payer. For example, a delayed charge for use of the hotel mini bar after the payer has checked out or a no show penalty charge when the payer fails to show for a booking.
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 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.minimumAmountPerPayment Decimal CONDITIONAL

The minimum 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 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 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 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.retailer CONDITIONAL

For an installment agreement where the payer purchased goods and/or services from a retailer but entered an installment agreement to pay for this purchase with you, you must provide details about the retailer.

agreement.retailer.abbreviatedTradingName String CONDITIONAL

Provide an abbreviation of the retailer's trading name that can be used by the issuer to indicate the retailer on the payer's statement.

Data can consist of any characters

Min length: 1 Max length: 10
agreement.retailer.merchantCategoryCode String CONDITIONAL

A 4-digit code used to classify the retailer's business by the type of goods or services it offers.

Data can consist of any characters

Min length: 1 Max length: 4
agreement.retailer.tradingName String CONDITIONAL

The retailer's trading name.

Data can consist of any characters

Min length: 1 Max length: 100
agreement.startDate Date CONDITIONAL

This is the effective start date for the payment agreement.

Cannot be in the past.

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

agreement.type 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 you want 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 you to process repeat payments for bills or invoices at agreed intervals (for example, weekly, monthly). The amount might be fixed or variable.

UNSCHEDULED

An agreement where the payer authorizes you 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 CONDITIONAL

Airline industry specific data

airline.bookingReference 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 Enumeration CONDITIONAL

The type of charge associated with the order.

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 CONDITIONAL

Itinerary details

airline.itinerary.leg[n] CONDITIONAL

Travel leg details.

airline.itinerary.leg[n].carrierCode 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 Boolean CONDITIONAL

Indicates if a stopover is permitted for the trip leg.

JSON boolean values 'true' or 'false'.

airline.itinerary.leg[n].taxes 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 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 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 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] CONDITIONAL

Passenger details

airline.passenger[n].firstName 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 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 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 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 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 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 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 CONDITIONAL

Ticket details

airline.ticket.conjunctionTicketIndicator 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 Boolean CONDITIONAL

Indicates if an electronic ticket was issued.

JSON boolean values 'true' or 'false'.

airline.ticket.exchangedTicketNumber Alphanumeric CONDITIONAL

The original ticket number when this is an order 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 CONDITIONAL

Ticket issue information.

airline.ticket.issue.address 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 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 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 String CONDITIONAL

The city/town where the ticket was issued.

Data can consist of any characters

Min length: 1 Max length: 100
airline.ticket.issue.country 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 Date CONDITIONAL

The date the ticket was issued.

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

airline.ticket.issue.travelAgentCode 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 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 Boolean CONDITIONAL

Indicates if the issued ticket is refundable.

JSON boolean values 'true' or 'false'.

airline.ticket.taxOrFee[n] 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 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 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 Alphanumeric CONDITIONAL

The airline ticket number associated with the order.

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

Min length: 11 Max length: 16
airline.ticket.totalFare 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 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 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 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

amount Decimal ALWAYS PROVIDED

The total amount for the order.  This is the net amount plus any merchant charge amounts.If you provide any sub-total amounts, then the sum of these amounts (order.itemAmount, order.taxAmount, order.shippingAndHandlingAmount, order.cashbackAmount, order.gratuityAmount, order.merchantCharge.amount and order.dutyAmount), minus the order.discountAmount must equal the net amount.

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

Data is a decimal number.

Max value: 1000000000000 Min value: 0 Max post-decimal digits: 3
authentication 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 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 2: see the authentication.3ds2 parameter group.

authentication.3ds.acsEci Alphanumeric CONDITIONAL

Indicates the security level of the order.

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 Base64 CONDITIONAL

The base64 encoded value generated by the issuer.

The authentication token Included in subsequent order 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 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.

For Rupay, this field corresponds to the authentication identifier assigned by Rupay for Guest Checkout transaction used for unregistered user transaction only.

Data can consist of any characters

Min length: 1 Max length: 50
authentication.status CONDITIONAL

Additional information about payer authentication status returned by the issuer or scheme.

authentication.status.code String CONDITIONAL

Indicates the status of payer authentication with the issuer.

For authentication.version=RUPAY this is the value returned in the error or status code field from the NPCI BEPG system to indicate success or failure response from the issuer.

Data can consist of any characters

Min length: 1 Max length: 100
authentication.status.description String CONDITIONAL

For authentication.version=RUPAY this is the value returned in the error message field from the NPCI BEPG system to provide additional information, for example, if authentication failed due to invalid or expired OTP.

Data can consist of any characters

Min length: 1 Max length: 1024
authenticationStatus Enumeration CONDITIONAL

Indicates the result of payer authentication.

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

AUTHENTICATION_ATTEMPTED

Payer authentication was attempted and a proof of authentication attempt was obtained.

AUTHENTICATION_AVAILABLE

Payer authentication is available for the payment method provided.

AUTHENTICATION_EXEMPT

Exemption from the Regulatory Technical Standards (RTS) requirements for Strong Customer Authentication (SCA) under the Payment Services Directive 2 (PSD2) regulations in the European Economic Area has been claimed or granted.

AUTHENTICATION_FAILED

The payer was not authenticated. You should not proceed with this transaction.

AUTHENTICATION_NOT_IN_EFFECT

There is no authentication information associated with this transaction.

AUTHENTICATION_NOT_SUPPORTED

The requested authentication method is not supported for this payment method.

AUTHENTICATION_PENDING

Payer authentication is pending completion of a challenge process.

AUTHENTICATION_REJECTED

The issuer rejected the authentication request and requested that you do not attempt authorization of a payment.

AUTHENTICATION_REQUIRED

Payer authentication is required for this payment, but was not provided.

AUTHENTICATION_SUCCESSFUL

The payer was successfully authenticated.

AUTHENTICATION_UNAVAILABLE

The payer was not able to be authenticated due to a technical or other issue.

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

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.

billing CONDITIONAL

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

billing.address 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 String CONDITIONAL

The city portion of the address.

Data can consist of any characters

Min length: 1 Max length: 100
billing.address.company 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 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 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 String CONDITIONAL

The state or province of the address.

Data can consist of any characters

Min length: 1 Max length: 20
billing.address.stateProvinceCode 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 String CONDITIONAL

The first line of the address.

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

Note: The transaction response will contain a concatenation of street and street2 data. If the concatenated value is more than the maximum field length, street2 data will be truncated.

Data can consist of any characters

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

The second line of the address (if provided).

Note: This field will be empty in the transaction response, as street2 data will be concatenated into the street field.

Data can consist of any characters

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

JSON boolean values 'true' or 'false'.

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

Data is a decimal number.

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

chargeback CONDITIONAL

This value will be provided when a chargeback is successfully processed and funds have been transferred back to the payer.

chargeback.amount Decimal ALWAYS PROVIDED

The total amount that has been successfully debited from the merchant's account as a result of chargebacks against this order.

Data is a decimal number.

Max value: 1000000000000 Min value: 0 Max post-decimal digits: 3
chargeback.currency String ALWAYS PROVIDED

The currency of chargeback raised against this order that has been successfully debited from the merchant's account, expressed as an ISO 4217 alpha code, e.g. USD.

Data can consist of any characters

Min length: 3 Max length: 3
correlationId 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
creationTime DateTime ALWAYS PROVIDED

Indicates the date and time the gateway considers the order to have been created.

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

currency Upper case alphabetic text ALWAYS PROVIDED

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
currencyConversion 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 the initial transaction for an order is a payer authentication transaction with DCC information and the subsequent authorization or pay transaction contains different DCC information, that authorization or pay transaction will be rejected.

If DCC information is provided on subsequent capture or refund for an order, it will be ignored.

currencyConversion.exchangeRateTime 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 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 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 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 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 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 Enumeration CONDITIONAL

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

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

FEXCO
currencyConversion.providerReceipt 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 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.

custom String CONDITIONAL

A field you provide to capture additional information about this order that is only of interest to you.

The gateway does not send this information to the acquirer. A maximum of 50 such fields may be added to the order.

Data can consist of any characters

Min length: 1 Max length: 250
customer CONDITIONAL

Information about the customer (payer) who has placed the order with you.

customer.email 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 String CONDITIONAL

The payer's first name.

Data can consist of any characters

Min length: 1 Max length: 50
customer.lastName String CONDITIONAL

The payer's last or surname.

Data can consist of any characters

Min length: 1 Max length: 50
customer.mobilePhone String CONDITIONAL

The contact person's mobile phone or cell phone number.

Data can consist of any characters

Min length: 1 Max length: 20
customer.phone String CONDITIONAL

The phone number of the person to whom the order is being billed.

Data can consist of any characters

Min length: 1 Max length: 20
customer.taxRegistrationId String CONDITIONAL

The tax registration identifier of the customer.

Data can consist of any characters

Min length: 1 Max length: 30
customer.nationalId 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
customerNote String CONDITIONAL

A note from the payer about this order.

Data can consist of any characters

Min length: 1 Max length: 250
customerOrderDate Date CONDITIONAL

The date the payer placed the order.

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

customerReference 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
debtRepayment CONDITIONAL

Additional details for debt repayment transactions (order.purchaseType=DEBT_REPAYMENT).

If your Merchant Category Code is 6012 (Merchandise and Services—Customer Financial Institutions) or 6051 ( (Non-Financial Institutions – Foreign Currency, Non-Fiat Currency)) you may be required to provide some or all the details in this parameter group.

debtRepayment.recipient CONDITIONAL

Details about the recipient of the payment and the destination account for the payment.

debtRepayment.recipient.accountIdentifier String ALWAYS PROVIDED

The account identifier for the payment recipient's account.

For payments into a card account provide the card number. For payments into other accounts (for example a bank account) provide the account number. The value provided will be returned masked in the response.

Data can consist of any characters

Min length: 1 Max length: 50
debtRepayment.recipient.dateOfBirth Date ALWAYS PROVIDED

The date of birth of the primary payment recipient in yyyy-mm-dd format.

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

debtRepayment.recipient.lastName String ALWAYS PROVIDED

Last name of the primary payment recipient.

Data can consist of any characters

Min length: 1 Max length: 50
debtRepayment.recipient.postcodeZip String ALWAYS PROVIDED

Postcode of the primary payment recipient.

Data can consist of any characters

Min length: 1 Max length: 10
description String CONDITIONAL

Short textual description of the contents of the order.

Data can consist of any characters

Min length: 1 Max length: 127
device CONDITIONAL

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

device.ani 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 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 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: 2048
device.hostname 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 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 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
discount 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.

discount.amount Decimal CONDITIONAL

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

Data is a decimal number.

Max value: 1000000000000 Min value: 0 Max post-decimal digits: 3
discount.code 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
discount.description String CONDITIONAL

A description of your reason for the discount.

Data can consist of any characters

Min length: 1 Max length: 127
dutyAmount Decimal CONDITIONAL

The duty amount (also known as customs tax, tariff or dues) for the order.

Data is a decimal number.

Max value: 1000000000000 Min value: 0 Max post-decimal digits: 3
expectedNumberOfCaptures Integer CONDITIONAL

The field indicates the total number of Capture requests you intend to submit for an order.

For example, if you intend to deliver the goods in two shipments and will capture part of the total authorized amount when you make each shipment, set the value of this field to 2.
If the value equals or drops below the actual number of successful Captures, then the gateway will prevent further Captures and void the outstanding Authorization amount (depending on your merchant profile configuration). If you are unsure of the number of Captures, set the value to 99, and to one on your last Capture.
If you do not provided a value for this field, but had previously provided one, the previous value is applied. For example, if you provide a value 2 on the first Capture for the order and then submit a second Capture without a value, the gateway assumes that the value is still 2.

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
funding CONDITIONAL

Details of the amount settled to your account for this order.

funding.amount Decimal ALWAYS PROVIDED

The total amount of money funded to / from your bank account for this order, as reported to the gateway by your acquirer.

This includes sales (credits to your account) and refunds (debits).
See order.fundingStatus to determine the certainty of this value.

Data is a decimal number.

Max value: 1000000000000 Min value: -1000000000000 Max post-decimal digits: 3
funding.currency Upper case alphabetic text ALWAYS PROVIDED

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

Data must consist of the characters A-Z

Min length: 3 Max length: 3
fundingStatus Enumeration CONDITIONAL

The current status of funding for the money that you can reasonably expect for this order.

It reflects both money into and out of your bank account (that is, both sales and refunds).
When considering funding status, the gateway only examines transactions that can move funds. For example, it ignores Authorizations and declined Captures. This is because fundingStatus reflects the movement of the money for the commercial transaction, it does not reflect the movement of money for fees associated with the transaction.

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

FUNDED

All transactions that could transfer money to / from your account are clearing and will settle.

FUNDING_ASSURED

All transactions that could transfer money to / from your account, are guaranteed to settle, but have not yet done so. The exact amount of the funds to be transferred might not be known in this state.

FUNDING_FAILED

There are transactions on the order that could result in the transfer of money to / from your account, however the service provider has not yet received funds from the payer. In case of an order with a refund the service provider was not able to return funds to the payer. You might need to contact the payer to unblock this condition.

FUNDING_ON_HOLD

There are transactions on the order that could result in the transfer of money to or from your account, however the service provider is unable to complete the transfer of funds, because of some problem with your account. This might be a transient state.

IN_PROGRESS

There are transactions on the order that could result in the transfer of money to / from your account, but some have not yet have done so. This is usually a transient state.

NON_FUNDED

There are no transactions on the order that could result in transfer of money to / from your account.

NOT_SUPPORTED

All transactions on the order were settled to a payment provider from which the gateway does not receive funding information.

gratuityAmount Decimal CONDITIONAL

The amount the payer has chosen to provide as a gratuity or tip in addition to the amount they are paying for the goods or services they are purchasing from you.

Data is a decimal number.

Max value: 1000000000000 Min value: 0 Max post-decimal digits: 3
id String ALWAYS PROVIDED

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 created by your merchant profile.

Data can consist of any characters

Min length: 1 Max length: 40
industryPracticePaymentReason Enumeration CONDITIONAL