API Operation Retrieve Session

3DSecure = CONDITIONAL

Information on 3DSecure fields.

Fixed value

3DSecure.acsEci Digits = CONDITIONAL

Indicates the security level of the transaction.

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

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

2

3DSecure.authenticationRedirect = CONDITIONAL

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

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

1. Simple: submit the form generated by the gateway. In this case, only the htmlBodyContent parameter is required.
2. Customized: for those merchants who wish to customise the submission. In this case, the acsURL and paReq parameters will be required to formulate the submission.
Note: This field will only be returned in the event of a successful directory server lookup.

Fixed value

3DSecure.authenticationRedirect.pageGenerationMode Enumeration = CONDITIONAL

Indicates the option (Simple or Customized) used to generate the page that redirects the cardholder to the card Issuer's Access Control Server (ACS) for authentication.

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

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

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

CUSTOMIZED

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

SIMPLE

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

3DSecure.authenticationRedirect.responseUrl Url = CONDITIONAL

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data is Base64 encoded

JSON type

String

allowable lengths

28 or 32

3DSecure.goodsDescription String = CONDITIONAL

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

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

0

maximum length

30

3DSecure.paResStatus 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™.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

1

3DSecure.veResEnrolled Alpha = CONDITIONAL

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

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

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

1

3DSecure.xid Base64 = CONDITIONAL

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

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data is Base64 encoded

JSON type

String

allowable length

28

3DSecureId ASCII Text = CONDITIONAL

A unique identifier supplied by the merchant for the authentication.

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data consists of ASCII characters

JSON type

String

minimum length

1

maximum length

64

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

Fixed value

agreement.expiryDate Date = CONDITIONAL

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

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

agreement.id String = Always Provided

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.

Existence

Always Provided

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

100

agreement.recurring = CONDITIONAL

Information about agreements for recurring payments.

Fixed value

agreement.recurring.daysBetweenPayments Integer = CONDITIONAL

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

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

Number

minimum value

1

maximum value

999

airline = CONDITIONAL

Airline industry specific data.

Fixed value

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.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

6

maximum length

15

airline.documentType Enumeration = CONDITIONAL

The type of charge associated with the transaction.

Existence

CONDITIONAL

Fixed value

Validation Rules

Document Type Code

JSON type

String

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

JSON type

String

minimum length

1

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data must consist of the characters A-Z

JSON type

String

minimum length

3

maximum length

3

airline.itinerary.leg[n].departureDate Date = CONDITIONAL

Date of departure for the trip leg.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

airline.itinerary.leg[n].departureTax Decimal = CONDITIONAL

Tax payable on departure for the trip leg.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

14

airline.itinerary.leg[n].departureTime Time = CONDITIONAL

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

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

airline.itinerary.leg[n].destinationAirport Upper case alphabetic text = CONDITIONAL

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data must consist of the characters A-Z

JSON type

String

minimum length

3

maximum length

3

airline.itinerary.leg[n].destinationArrivalDate Date = CONDITIONAL

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Indicates if a stopover is permitted for the trip leg.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON boolean values 'true' or 'false'.

JSON type

Boolean

airline.itinerary.leg[n].taxes Decimal = CONDITIONAL

Total taxes payable for the trip leg.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

14

airline.itinerary.leg[n].travelClass Alphanumeric = CONDITIONAL

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

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

3

airline.itinerary.numberInParty Digits = CONDITIONAL

Number of passengers associated with this booking.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

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

Existence

CONDITIONAL

Ticket details

Fixed value

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.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON boolean values 'true' or 'false'.

JSON type

Boolean

airline.ticket.eTicket Boolean = CONDITIONAL

Indicates if an electronic ticket was issued.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON boolean values 'true' or 'false'.

JSON type

Boolean

airline.ticket.exchangedTicketNumber Alphanumeric = CONDITIONAL

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

Existence

CONDITIONAL

The date the ticket was issued.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

airline.ticket.issue.travelAgentCode Alphanumeric = CONDITIONAL

Industry code of the travel agent issuing the ticket.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

8

maximum length

9

airline.ticket.issue.travelAgentName Alphanumeric = CONDITIONAL

Name of the travel agent issuing the ticket.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

30

airline.ticket.restricted Boolean = CONDITIONAL

Indicates if the issued ticket is refundable.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON boolean values 'true' or 'false'.

JSON type

Boolean

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.

Fixed value

airline.ticket.taxOrFee[n].amount Decimal = CONDITIONAL

The tax, charge or fee amount payable.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

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

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

3

maximum length

3

airline.ticket.ticketNumber Alphanumeric = CONDITIONAL

The airline ticket number associated with the transaction.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

11

maximum length

16

airline.ticket.totalFare Decimal = CONDITIONAL

Total fare for all trip legs on the ticket.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

14

airline.ticket.totalFees Decimal = CONDITIONAL

Total fee for all trip legs on the ticket.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

14

airline.ticket.totalTaxes Decimal = CONDITIONAL

Total taxes for all trip legs on the ticket.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

14

airline.transactionType Enumeration = CONDITIONAL

The type of transaction performed against this airline booking.

Existence

CONDITIONAL

Fixed value

Validation Rules

Transaction Type

JSON type

String

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

Fixed value

authentication.3ds2 = CONDITIONAL

JSON type

String

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

TEXT

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

SINGLE_SELECT

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

MULTI_SELECT

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

OUT_OF_BAND

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

OTHER_HTML

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

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

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

3DS1

3-D Secure Version 1

3DS2

3-D Secure Version 2

authentication.challengePreference Enumeration = CONDITIONAL

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

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

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

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

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

CHALLENGE_MANDATED

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

CHALLENGE_PREFERRED

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

NO_CHALLENGE

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

NO_PREFERENCE

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

authentication.channel Enumeration = CONDITIONAL

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

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

MERCHANT_REQUESTED

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

PAYER_APP

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

PAYER_BROWSER

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

authentication.goodsDescription String = CONDITIONAL

Description of the goods being purchased.

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

0

maximum length

30

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

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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.

1

maximum length

1

authorizationResponse.cardSecurityCodePresenceIndicator Alphanumeric = CONDITIONAL

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

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

2

authorizationResponse.commercialCard String = CONDITIONAL

Indicates if the card used is a commercial card.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

3

authorizationResponse.commercialCardIndicator String = CONDITIONAL

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

1

authorizationResponse.financialNetworkCode String = CONDITIONAL

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

3

authorizationResponse.financialNetworkDate Date = CONDITIONAL

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

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

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

authorizationResponse.marketSpecificData String = CONDITIONAL

Indicates the market or the industry associated with the payment.

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

1

authorizationResponse.posData String = CONDITIONAL

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

13

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

4

authorizationResponse.processingCode String = CONDITIONAL

Identifies the type of Card Transaction sent to Card Acceptor.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

6

authorizationResponse.responseCode String = CONDITIONAL

The response code which indicates the status of the transaction.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

3

authorizationResponse.returnAci String = CONDITIONAL

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

1

authorizationResponse.trackQuality String = CONDITIONAL

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

2

authorizationResponse.transactionIdentifier String = CONDITIONAL

The unique identifier for the transaction returned by the issuer.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

15

authorizationResponse.validationCode String = CONDITIONAL

The validation code returned by the issuer.

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

4

billing = CONDITIONAL

Data can consist of any characters

JSON type

String

minimum length

1

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

100

billing.address.street2 String = CONDITIONAL

The second line of the address (if provided).

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

100

browserPayment = CONDITIONAL

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

Fixed value

browserPayment.operation Enumeration = CONDITIONAL

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

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

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

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

Fixed value

browserPayment.paypal.agreementConfirmation Enumeration = CONDITIONAL

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

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

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

AGREE

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

AGREE_AND_PAY

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

browserPayment.paypal.displayShippingAddress 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.

Existence

CONDITIONAL

Fixed value

Validation Rules

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.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

constraints = CONDITIONAL

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

40

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.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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 String = CONDITIONAL

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

100

currencyConversion.requestId String = CONDITIONAL

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

100

currencyConversion.uptake Enumeration = CONDITIONAL

Indicates how DCC applies to the order.

If not provided, this value defaults to NOT_REQUIRED.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

Information associated with the customer's account.

Fixed value

customer.account = CONDITIONAL

Information about the customer's account with you

Fixed value

customer.account.authentication = CONDITIONAL

Information about how you authenticated the payer.

Fixed value

customer.account.authentication.method Enumeration = CONDITIONAL

The method you used to authenticate the payer.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

CUSTOMER_ACCOUNT_LOGIN

The merchant authenticated the payer using a credential system (for example,password) that they manage.

FEDERATED_IDENTITY_LOGIN

The merchant authenticated the payer using a federated identity management service such as Google or Facebook

FIDO_AUTHENTICATION

The merchant authenticated the payer using hardware, mobile, or biometrics based authentication that is compliant with FIDO Alliance specifications.

ISSUER_ACCOUNT_LOGIN

The merchant authenticated the payer using a credential system for example, password) managed by the issuer.

NONE

The merchant did not authenticate the payer.

maximum value

999

customer.account.history.creationDate Date = CONDITIONAL

The date the payer created an account with you.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

customer.account.history.issuerAuthentication = CONDITIONAL

Information about the payer authentication performed for a previous transaction with you.

Fixed value

customer.account.history.issuerAuthentication.acsTransactionId String = CONDITIONAL

The unique transaction identifier used by the issuer's Access Control Server (ACS) to identify the transaction.

If you are processing a recurring payment, then provide the transaction acsTransactionId for the transaction where the payer was authenticated.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

36

customer.account.history.issuerAuthentication.time DateTime = CONDITIONAL

The date and time the payer was authenticated for the prior transaction.

If you are processing a recurring payment, then provide the time and date for the transaction where the payer was authenticated.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

customer.account.history.issuerAuthentication.type Enumeration = CONDITIONAL

The method used to authenticate the payer for a prior transaction with you.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

3DS_FRICTIONLESS

3DS authentication was performed without payer interaction.

3DS_CHALLENGE

3DS authentication was performed and the payer was challenged for additional information.

ADDRESS_VERIFICATION

The issuer verifed the billing address provided by the payer. 3DS authentication was not used.

OTHER

The issuer verifed the payer using another method.

customer.account.history.lastUpdated Date = CONDITIONAL

The date the payer's account with you was last updated.

For example, they changed address details or changed card details.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

customer.account.history.passwordLastChanged Date = CONDITIONAL

The date the payer last changed the password for their account with you.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

customer.account.history.recentActivity Integer = CONDITIONAL

The number of transactions (successful and abandoned) that have been requested in the last 24 hours for all payment methods stored against this customer account.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

Number

minimum value

0

maximum value

99

customer.account.history.shippingAddressDate Date = CONDITIONAL

The date you first shipped goods to the payer's shipping address provided in the shipping.address parameter group.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

customer.account.history.suspiciousActivity Boolean = CONDITIONAL

Have you experienced suspicious or fraudulent activity on the account in the past.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON boolean values 'true' or 'false'.

JSON type

Boolean

customer.account.id String = CONDITIONAL

Your identifier for the payer's account with you.

This should be an immutable identifier, rather than the customer's name, email or such data that could be changed by the customer.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

40

customer.dateOfBirth Date = CONDITIONAL

The payer's date of birth.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

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

The number consists of:

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

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

mandatory country code

true

maximum total digits

15

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

30

customer.phone Telephone Number = CONDITIONAL

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

The number consists of:

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

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

mandatory country code

true

maximum total digits

15

customer.taxRegistrationId String = CONDITIONAL

The tax registration identifier of the customer.

Existence

CONDITIONAL

Fixed value

Validation Rules

Browser time zone offset between -840 to +840.

JSON type

String

device.fingerprint String = CONDITIONAL

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

For example, session ID, blackbox ID.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

4000

device.hostname String = CONDITIONAL

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

60

device.ipAddress String = CONDITIONAL

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

7

maximum length

15

device.mobilePhoneModel String = CONDITIONAL

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

255

gatewayEntryPoint Enumeration = CONDITIONAL

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

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

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

AUTO

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

BATCH

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

CHECKOUT

The transaction was created via checkout integration.

MERCHANT_ADMINISTRATION

The transaction was initiated in the Merchant Administration.

SERVICE_PROVIDER_API

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

WEB_SERVICES_API

The transaction was submitted via Web Services API.

lineOfBusiness String = CONDITIONAL

Your payment service provider might have configured your merchant profile to support several lines of business.

Each line of business can have different payment parameters, such as bank account, supported cards or such.

For example, lineOfBusiness = TICKET_SALES can have a different bank account from lineOfBusiness = MERCHANDISING. One line of business on your profile might be "null". To use that, do not provide the lineOfBusiness field.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters except space

JSON type

String

minimum length

1

maximum length

100

locale String = CONDITIONAL

A language identifier or IETF language tag to control the language of the payment interaction with the payer (e.g. en_US, es, fr-CA).

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

See Dynamic Currency Conversion for more detail.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data must be a language identifier or IETF language tag

JSON type

String

minimum length

2

maximum length

5

merchant Alphanumeric + additional characters = Always Provided

The unique identifier issued to you by your payment provider.

Existence

Always Provided

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

40

order = CONDITIONAL

Information about the order associated with this transaction.

Fixed value

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

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON boolean values 'true' or 'false'.

JSON type

Boolean

order.amount Decimal = CONDITIONAL

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

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

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

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data must consist of the characters A-Z

JSON type

String

minimum length

3

maximum length

3

order.custom String = CONDITIONAL

Information about this order that is of interest to you.

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

250

order.customerNote String = CONDITIONAL

A note from the payer about this order.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

250

order.customerOrderDate Date = CONDITIONAL

The date the payer placed the order.

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

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data consists of ASCII characters

JSON type

String

minimum length

0

maximum length

25

order.description String = CONDITIONAL

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

Existence

CONDITIONAL

Fixed value

This field only applies if you intend to receive the payer's funds in several Capture operations.

It 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 amount authorized when you make each shipment, set the value of this field to 2.
If the value ever equals or drops below the actual number of successful captures, then the gateway will prevent further captures and will void any unused authorized funds. If you are unsure of the number of captures, just set the value to 99, and then set it to 1 on your last capture.
If it is not specified on Capture operations, the last specified value is retained (defaulting to 1).

Existence

CONDITIONAL

Fixed value

Validation Rules

Data is a number between 1 and 99 represented as a string.

JSON type

String

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

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

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

14

order.id String = CONDITIONAL

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.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

40

The URL to which the gateway will send Webhook notifications when an order is created or updated.

To receive notifications at this URL, you must enable Webhook notifications in Merchant Administration. Ensure the URL is HTTPS

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

order.owningEntity String = CONDITIONAL

Your identifier for the part of your organization that is responsible for the order.

You might provide this data when you want to track the accountability for the order. For example, store number, sales region, branch, or profit center

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

40

order.recurringPaymentAgreement Alphanumeric = CONDITIONAL

Your reference to the contract or agreement you have with the payer to process recurring payments.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

30

order.reference String = CONDITIONAL

The identifier of the order.

For example, a shopping cart number, an order number, or an invoice number.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

40

order.requestorName String = CONDITIONAL

The name of the person who requested the goods or services.

Existence

The total shipping and handling amount for the order.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

14

order.statementDescriptor = CONDITIONAL

JSON type

String

minimum length

1

maximum length

100

order.statementDescriptor.address.street2 String = CONDITIONAL

The second line of the address (if provided).

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

100

order.statementDescriptor.name String = CONDITIONAL

Descriptor name of the merchant.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

100

order.statementDescriptor.phone String = CONDITIONAL

Descriptor phone number of the merchant's business.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

20

order.subMerchant = CONDITIONAL

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

100

order.subMerchant.address.street2 String = CONDITIONAL

The second line of the address (if provided).

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

100

order.subMerchant.authentication[n] = CONDITIONAL

String

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

AMEX_SAFEKEY

DINERS_PROTECTBUY

JCB_JSECURE

VERIFIED_BY_VISA

order.subMerchant.bankIndustryCode Digits = CONDITIONAL

Code used by acquirer to describe the business or industry the sub-merchant operates in.

You must provide a value if you want the gateway to perform 3-D Secure Version 2 authentication of the payer.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

4

maximum length

4

order.subMerchant.email Email = CONDITIONAL

The sub-merchant's email address.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

order.subMerchant.identifier String = CONDITIONAL

Your identifier for the sub-merchant.

You can use this identifier in searches and reports in the gateway.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

100

order.subMerchant.phone String = CONDITIONAL

The sub-merchant's phone number

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

20

order.subMerchant.registeredName String = CONDITIONAL

The legal name of the sub-merchant.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

100

order.subMerchant.tradingName String = CONDITIONAL

The trading name of the sub-merchant, also known as doing business as (DBA), operating as or trading as.

For MasterCard transactions the name must not exceed 21 characters. For American Express transactions the name must not exceed 27 characters (or 36 characters including the aggregator name). The trading name may be displayed on the payer's cardholder statement. Therefore if you need to shorten it, use an abbreviation that will be meaningful to the payer when displayed on their statement.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

100

order.subMerchant.websiteUrl Url = CONDITIONAL

The URL of the sub-merchant's website.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

order.supply = CONDITIONAL

Information about orders for items not yet available (pre-order) or for items previously purchased (reorder).

Fixed value

order.supply.preorder Boolean = CONDITIONAL

Indicates that the purchase includes merchandise with a future availability or release date.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON boolean values 'true' or 'false'.

JSON type

Boolean

order.supply.preorderAvailabilityDate Date = CONDITIONAL

The date that preordered items are expected to be available.

Provide this field if the payer is ordering items before you have them available for purchase.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

order.supply.reorder Boolean = CONDITIONAL

Indicates that the purchase includes merchandise that the payer has previously ordered.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON boolean values 'true' or 'false'.

JSON type

Boolean

order.surchargeAmount Decimal = CONDITIONAL

A fee charged by you to cover the cost of accepting a payment method.

This is an additional amount charged by you for accepting one payment method (e.g. a credit card) instead of another (e.g. cash).
If you provide a surcharge amount, you should include it in the total amount for the order.

Existence

CONDITIONAL

The type of tax included in the order amount.

The correct value as used by your acquirer may have to be provided. Contact your payment service provider for details.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

50

order.taxAmount Decimal = CONDITIONAL

The total amount of tax included in this order.

This value will be used for all pay orders and full capture transactions unless you provide us with a different amount in the transaction.taxAmount.
This amount is the sum of the tax amount for all the items contained in the order. If you supply both this value and any line item details, then this amount MUST equal the sum of the item.quantity times the item.unitTaxAmount for all the line items.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

14

order.taxRegistrationId String = CONDITIONAL

Your tax registration identifier provided by the Federal/National tax authority (for example, federal tax identification number, ABN).

If you are a Canadian merchant, use this field to provide your Tax Registration ID for paying Harmonized Sales Tax (HST) or Goods and Services Tax (GST) collected by the Canada Revenue Agency.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

30

order.taxStatus Enumeration = CONDITIONAL

Indicates your tax status for this order.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

EXEMPT

Indicates that you are exempt from tax.

NOT_EXEMPT

Indicates that you are not exempt from tax.

NOT_PROVIDED

Indicates that you are not providing information about being exempt from tax.

order.valueTransfer = CONDITIONAL

Information about payments that transfer money to another store of value, such as a gift card or gaming chips.

Fixed value

order.valueTransfer.accountType Enumeration = CONDITIONAL

The type of value store to which money is being transferred.

The default value is NOT_A_TRANSFER.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

ACCOUNT_FUNDING

Payment to add funds to the payer's account with the merchant. These funds can be used for future purchases.

NOT_A_TRANSFER

This payment is not for the purpose of transferring money to another store of value. It is a payment for goods or services.

PREPAID_LOAD

Payment to add funds to a prepaid card or gift card.

QUASI_CASH_TRANSACTION

Payment for items that are directly convertible to cash. For example, money orders, casino gaming chips, or traveller's checks.

order.valueTransfer.amount Decimal = CONDITIONAL

The amount of money being transferred, in units of order.valueTransfer.currency.

The default value is order.amount

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

14

order.valueTransfer.currency Upper case alphabetic text = CONDITIONAL

The currency of the store.

If the money is being transferred to multiple currencies, then use the currency of the highest transferred value.

The default value is order.currency.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data must consist of the characters A-Z

JSON type

String

minimum length

3

maximum length

3

order.valueTransfer.numberOfCards Integer = CONDITIONAL

The number of prepaid or gift card being purchased.

The default value is one when you set order.valueTransfer.accountType = PREPAID_LOAD. For all other values of order.valueTransfer.accountType the default is zero.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

Number

minimum value

0

maximum value

999

order.walletIndicator String = CONDITIONAL

The wallet indicator as returned by the wallet provider.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

3

maximum length

3

order.walletProvider Enumeration = CONDITIONAL

The wallet provider used to collect the customer's payment details used for this transaction.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

AMEX_EXPRESS_CHECKOUT

Amex Express Checkout wallet provider.

APPLE_PAY

Apple Pay mobile wallet provider.

CHASE_PAY

Chase Pay wallet provider.

GOOGLE_PAY

Google Pay mobile wallet provider.

MASTERPASS_ONLINE

MasterPass Online wallet provider.

SAMSUNG_PAY

Samsung Pay mobile wallet provider.

VISA_CHECKOUT

Visa Checkout wallet provider.

partnerSolutionId String = CONDITIONAL

If, when integrating with the gateway, you are using a solution (e.g. a shopping cart or e-commerce solution) provided, supported or certified by your payment service provider, enter the solution ID issued by your payment service provider here.

If your payment service provider has not provided you with a solution ID, you should ignore this field.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

The identifier for the payment plan.

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

40

paymentType Enumeration = CONDITIONAL

The payment method the payer wishes to use to pay for this order.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

ACH

ALIPAY

BANCANET

BOLETO_BANCARIO

CARD

ENETS

GIFT_CARD

GIROPAY

IDEAL

OXXO

PAYPAL

POLI

SEPA

SOFORT

UNION_PAY

WECHAT_PAY

responseControls = CONDITIONAL

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

Fixed value

responseControls.sensitiveData String = CONDITIONAL

Indicates how sensitive data is returned in the response.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

50

risk = CONDITIONAL

Session Information

Fixed value

session.id ASCII Text = Always Provided

The identifier of the session

Existence

Always Provided

Fixed value

Validation Rules

Data consists of ASCII characters

JSON type

String

minimum length

31

maximum length

35

session.updateStatus Enumeration = Always Provided

A summary of the outcome of the last attempt to modify the session.

In order to perform an operation using this session this value must be SUCCESS.

Existence

Always Provided

Fixed value

Validation Rules

JSON type

String

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

FAILURE

The last attempt to place data into the session was unsuccessful. The session may contain invalid data. A request operation using this session will be rejected by the payment gateway.

NO_UPDATE

No attempt has been made to place data into the session. A request operation using this session will be rejected by the payment gateway.

SUCCESS

The last attempt to update the session was successful. You may submit a request operation using this session.

session.version ASCII Text = Always Provided

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.

See Making Business Decisions Based on Session Content.

Existence

Always Provided

Fixed value

Validation Rules

Data consists of ASCII characters

JSON type

String

minimum length

10

maximum length

10

shipping = CONDITIONAL

String

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

DIFFERENT

The shipping and billing addresses are different.

SAME

The shipping and billing addresses are the same.

UNKNOWN

It is not known if the shipping and billing addresses are the same.

shipping.address.source Enumeration = CONDITIONAL

How you obtained the shipping address.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

ADDRESS_ON_FILE

Order shipped to an address that you have on file.

NEW_ADDRESS

Order shipped to an address provided by the payer for this transaction.

The second line of the address (if provided).

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

50

shipping.contact.mobilePhone Telephone Number = CONDITIONAL

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

The number consists of:

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

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

mandatory country code

true

maximum total digits

15

shipping.contact.phone Telephone Number = CONDITIONAL

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

The number consists of:

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

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

mandatory country code

true

maximum total digits

15

shipping.contact.sameAsBilling Enumeration = CONDITIONAL

Indicates whether the supplied name for the recipient of shipping matches the cardholder name.

Provide this value if you are not providing the full name or cardholder name, but you can affirm that they are the same or different.

Default value is UNKNOWN

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

DIFFERENT

The shipping and billing addresses are different.

SAME

The shipping and billing addresses are the same.

UNKNOWN

It is not known if the shipping and billing addresses are the same.

shipping.method Enumeration = CONDITIONAL

The shipping method used for delivery of this order.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

ELECTRONIC

Electronic delivery.

GROUND

Ground (4 or more days).

NOT_SHIPPED

Order for goods that are not shipped (for example, travel and event tickets)

OVERNIGHT

Overnight (next day).

PICKUP

Shipped to a local store for pick up.

PRIORITY

Priority (2-3 days).

SAME_DAY

Same day.

origin.postcodeZip Alphanumeric + additional characters = CONDITIONAL

The post code or zip code of the address the order is shipped from.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

10

sourceOfFunds = CONDITIONAL

The details describing the source of the funds to be used.

For card payments these may be represented by combining one or more of the following: explicitly provided card details, a session identifier which the gateway will use to look up the card details and/or a card token. Precedence rules will be applied in that explicitly provided card details will override session card details which will override card token details. Each of these may represent partial card details, however the combination must result in a full and complete set of card details. See Using Multiple Sources of Card Details for examples.

Fixed value

sourceOfFunds.provided = CONDITIONAL

Information about the source of funds when it is directly provided (as opposed to via a token or session).

For browser payments, the source of funds details are usually collected from the payer on the payment provider's website and provided to you when you retrieve the transaction details (for a successful transaction). However, for some payment types (such as giropay), you must collect the information from the payer and supply it here.

Fixed value

sourceOfFunds.provided.ach = CONDITIONAL

For ACH payments (sourceOfFunds.type=ACH) you must provide values for all fields within this parameter group, including details about the payers bank account as well as the type of ACH payment.

It is your responsibility to authenticate the payer and obtain authorization from the payer in accordance with the NACHA Operating Rules and Guidelines for the Standard Entry Class (SEC) associated with this payment. For details please refer to https://www.nacha.org/.

Fixed value

sourceOfFunds.provided.ach.accountType Enumeration = CONDITIONAL

An indicator identifying the type of bank account.

Consumer (checking or savings), or
Business

For pre-arranged payments (sourceOfFunds.provided.ach.secCode=PPD) retrieve this information from the payer.

If payments were telephone-initiated (sourceOfFunds.provided.ach.secCode=TEL) or internet-initiated (sourceOfFunds.provided.ach.secCode=WEB) you may choose to limit the payer's options (e.g. only support consumer checking accounts), depending on your type of business (e.g. B2C online webshop).

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

CONSUMER_CHECKING

Consumer Checking Account

CONSUMER_SAVINGS

Consumer Savings Account

CORPORATE_CHECKING

Business Checking Account

sourceOfFunds.provided.ach.bankAccountHolder String = CONDITIONAL

The name of the bank account holder, as it appears on the account at the receiving financial institution.

Retrieve this information from the payer.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

28

sourceOfFunds.provided.ach.bankAccountNumber Alphanumeric + additional characters = CONDITIONAL

The identifier of the bank account at the receiving financial institution.

Retrieve this information from the payer.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

17

sourceOfFunds.provided.ach.routingNumber Digits = CONDITIONAL

The identifier of the receiving financial institution.

Also known as:

Routing number,
Transit number, or
ABA number

Retrieve this information from the payer.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

9

maximum length

9

sourceOfFunds.provided.ach.secCode Enumeration = CONDITIONAL

Identifies the Standard Entry Class (SEC) code to be sent to the issuer.

The SEC is defined by NACHA and describes the origin and intent of the payment. For details please refer to https://www.nacha.org/.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

PPD

An ACH debit or credit payment (B2C) that has been authorized by an authenticated customer in written form (signed or similarly authenticated). PPD is used for pre-arranged payments (e.g. employee payroll, mortgage payments, expense reimbursement).

TEL

An ACH debit payment (B2C) that has been authorized by an authenticated customer via phone. TEL may only be used if a relationship already exists between you and the consumer, or, the consumer initiates the contact with you.

WEB

An ACH debit payment (B2C) that has been authorized by an authenticated customer via the internet or a wireless network.

sourceOfFunds.provided.alipay = CONDITIONAL

For Alipay payments (sourceOfFunds.type=ALIPAY) you must provide values for all fields within this parameter group.

Fixed value

sourceOfFunds.provided.alipay.payerCode String = CONDITIONAL

Payer code is a one-time code used by Alipay to identify the payer.

It is generated by the Alipay wallet app on the payer's mobile device.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

255

sourceOfFunds.provided.boletoBancario = CONDITIONAL

Additional details related to a Boleto Bancario browser payment.

When processing a Boleto Bancario payment you must also provide the payer's national identifier (customer.nationalId), your reference to the payer (customer.id) and the payer's date of birth (customer.dateOfBirth)

Fixed value

sourceOfFunds.provided.boletoBancario.bankAccountHolder String = CONDITIONAL

The name of the bank account holder for the payer's bank account.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

255

sourceOfFunds.provided.card = CONDITIONAL

Details as shown on the card.

Fixed value

sourceOfFunds.provided.card.accountType Enumeration = CONDITIONAL

You can provide this field for card types that have a savings/checking option, such as Maestro cards.

If you do not provide a value, we will use the acquirer's default. You can use paymentTypes.card.cardTypes in the 'Retrieve Payment Options' operation response to determine the card type.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

CHECKING

SAVINGS

sourceOfFunds.provided.card.devicePayment = CONDITIONAL

If the payer chose to pay using a device you must provide payment details in this parameter group.

Use this parameter group when accepting payments using device payment methods such as Apple Pay, Android Pay or Samsung Pay.

Fixed value

sourceOfFunds.provided.card.devicePayment.3DSecure = CONDITIONAL

Details used to process a digital payment where the payment data keys for the online payment cryptogram are provided using the 3-D Secure format.

Use this parameter group for:

• Device payments: if you decrypt the payment token yourself. In this case, you source these fields directly from the decrypted payment token.
You do not need to use this parameter group if you provide the payment token in sourceOfFunds.provided.card.devicePayment.paymentToken.
• Card scheme tokens: if you decrypt the transaction credentials yourself.

Fixed value

sourceOfFunds.provided.card.devicePayment.3DSecure.eciIndicator Digits = CONDITIONAL

The Electronic Commerce Indicator generated for payments made using a device payment method.

You source this field directly from the decrypted payment token.

This field is not applicable for payments using digital wallets or card scheme tokens.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

2

sourceOfFunds.provided.card.devicePayment.3DSecure.onlinePaymentCryptogram Base64 = CONDITIONAL

A cryptogram used to authenticate the transaction.Use this field for:

• Device payments: source this field directly from the decrypted payment token.
• Card scheme tokens: source this field directly from the decrypted transaction credentials.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data is Base64 encoded

JSON type

String

minimum length

1

maximum length

128

sourceOfFunds.provided.card.devicePayment.cryptogramFormat Enumeration = CONDITIONAL

The format of the cryptogram provided for the digital payment.Use this field for:

• Device payments: provide the cryptogram format when you decrypt the payment token and provide the payment details (including the online payment cryptogram) in the transaction request.

This field does not apply to Card Scheme token payments.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

3DSECURE

The payment data keys for the online payment cryptogram are provided using the 3-D Secure format.

EMV

The payment data keys for the online payment cryptogram are provided using the EMV format.

sourceOfFunds.provided.card.devicePayment.paymentToken String = CONDITIONAL

This is the payment token that you received from the device's payment SDK.

For example:

For Apple Pay - this is the PKPaymentToken.paymentData value.

For Google - this is PaymentMethodToken.getToken().

Note 1: The gateway API considers this value to be a string, NOT JSON itself. Therefore when using the JSON gateway API, this field will typically look like:

"sourceOfFunds": {
"provided": {
"card": {
"devicePayment": {
"paymentToken": "{\"data\":\"869ss19ew ....

Note 2: The gateway will ignore the currency and amount information in the payment token, and will instead use the values passed on the amount and currency fields. For normal usage, you should populate those fields with the exact same values as you got from the SDK.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

16384

sourceOfFunds.provided.card.emvRequest String = CONDITIONAL

This field only applies to transactions that originate from an EMV capable terminal.

It contains selected EMV fields as provided by the terminal.

For the list of field tags to include (if provided by the terminal), see Card Present Payments. Requests with any other tags are rejected by the gateway.

Some of the tags represent data that can occur on explicit fields in this API. You can submit the value either in this field, or in both places. For example, the PAN can be presented as EMV tag 5A in this field, or included both the sourceOfFunds.provided.card.number API field and in EMV tag 5A in this field.

If you specify the EMV tag only, we can populate the explicit field in the API. Fields where this is supported have the text "This field corresponds to EMV tag <tag name>" in their field descriptions.

If you specify both places, there will be no population of the explicit field or validation that the data matches.

The API response will not contain PCI sensitive fields.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

250

sourceOfFunds.provided.card.expiry = CONDITIONAL

Fixed value

sourceOfFunds.provided.card.maskedFpanExpiry.month Digits = CONDITIONAL

The expiration month for the Funding Primary Account Number (FPAN).

Months are numbered January=1, through to December=12.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data is a number between 1 and 12 represented as a string.

JSON type

String

sourceOfFunds.provided.card.maskedFpanExpiry.year Digits = CONDITIONAL

The expiration year for the Funding Primary Account Number (FPAN).

The Common Era year is 2000 plus this value.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

2

maximum length

2

sourceOfFunds.provided.card.mobileWallet = CONDITIONAL

String

minimum length

1

maximum length

256

sourceOfFunds.provided.card.number Digits = CONDITIONAL

Credit card number as printed on the card.

Existence

The DUKPT key serial number supplied by the terminal.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data is hexadecimal encoded

JSON type

String

minimum length

20

maximum length

20

sourceOfFunds.provided.card.provided.card.p2pe.payload Hex = CONDITIONAL

The DUKPT encrypted payload supplied by the terminal.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data is hexadecimal encoded

JSON type

String

minimum length

32

maximum length

1024

sourceOfFunds.provided.card.provided.card.prefix Digits = CONDITIONAL

The first 10 digits of the card number, as printed on the card.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

10

maximum length

10

sourceOfFunds.provided.card.securityCode Digits = CONDITIONAL

Card verification code, as printed on the back or front of the card or as provided for a card scheme token.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

3

maximum length

4

sourceOfFunds.provided.card.sequenceNumber Digits = CONDITIONAL

A number used to differentiate between cards with the same Primary Account Number (PAN).

This field corresponds to EMV tag 5F34

Existence

CONDITIONAL

Fixed value

Validation Rules

Data is a number between 0 and 999 represented as a string.

JSON type

String

sourceOfFunds.provided.card.storedOnFile Enumeration = CONDITIONAL

This field only applies if you collect cards from your payers, store them, and either you or your payers use the stored value for subsequent payments.

If you store using gateway tokenization then you can ignore this field, unless you do payments with both stored and non-stored cards. If you do both, then you must supply the NOT_STORED value for the non-stored case.

If you use Scheme Tokenization services like MDES and store the tokens provided, you have to provide the value STORED and if you pass the token value with out storing them, provide the value NOT_STORED.

If you store yourself, you have to provide the TO_BE_STORED or STORED values for all payments.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

NOT_STORED

Set this value if the card or token details provided will not be stored. This is the default value for merchants without tokenization.

STORED

Set this value if the card or token details provided have been stored previously. This is the default value when paying with a gateway token.

TO_BE_STORED

Set this value if this is the first transaction using the card and you intend to store the card or token details on success. This is the default value for tokenization merchants who present a payment with a PAN.

sourceOfFunds.provided.ebt = CONDITIONAL

If the payer chose to pay using a Electronic Benefits Transfer card, you must submit sourceOfFunds.type=EBT_CARD and provide the payer's card details in this parameter group.

Fixed value

sourceOfFunds.provided.ebt.accountType Enumeration = CONDITIONAL

Indicates the type of benefits account used for the payment.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

CASH_BENEFITS

Benefits provided as cash.

EWIC_BENEFITS

Benefits provided under the Special Supplemental Nutrition Program for Women, Infants, and Children.

SNAP_BENEFITS

Benefits provided under the Supplemental Nutrition Assistance Program.

sourceOfFunds.provided.ebt.manualAuthorizationCode Digits = CONDITIONAL

Value provided to you by the EBT merchant helpline when you requested manual authorization of the payment because you were unable to authorize the payment online.

For example, your point of sale (POS) machine is not working. When you manually authorize a payment you also need to provided the voucher number used to record the payment in sourceOfFunds.provided.EBT.voucherNumber.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

6

sourceOfFunds.provided.ebt.merchantFns Digits = CONDITIONAL

The identifier assigned to you by the USDA Food and Nutrition Service (FNS) when they authorized you to accept EBT payments at your store.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

7

sourceOfFunds.provided.ebt.voucherNumber Digits = CONDITIONAL

The number of the paper form (voucher) that you used to record details of an EBT payment when you were unable to authorize the payment online.

For example, your point of sale (POS) machine is not working. When you use a voucher you also need to provide an authorization code in sourceOfFunds.provided.benefits.ebt.manualAuthorizationCode.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

15

sourceOfFunds.provided.enets = CONDITIONAL

Additional details related to an eNETS browser payment.

Note: if you provide data for an eNETS payment, then you must also provide an email address for the customer in customer.email and a phone number for the customer in either customer.phone or customer.mobilePhone

Fixed value

sourceOfFunds.provided.enets.bankAccountHolder String = CONDITIONAL

The name of the bank account holder for the payer's bank account.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

255

sourceOfFunds.provided.giftCard = CONDITIONAL

If the payer chose to pay using a gift card, you must submit sourceOfFunds.type=GIFT_CARD and provide the payer's gift card details in this parameter group.

Fixed value

sourceOfFunds.provided.giftCard.expectedLocalBrand String = CONDITIONAL

Do not provide this field in your request unless instructed to do so by your payment service provider.

The field is required, if your gift card numbers do not use ISO BIN rules and therefore not allowing the gateway to identify the local brand.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

4

maximum length

50

sourceOfFunds.provided.giftCard.number Digits = CONDITIONAL

Card number as printed or embossed on the gift card.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

9

maximum length

19

sourceOfFunds.provided.giftCard.pin Digits = CONDITIONAL

PIN number for the gift card.

Existence

CONDITIONAL

Additional details related to an iDEAL browser payment.

When processing an iDEAL payment you can also provide the payer's bank identification code (ideal.bic),

Fixed value

sourceOfFunds.provided.ideal.bic Alphanumeric = CONDITIONAL

The international Business Identifier Code (BIC) for the payer's bank account.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

8

maximum length

11

sourceOfFunds.provided.oxxo = CONDITIONAL

Additional details related to an OXXO browser payment.

When processing an OXXO payment you must also provide the payer's national identifier (customer.nationalId), your reference to the payer (customer.id) and the payer's date of birth (customer.dateOfBirth).

Fixed value

sourceOfFunds.provided.oxxo.bankAccountHolder String = CONDITIONAL

The name of the bank account holder for the payer's bank account.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

255

sourceOfFunds.provided.paypal = CONDITIONAL

Information about the payer's PayPal account.

It is provided to you when the payer successfully makes a payment using PayPal or when you have established a billing agreement with the payer.

Fixed value

sourceOfFunds.provided.paypal.billingAgreement = CONDITIONAL

Details about the agreement you have established with the payer that allows you to bill the payer's PayPal account for goods or services.

Fixed value

sourceOfFunds.provided.paypal.billingAgreement.cardinality Enumeration = CONDITIONAL

Indicates the number of billing agreements between you and this payer.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

MULTIPLE

Indicates that you have multiple billing agreements with this payer. This means that a new agreement ID will be returned in response to each request.

SINGLE

Indicates that you have a single billing agreement with this payer. This means that the same agreement ID will be returned in response to each request.

sourceOfFunds.provided.paypal.billingAgreement.description String = CONDITIONAL

Your description for the PayPal billing agreement.

This description is displayed to the payer when they are asked to approve the billing agreement.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

255

sourceOfFunds.provided.paypal.billingAgreement.name String = CONDITIONAL

Your name for the PayPal billing agreement.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

255

sourceOfFunds.provided.poli = CONDITIONAL

Additional details related to a POLi browser payment.

Fixed value

sourceOfFunds.provided.poli.bankAccountHolder String = CONDITIONAL

The name of the bank account holder for the payer's bank account.

Existence

CONDITIONAL

The International Bank Account Number (IBAN) for the payer's bank account.

By default, the bank account number will be returned in a masked format, for example, xxxxxx0000. If you wish to return unmasked bank account numbers, you must have the requisite permission, set responseControls.sensitiveData, and authenticate your call to the API using certificate authentication. Contact your payment service provider for further information.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

50

sourceOfFunds.provided.sofort = CONDITIONAL

Details about the payer's bank account used for a payment made using Sofortbanking.

The format of the bank account details differs per country.

Fixed value

sourceOfFunds.provided.sofort.bic String = CONDITIONAL

The international Business Identifier Code (BIC) for the payer's bank account.

Existence

CONDITIONAL

The unique identifier assigned to you by the Token Service Provider that you requested a token from for this payment.

This field is mandatory for payments where the Chase Pay wallet was used.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

11

maximum length

11

sourceOfFunds.type Enumeration = CONDITIONAL

The payment method used for this authentication.

If you are passing card or scheme token data on the API, then you need to set this value, and also provide the card or token details in the sourceOfFunds.provided.card group.

If you are making a payment with a gateway token, then you can leave this field unset, and only populate the sourceOfFund.token field.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

ACH

The payer chose to pay using an electronic fund transfer, to be processed via the Automated Clearing House (ACH) Network. You must provide the payer's bank account details and information about the type of ACH payment under the sourceOfFunds.provided.ach parameter group.

ALIPAY

The payer selected the payment method Alipay.

BOLETO_BANCARIO

The payer selected the payment method Boleto Bancario.

CARD

Use this value for authentications using the card number.

EBT_CARD

Use this value for Electronic Benefits Transfer (EBT) card payments. The additional EBT data must also be provided in the sourceOfFunds.provided.ebt parameter group.

ENETS

The payer selected the payment method eNETS.

GIFT_CARD

Use this value for gift cards.

GIROPAY

The payer selected the payment method giropay.

IDEAL

The payer selected the payment method iDEAL.

KLARNA

The payer selected the payment method Klarna.

OXXO

The payer selected the payment method OXXO.

PAYPAL

The payer selected the payment method PayPal.

POLI

The payer selected the payment method POLi.

SCHEME_TOKEN

Use this value for authentications using scheme tokens.

SEPA

The payer selected the payment method SEPA.

SOFORT

The payer selected the payment method Sofortbanking.

UNION_PAY

The payer selected the payment method UnionPay.

WECHAT_PAY

The payer selected the payment method WeChatPay.

subgatewayMerchant = CONDITIONAL

Information about your merchant.

This group only applies if you:

operate a gateway, and
you are not boarding your merchants onto the gateway, and
you are enabled for this capability on the gateway.

If you are such a gateway, use these fields to provide information about your merchant, so that our gateway can process their transaction on your behalf.

Note: In these cases, you must also provide values for the follow fields:

order.merchantCategoryCode
transaction.frequency

Fixed value

subgatewayMerchant.acquirer[n] = CONDITIONAL

Details about this merchant's account with the acquirers they use for payment processing.

A merchant might have one or more acquirers.

Each record in this group applies to one acquirer. If your gateway knows exactly which acquirer will use for this transaction, then you can provide just that acquirer's data. Alternatively, you can specify a set of acquirers, in which case the gateway will select between them based on the routing rules that configured in our gateway.

In this group, the term 'acquirer' includes banks acquiring scheme cards (such as MasterCard,or Visa), and alternative providers (such as UnionPay, or SEPA)

Fixed value

subgatewayMerchant.acquirer[n].3DS1 = CONDITIONAL

Information about the merchant's registration to use 3-D Secure authentication version 1 for this acquirer.

Fixed value

subgatewayMerchant.acquirer[n].3DS1.amexSafeKey = CONDITIONAL

Information about the merchant's registration to use American Express SafeKey 3-D Secure authentication version 1 for this acquirer.

Fixed value

subgatewayMerchant.acquirer[n].3DS1.amexSafeKey.merchantId String = CONDITIONAL

The unique identifier assigned to the merchant by their acquirer when they registered to use American Express SafeKey 3-D Secure authentication version 1.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

24

subgatewayMerchant.acquirer[n].3DS1.mastercardSecureCode = CONDITIONAL

Information about the merchant's registration to use Mastercard SecureCode 3-D Secure authentication version 1 for this acquirer.

Fixed value

subgatewayMerchant.acquirer[n].3DS1.mastercardSecureCode.merchantId String = CONDITIONAL

The unique identifier assigned to the merchant by their acquirer when they registered to use Mastercard SecureCode 3-D Secure authentication version 1.

Existence

CONDITIONAL

The name of the acquirer on which your merchant has an account.This is the value as returned in transaction.acquirer.id, for example ACME_BANK.

Your payment service provider will supply the acquirer names that apply to you.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

0

maximum length

40

subgatewayMerchant.address = CONDITIONAL

The address of this merchant.

Fixed value

subgatewayMerchant.address.city String = CONDITIONAL

The city or town of this merchant's billing address.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

30

subgatewayMerchant.address.countryCode Upper case alphabetic text = CONDITIONAL

The country of this merchant's billing address.

The value must be a three-letter country code according to ISO 3166-1 alpha-3.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data must consist of the characters A-Z

JSON type

String

minimum length

3

maximum length

3

subgatewayMerchant.address.postcodeZip String = CONDITIONAL

The zip or postal code of this merchant's billing address.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

16

subgatewayMerchant.address.state String = CONDITIONAL

The state or province of the merchant's billing address.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

30

subgatewayMerchant.address.street1 String = CONDITIONAL

The first line of the street address of this merchant's billing address.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

40

subgatewayMerchant.address.street2 String = CONDITIONAL

The second line of the street address of this merchant's billing address.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

40

subgatewayMerchant.authentication[n] = CONDITIONAL

JSON type

String

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

AMEX_SAFEKEY

DINERS_PROTECTBUY

JCB_JSECURE

MASTERCARD_SECURECODE

RUPAY

VERIFIED_BY_VISA

subgatewayMerchant.id Alphanumeric + additional characters = CONDITIONAL

The identifier you use to uniquely identify this merchant on your system.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

36

subgatewayMerchant.name String = CONDITIONAL

This merchant's registered business, trading or organization name.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

100

subgatewayMerchant.websiteUrl Url = CONDITIONAL

The URL of the merchant's website.

You must provide a value if you want the gateway to perform 3-D Secure authentication of the payer.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

token Alphanumeric = CONDITIONAL

The token you supply that you wish to create or update.

You can only supply this value when creating a token if your token repository is configured to support merchant-supplied tokens.

On response, the format of the token depends on the token generation strategy configured for your repository. See Tokenization for more details.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

40

transaction = CONDITIONAL

minimum length

1

maximum length

6

transaction.currency Upper case alphabetic text = CONDITIONAL

The currency which should be used for acquirer card verification.

Not required for basic verification.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data must consist of the characters A-Z

JSON type

String

minimum length

3

maximum length

3

transaction.discountAmount Decimal = CONDITIONAL

The total amount deducted from the transaction amount that would normally apply.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

14

transaction.frequency Enumeration = CONDITIONAL

Indicates the frequency of the transaction offered to the payer.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

INSTALLMENT

Indicates an installment transaction where the payer authorizes you to deduct multiple payments over an agreed period of time for a single purchase.

RECURRING

Indicates a recurring transaction where the payer authorizes you to automatically debit their accounts for bill or invoice payments.

SINGLE

Indicates a single transaction where a single payment is used to complete the order.

transaction.id String = CONDITIONAL

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.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

40

transaction.item[n] = CONDITIONAL

Information about the items the payer purchases with the order.

Fixed value

transaction.item[n].brand String = CONDITIONAL

The brand of the item.

For example, Dell.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

127

transaction.item[n].category String = CONDITIONAL

Your category for the item.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

127

transaction.item[n].description String = CONDITIONAL

Description for the item with information such as size, color, etc.

For example, 'Color:Red, Size:M'

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

127

transaction.item[n].detail = CONDITIONAL

Only use this parameter group to provide additional line item details required for a better interchange rate for Purchasing Cards, Business and/or Corporate Cards (Level 3).

Check with your payment service provider if Level 3 data is supported for your acquirer.

Fixed value

transaction.item[n].detail.acquirerCustom JSON Text = CONDITIONAL

Use this field to provide line item details that your acquirer requires you to provide.

Data must be provided in JSON format using the record name and field name (separated by a comma) to identify the value provided. Contact your payment service provider for details about the supported fields including the field definitions.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data is valid Json Format

JSON type

String

minimum length

1

maximum length

4000

transaction.item[n].detail.commodityCode Digits = CONDITIONAL

A code describing a commodity or a group of commodities pertaining to goods classification.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data is a number between 1 and 9999999999999999 represented as a string.

JSON type

String

transaction.item[n].detail.tax[n] = CONDITIONAL

Information about the taxes per line item.

Fixed value

transaction.item[n].detail.tax[n].amount Decimal = CONDITIONAL

The tax amount for the tax type defined in order.item[n].detail.tax[m].type for the item.

Note that the tax amount provided must reflect the tax amount applied before a discount was applied.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

14

transaction.item[n].detail.tax[n].rate Decimal = CONDITIONAL

The tax rate (percentage) applied to the item for the tax type defined in order.item[n].detail.tax[m].type.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

6

transaction.item[n].detail.tax[n].type String = CONDITIONAL

The tax type for which the amount specified under order.item[n].detail.tax[m].amount has been paid for this item.

The correct value as used by your acquirer may have to be provided. Contact your payment service provider for details.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

127

transaction.item[n].detail.unitDiscountRate Decimal = CONDITIONAL

The discount rate (percentage) applied to this item.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

6

transaction.item[n].detail.unitTaxRate Decimal = CONDITIONAL

The tax rate (percentage) of the tax charged for this item.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

6

transaction.item[n].detail.unitTaxType String = CONDITIONAL

The type of tax charged for this item.

The correct value as used by your acquirer may have to be provided. Contact your payment service provider for details.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

10

transaction.item[n].detail.unspsc Digits = CONDITIONAL

The United Nations Standard Products and Services Code (UNSPSC) for the item.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data is a number between 1 and 9999999999999999 represented as a string.

JSON type

String

transaction.item[n].detail.upc Digits = CONDITIONAL

The Universal Product Code (UPC) for the item.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data is a number between 1 and 9999999999999999 represented as a string.

JSON type

String

transaction.item[n].industryCategory Enumeration = CONDITIONAL

Provide the industry category to send this line item to your acquirer for specialized processing as industry data.

Such processing might have legal obligations, which are your responsibility. Do not provide an industry category, unless you are certain it applies to you, and is accepted by your acquirer.

We support the following industry standard processing:

US health care processing using the IIAS standard.

The supported values for this field are:

HEALTHCARE_VISION, HEALTHCARE_DENTAL, HEALTHCARE_PRESCRIPTION, HEALTHCARE_OTHER

We formulate an IIAS message by summing the amounts of all the line items with the same industry category. The amount of a line item is computed as:

(order.item.unitPrice + order.item.tax) * order.item.quantity

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

HEALTHCARE_DENTAL

HEALTHCARE_OTHER

HEALTHCARE_PRESCRIPTION

HEALTHCARE_VISION

transaction.item[n].name String = CONDITIONAL

A short name describing the item.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

127

transaction.item[n].quantity Decimal = CONDITIONAL

The quantity of the item.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

0

maximum length

30

transaction.item[n].sku String = CONDITIONAL

The SKU (Stock Keeping Unit) or the item identifier for this item.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

127

The total item amount for this transaction.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

14

transaction.merchantNote String = CONDITIONAL

Your note about this transaction.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

Indicates the channel through which you received authorization for the payment for this order from the payer.

For example, set this value to INTERNET if the payer initiated the payment online.

If you have an existing agreement with the payer that authorizes you to process this payment (for example, a recurring payment) then set this value to MERCHANT.You only need to provide transaction.source if you want to override the default value configured for your acquirer link.

Note:

You can only override the default value if you have the requisite permission.
The value you provide must match one of those configured by your payment service provider.
You can only set the transaction source on the initial transaction on an order. It cannot be changed on subsequent transactions.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

CALL_CENTRE

Transaction conducted via a call centre.

CARD_PRESENT

Transaction where the card is presented to the merchant.

INTERNET

Transaction conducted over the Internet.

MAIL_ORDER

Transaction received by mail.

MERCHANT

Transaction initiated by you based on an agreement with the payer. For example, a recurring payment, installment payment, or account top-up.

MOTO

Transaction received by mail or telephone.

PAYER_PRESENT

Transaction where a non-card payment method is presented to the Merchant.

TELEPHONE_ORDER

Transaction received by telephone.

VOICE_RESPONSE

Transaction conducted by a voice/DTMF recognition system.

transaction.targetTransactionId String = CONDITIONAL

The identifier for the transaction you wish to refund.

That is the {transactionId} URL field for REST and the transaction.id field for NVP.

If you do not provide a target transaction ID the gateway will try to identify a transaction. If no transaction can be found or more than one transaction is identified, the request is rejected.

Existence

CONDITIONAL

The type of tax included in the transaction amount.

The correct value as used by your acquirer may have to be provided. Contact your payment service provider for details.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

50

transaction.taxAmount Decimal = CONDITIONAL

The total tax amount for the transaction.

You only need to provide this field when you capture or refund part of the order amount. In this case, the amount must not exceed order.taxAmount. If you provide this field when you capture or refund the full amount of the order, then the value provided must match order.taxAmount.

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

minimum length

1

maximum length

14

transaction.taxStatus Enumeration = CONDITIONAL

Indicates your tax status for this transaction.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

EXEMPT

Indicates that you are exempt from tax.

NOT_EXEMPT

Indicates that you are not exempt from tax.

NOT_PROVIDED

Indicates that you are not providing information about being exempt from tax.

transactionSource Enumeration = CONDITIONAL

Indicates the channel through which you received authorization for the payment for this order from the payer.

For example, set this value to INTERNET if the payer initiated the payment online.

If you have an existing agreement with the payer that authorizes you to process this payment (for example, a recurring payment) then set this value to MERCHANT.You only need to provide transaction.source if you want to override the default value configured for your acquirer link.

Note:

You can only override the default value if you have the requisite permission.
The value you provide must match one of those configured by your payment service provider.
You can only set the transaction source on the initial transaction on an order. It cannot be changed on subsequent transactions.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

CALL_CENTRE

Transaction conducted via a call centre.

CARD_PRESENT

Transaction where the card is presented to the merchant.

INTERNET

Transaction conducted over the Internet.

MAIL_ORDER

Transaction received by mail.

MERCHANT

Transaction initiated by you based on an agreement with the payer. For example, a recurring payment, installment payment, or account top-up.

MOTO

Transaction received by mail or telephone.

PAYER_PRESENT

Transaction where a non-card payment method is presented to the Merchant.

TELEPHONE_ORDER

Transaction received by telephone.

VOICE_RESPONSE

Transaction conducted by a voice/DTMF recognition system.

userId String = CONDITIONAL

The person who initiated this transaction.

For Merchant Administration, the person is identified by their logon name.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

256

verificationStrategy Enumeration = CONDITIONAL

The strategy used to verify the payment instrument details before they are stored.

You only need to specify the verification strategy if you want to override the default value configured for your merchant profile. When the verification strategy is BASIC or ACQUIRER you must also provide the card expiry date in the sourceOfFunds.provided.card.expiry parameter group.

Existence

CONDITIONAL

Fixed value

Validation Rules

Response fields from MasterPass operations.

Fixed value

wallet.masterpass.allowedCardTypes String = CONDITIONAL

The card types supported for the merchant.

You provide this value when you initiate a MasterPass interaction to limit the card types that the payer can select to those supported by the merchant.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

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

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

wallet.masterpass.payerAuthentication Enumeration = CONDITIONAL

Indicates whether payer authentication is required for the MasterPass Express Checkout interaction.

Existence

CONDITIONAL

Fixed value

Validation Rules

JSON type

String

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

NOT_REQUIRED

This operation does not require further payer authentication.

REQUIRED

This operation requires further payer authentication.

wallet.masterpass.requestToken String = CONDITIONAL

The MasterPass request token required to initiate a MasterPass wallet interaction.

You provide this value in order to initiate a MasterPass interaction.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

255

wallet.masterpassExpressCheckout.originUrl Url = CONDITIONAL

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

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

wallet.masterpassExpressCheckout.precheckoutTransactionId String = CONDITIONAL

A MasterPass transaction identifier.

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

50

wallet.masterpassExpressCheckout.secondaryOriginUrl Url = CONDITIONAL

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

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

Existence

CONDITIONAL

Fixed value

Validation Rules

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

JSON type

String

wallet.visaCheckout = CONDITIONAL

Response fields from Visa Checkout Open Wallet operation.

Fixed value

wallet.visaCheckout.callId String = CONDITIONAL

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

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

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

48

wallet.visaCheckout.cardArts String = CONDITIONAL

Card artwork details as returned by Visa Checkout, including the URL of the card art, and height and width of the card art in pixels, for example {"cardArt":[{"baseImageFileName":"<Image URL>","height":50,"width":77}]}.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

200

wallet.visaCheckout.cardBrand String = CONDITIONAL

Card brand returned by Visa Checkout indicating the card brand selected by the payer at Visa Checkout.

Existence

CONDITIONAL

Fixed value

Validation Rules

Data can consist of any characters

JSON type

String

minimum length

1

maximum length

50

URL	https://ap-gateway.mastercard.com/api/rest/version/52/merchant/{merchantId}/session/{sessionId}
HTTP Method	GET
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.

Retrieve Session

Request Parameters

correlationId String = OPTIONAL

responseControls = OPTIONAL

responseControls.sensitiveData String = OPTIONAL

{merchantId} Alphanumeric + additional characters COMPULSORY

{sessionId} ASCII Text COMPULSORY

Response Parameters

merchant Alphanumeric + additional characters = Always Provided

session = Always Provided

session.id ASCII Text = Always Provided

session.updateStatus Enumeration = Always Provided

session.version ASCII Text = Always Provided

wallet.masterpass = CONDITIONAL

wallet.masterpass.allowedCardTypes String = CONDITIONAL

wallet.masterpass.longAccessToken String = CONDITIONAL

wallet.masterpass.merchantCheckoutId String = CONDITIONAL

wallet.masterpass.originUrl Url = CONDITIONAL

wallet.masterpass.payerAuthentication Enumeration = CONDITIONAL

wallet.masterpass.requestToken String = CONDITIONAL

wallet.masterpass.secondaryOriginUrl Url = CONDITIONAL

wallet.visaCheckout = CONDITIONAL

wallet.visaCheckout.cardArts String = CONDITIONAL

wallet.visaCheckout.cardBrand String = CONDITIONAL

3DSecure = CONDITIONAL

3DSecure.acsEci Digits = CONDITIONAL

3DSecure.authenticationRedirect = CONDITIONAL

3DSecure.authenticationRedirect.pageGenerationMode Enumeration = CONDITIONAL

3DSecure.authenticationRedirect.responseUrl Url = CONDITIONAL

3DSecure.authenticationRedirect.simple = CONDITIONAL

3DSecure.authenticationRedirect.simple.expectedHtmlEncoding Enumeration = CONDITIONAL

3DSecure.authenticationRedirect.simple.redirectDisplayBackgroundColor Alphanumeric + additional characters = CONDITIONAL

3DSecure.authenticationRedirect.simple.redirectDisplayContinueButtonText String = CONDITIONAL

3DSecure.authenticationRedirect.simple.redirectDisplayTitle String = CONDITIONAL

3DSecure.authenticationToken Base64 = CONDITIONAL

3DSecure.goodsDescription String = CONDITIONAL

3DSecure.paResStatus Alpha = CONDITIONAL

3DSecure.veResEnrolled Alpha = CONDITIONAL

3DSecure.xid Base64 = CONDITIONAL

3DSecureId ASCII Text = CONDITIONAL

agreement = CONDITIONAL

agreement.expiryDate Date = CONDITIONAL

agreement.id String = Always Provided

agreement.recurring = CONDITIONAL

agreement.recurring.daysBetweenPayments Integer = CONDITIONAL

airline = CONDITIONAL

airline.bookingReference Alphanumeric = CONDITIONAL

airline.documentType Enumeration = CONDITIONAL

airline.itinerary = CONDITIONAL

airline.itinerary.leg[n] = CONDITIONAL

airline.itinerary.leg[n].carrierCode Regex = CONDITIONAL

airline.itinerary.leg[n].conjunctionTicketNumber Alphanumeric = CONDITIONAL

airline.itinerary.leg[n].couponNumber Alphanumeric = CONDITIONAL

airline.itinerary.leg[n].departureAirport Upper case alphabetic text = CONDITIONAL

airline.itinerary.leg[n].departureDate Date = CONDITIONAL

airline.itinerary.leg[n].departureTax Decimal = CONDITIONAL

airline.itinerary.leg[n].departureTime Time = CONDITIONAL

airline.itinerary.leg[n].destinationAirport Upper case alphabetic text = CONDITIONAL

airline.itinerary.leg[n].destinationArrivalDate Date = CONDITIONAL

airline.itinerary.leg[n].destinationArrivalTime Time = CONDITIONAL

airline.itinerary.leg[n].endorsementsRestrictions Alphanumeric = CONDITIONAL

airline.itinerary.leg[n].exchangeTicketNumber Alphanumeric = CONDITIONAL

airline.itinerary.leg[n].fare Decimal = CONDITIONAL

airline.itinerary.leg[n].fareBasis Alphanumeric = CONDITIONAL

airline.itinerary.leg[n].fees Decimal = CONDITIONAL

airline.itinerary.leg[n].flightNumber Alphanumeric = CONDITIONAL

airline.itinerary.leg[n].stopoverPermitted Boolean = CONDITIONAL

airline.itinerary.leg[n].taxes Decimal = CONDITIONAL

airline.itinerary.leg[n].travelClass Alphanumeric = CONDITIONAL

airline.itinerary.numberInParty Digits = CONDITIONAL

airline.itinerary.originCountry Upper case alphabetic text = CONDITIONAL

airline.passenger[n] = CONDITIONAL

airline.passenger[n].firstName String = CONDITIONAL

airline.passenger[n].frequentFlyerNumber String = CONDITIONAL

airline.passenger[n].lastName String = CONDITIONAL

airline.passenger[n].middleName String = CONDITIONAL

airline.passenger[n].specificInformation Alphanumeric = CONDITIONAL

airline.passenger[n].title String = CONDITIONAL

airline.planNumber Alphanumeric = CONDITIONAL

airline.ticket = CONDITIONAL