Update Session

Request to add or update request fields contained in the session.

URL https://na.gateway.mastercard.com/api/rest/version/58/merchant/{merchantId}/session/{sessionId}
HTTP Method PUT
Authentication This operation requires authentication via one of the following methods:
  • Certificate authentication.
  • Basic HTTP authentication as described at w3.org. Provide 'merchant.<your gateway merchant ID>' in the userid portion and your API password in the password portion.

Request Parameters

agreement   = OPTIONAL

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

Existence
OPTIONAL
Fixed value
Validation Rules
Data must comply with ISO 8601 extended date format, yyyy-mm-dd
JSON type
String

agreement.id  String = OPTIONAL

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

  • Recurring payments: you have an agreement with the payer that authorizes you to automatically debit their account at agreed intervals for fixed or variable amounts. For example, gym membership, phone bills, or magazine subscriptions.
  • Installment payments: you have an agreement with the payer that authorizes you to process multiple payments over an agreed period of time for a single purchase. For example, the payer purchases an item for $1000 and pays for it in four monthly installments.
  • Unscheduled: you have an agreement with the payer that authorizes you to process future payments when required. For example, the payer authorizes you to process an account top-up transaction for a transit card when the account balance drops below a certain threshold.
When you first establish an agreement with the payer you should also specify the type of agreement in agreement.type.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

agreement.recurring   = OPTIONAL

Information about agreements for recurring payments.
Fixed value

agreement.recurring.amountVariability  Enumeration = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
FIXED
All payments in the recurring payment agreement have the same amount. Examples include magazine subscriptions or gym memberships.
VARIABLE
The amount for the payments within the recurring payment agreement differs between payments. Examples include usage-based charges like utility or phone bills.

agreement.recurring.daysBetweenPayments  Integer = OPTIONAL

Existence
OPTIONAL
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

agreement.recurring.numberOfPayments  Integer = OPTIONAL

Existence
OPTIONAL
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
9999

agreement.type  Enumeration = OPTIONAL

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

The gateway will use the value you specify for subsequent payments in the series.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
INSTALLMENT
An agreement where the payer authorizes the payment for a single purchase to be split into a number of payments processed at agreed intervals. For example, pay for a purchase in six monthly installments.
OTHER
An agreement where the merchant wants to link related payments for any purpose other than processing recurring, installment, or unscheduled payments. For example, split tender payments.
RECURRING
An agreement where the payer authorizes the merchant to process payments for recurring bills or invoices at agreed intervals (for example, weekly, monthly). The amount might be fixed or variable.
UNSCHEDULED
An agreement where the payer authorizes the merchant to automatically deduct funds for a payment for an agreed purchase when required (unscheduled). For example, auto top-ups when the account value falls below a threshold.

airline   = OPTIONAL

Airline industry specific data.
Fixed value

airline.bookingReference  Alphanumeric = OPTIONAL

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

Existence
OPTIONAL
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   = OPTIONAL

Itinerary details
Fixed value

airline.itinerary.leg[n]   = OPTIONAL

Travel leg details.
Fixed value

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

Existence
OPTIONAL
Fixed value
Validation Rules
Data must match regex
JSON type
String
regex
\w{2}|\d{3}|\w{2}/\d{3}
message
Carrier code must be 2 characters, 3 digits or a combination of both in the format: ZZ/999

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

Existence
OPTIONAL
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.itinerary.leg[n].couponNumber  Alphanumeric = OPTIONAL

Each trip leg requires a separate coupon. The coupon within the series is identified by the coupon number.
Existence
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z
JSON type
String
minimum length
1
maximum length
1

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

Existence
OPTIONAL
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 = OPTIONAL

Existence
OPTIONAL
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 = OPTIONAL

Existence
OPTIONAL
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 = OPTIONAL

Existence
OPTIONAL
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 = OPTIONAL

Existence
OPTIONAL
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 = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data must comply with ISO 8601 extended date format, yyyy-mm-dd
JSON type
String

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

Existence
OPTIONAL
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].endorsementsRestrictions  Alphanumeric = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z
JSON type
String
minimum length
1
maximum length
20

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

Existence
OPTIONAL
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.itinerary.leg[n].fare  Decimal = OPTIONAL

Existence
OPTIONAL
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].fareBasis  Alphanumeric = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z
JSON type
String
minimum length
1
maximum length
24

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

Existence
OPTIONAL
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].flightNumber  Alphanumeric = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z
JSON type
String
minimum length
4
maximum length
6

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

Existence
OPTIONAL
Fixed value
Validation Rules
JSON boolean values 'true' or 'false'.
JSON type
Boolean

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

Existence
OPTIONAL
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 = OPTIONAL

Existence
OPTIONAL
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 = OPTIONAL

Existence
OPTIONAL
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 = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data must consist of the characters A-Z
JSON type
String
minimum length
3
maximum length
3

airline.passenger[n]   = OPTIONAL

Passenger details
Fixed value

airline.passenger[n].firstName  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

airline.passenger[n].frequentFlyerNumber  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
20

airline.passenger[n].lastName  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
20

airline.passenger[n].middleName  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

airline.passenger[n].specificInformation  Alphanumeric = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z
JSON type
String
minimum length
1
maximum length
59

airline.passenger[n].title  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
20

airline.planNumber  Alphanumeric = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z
JSON type
String
minimum length
2
maximum length
2

airline.ticket   = OPTIONAL

Ticket details
Fixed value

airline.ticket.conjunctionTicketIndicator  Boolean = OPTIONAL

Conjunction ticket refers to two or more tickets concurrently issued to a passenger and which together constitute a single contract of carriage.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON boolean values 'true' or 'false'.
JSON type
Boolean

airline.ticket.eTicket  Boolean = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
JSON boolean values 'true' or 'false'.
JSON type
Boolean

airline.ticket.exchangedTicketNumber  Alphanumeric = OPTIONAL

Existence
OPTIONAL
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.issue   = OPTIONAL

Ticket issue information.
Fixed value

airline.ticket.issue.address  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
16

airline.ticket.issue.carrierCode  Regex = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data must match regex
JSON type
String
regex
\w{2}|\d{3}|\w{2}/\d{3}
message
Carrier code must be 2 characters, 3 digits or a combination of both in the format: ZZ/999

airline.ticket.issue.carrierName  Alphanumeric = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z
JSON type
String
minimum length
1
maximum length
25

airline.ticket.issue.city  Alphanumeric = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z
JSON type
String
minimum length
1
maximum length
18

airline.ticket.issue.country  Upper case alphabetic text = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data must consist of the characters A-Z
JSON type
String
minimum length
3
maximum length
3

airline.ticket.issue.date  Date = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data must comply with ISO 8601 extended date format, yyyy-mm-dd
JSON type
String

airline.ticket.issue.travelAgentCode  Alphanumeric = OPTIONAL

Existence
OPTIONAL
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 = OPTIONAL

Existence
OPTIONAL
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 = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
JSON boolean values 'true' or 'false'.
JSON type
Boolean

airline.ticket.taxOrFee[n]   = OPTIONAL

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

Existence
OPTIONAL
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 = OPTIONAL

For example, the IATA tax/ charge/ fee type for Passenger Movement Charge (PMC) in Australia is TT1.
Existence
OPTIONAL
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 = OPTIONAL

Existence
OPTIONAL
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 = OPTIONAL

Existence
OPTIONAL
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 = OPTIONAL

Existence
OPTIONAL
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 = OPTIONAL

Existence
OPTIONAL
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 = OPTIONAL

Existence
OPTIONAL
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   = OPTIONAL

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.3ds   = OPTIONAL

Only provide these fields if you authenticated the payer using a different 3-D Secure service provider. If you authenticated the payer using the gateway, then provide authentication.transactionId instead.

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

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

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

authentication.3ds.acsEci  Alphanumeric = OPTIONAL

This is the Electronic Commerce Indicator (ECI) value provided by the issuer's Access Control Server (ACS) to indicate the results of the attempt to authenticate the payer.
Existence
OPTIONAL
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

authentication.3ds.authenticationToken  Base64 = OPTIONAL

The authentication token Included in subsequent transaction request messages and used by the card scheme to verify that the authentication occurred and the values provided are valid. The token should be used unaltered. For 3DS version 1, this field corresponds to the Cardholder Authentication Verification Value (CAVV) for Visa, the Accountholder Authentication Value (AAV) for MasterCard and JCB, or the American Express Verification Value (AEVV) for American Express.

For 3DS version 2, this field corresponds to the Authentication Value.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is Base64 encoded
JSON type
String
allowable lengths
28 or 32

authentication.3ds.transactionId  String = OPTIONAL

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

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


This identifier should be used in subsequent operation requests unaltered.

An XID submitted in this field must be in base64 format.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

authentication.3ds1   = OPTIONAL

Only provide these fields if you authenticated the payer using a different 3-D Secure service provider. If you authenticated the payer using the gateway, then provide authentication.transactionId instead.
Fixed value

authentication.3ds1.paResStatus  Alpha = OPTIONAL

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
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters a-z, A-Z
JSON type
String
minimum length
1
maximum length
1

authentication.3ds1.veResEnrolled  Alpha = OPTIONAL

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

This is the value returned in the 'enrolled' field of the Verify Enrollment Response (VERes) message from the card scheme's Directory Server. For example, Y, N, or U. Refer to the relevant documentation for Mastercard SecureCode™, Verified by Visa™, JCB J/Secure™, American Express SafeKey™, or Diners Club ProtectBuy™.
Existence
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters a-z, A-Z
JSON type
String
minimum length
1
maximum length
1

authentication.3ds2   = OPTIONAL

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

authentication.3ds2.protocolVersion  Alphanumeric + additional characters = OPTIONAL

For example, 2.1.0
Existence
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, '.'
JSON type
String
minimum length
1
maximum length
20

authentication.3ds2.sdk   = OPTIONAL

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

authentication.3ds2.sdk.appId  String = OPTIONAL

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

This field corresponds to EMVCo field sdkAppID
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
36
maximum length
36

authentication.3ds2.sdk.encryptedData  String = OPTIONAL

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

This field corresponds to EMVCo field sdkEncData
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
0
maximum length
64000

authentication.3ds2.sdk.ephemeralPublicKey  JSON Text = OPTIONAL

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

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

This field corresponds to EMVCo field sdkEphemPubKey
Existence
OPTIONAL
Fixed value
Validation Rules
Data is valid Json Format
JSON type
String
minimum length
0
maximum length
256

authentication.3ds2.sdk.interface  Enumeration = OPTIONAL

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

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

This field corresponds to EMVCo data element sdkInterface in the field deviceRenderOptions.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
HTML
The device supports HTML format.
NATIVE
The device supports the UI format native to the payer's device.

authentication.3ds2.sdk.referenceNumber  String = OPTIONAL

This field corresponds to EMVCo field sdkReferenceNumber
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
32

authentication.3ds2.sdk.timeout  Integer = OPTIONAL

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

This field corresponds to EMVCo field sdkMaxTimeout
Existence
OPTIONAL
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
300
maximum value
900

authentication.3ds2.sdk.transactionId  String = OPTIONAL

This field corresponds to EMVCo field sdkTransID
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
36
maximum length
36

authentication.3ds2.sdk.uiType  Comma separated enumeration = OPTIONAL

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

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

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

This field corresponds to EMVCo data element sdkUiType in the field deviceRenderOptions.
Existence
OPTIONAL
Fixed value
Validation Rules
Indicates the UI types which the SDK supports for displaying authentication challenges within the app.
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.3ds2.statusReasonCode  String = OPTIONAL

Refer to the EMVCo specification for 3-D Secure.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
2
maximum length
2

authentication.3ds2.transactionStatus  Alpha = OPTIONAL

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

Refer to the EMVCo specification for 3-D Secure.
Existence
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters a-z, A-Z
JSON type
String
minimum length
1
maximum length
1

authentication.acceptVersions  Comma Separated Enumeration = OPTIONAL

Existence
OPTIONAL
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 = OPTIONAL

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
OPTIONAL
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.
REQUEST_WHITELISTING
Tells the issuer that you prefer them to present the payer with a challenge and that you want them to invite the payer to add you to their list of trusted merchants. If the payer whitelists you, they can skip authentication for any future payments. You will be able to tell whether the payer has added you to their list of trusted merchants by looking at authentication.psd2.whitelistStatus in the authentication response following the completion of the challenge.

authentication.goodsDescription  String = OPTIONAL

If supported, this description will be displayed on the authentication UI presented to the payer.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
0
maximum length
30

authentication.psd2   = OPTIONAL

It provides details about SCA exemptions under PSD2.
Fixed value

authentication.psd2.exemption  Enumeration = OPTIONAL

Note:
  • For recurring payments, provide the MERCHANT_INITIATED_TRANSACTION value only if the amount is the same. If the amount is variable, provide RECURRING_PAYMENT instead.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
AUTO
If either a LOW_RISK or LOW_VALUE_PAYMENT exemption applies to the transaction, it is automatically claimed by the gateway on behalf of the merchant.
LOW_RISK
Exemption is claimed because the acquirer has a low fraud rate.
LOW_VALUE_PAYMENT
Exemption is claimed as the amount is below 30 Euro.
MERCHANT_INITIATED_TRANSACTION
The transaction is excluded as it was initiated by the merchant based on an agreement with the payer. For example, a recurring payment (for a fixed amount), installment payment, or account top-up. In these cases, the payer is not present and cannot participate in an authentication interaction. Merchant initiated transactions are only applicable to subsequent transactions on the order and are out of scope of the PSD2 RTS on Strong Customer Authentication (SCA). The payer must be authenticated during the first transaction that established the agreement.
NONE
An exemption is not claimed for this transaction. The merchant requires Strong Customer Authentication (SCA) be performed.
RECURRING_PAYMENT
The transaction is exempt as it was initiated by the merchant based on an agreement with the payer for a recurring payment for a variable amount. This value is only applicable to subsequent transactions on the order. In this case, the payer is not present and cannot participate in an authentication interaction. The payer must be authenticated during the first transaction that established the agreement.
SECURE_CORPORATE_PAYMENT
The transaction is exempt as it is a corporate or Business-to-Business (B2B) payment performed using dedicated payment processes and protocols that are not available to consumers and offer at least equivalent security levels.
WHITELISTED_MERCHANT
The transaction is exempt because the payer has added you to the list of their trusted merchants (as maintained by the issuer).

authentication.redirectResponseUrl  Url = OPTIONAL

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

You must provide this URL, unless you are certain that there will be no interaction with the payer.
Existence
OPTIONAL
Fixed value
Validation Rules
Ensure that the URL begins with 'https' and is longer than 11 characters.
JSON type
String

authentication.transactionId  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
40

authorizationResponse   = OPTIONAL

Authorisation response fields for a standalone capture request.
Fixed value

authorizationResponse.avsCode  ASCII Text = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data consists of ASCII characters
JSON type
String
minimum length
1
maximum length
100

authorizationResponse.cardLevelIndicator  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
2

authorizationResponse.cardSecurityCodeError  String = OPTIONAL

An indicator, provided by the Issuer in the authorization response, to identify the presence of an invalid card security code (CSC). If there is an error, the Issuer will respond with the 1-byte CSC Error Code (Y).
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
1

authorizationResponse.cardSecurityCodePresenceIndicator  Alphanumeric = OPTIONAL

Existence
OPTIONAL
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 = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
3

authorizationResponse.commercialCardIndicator  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
1

authorizationResponse.financialNetworkCode  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
3

authorizationResponse.financialNetworkDate  Date = OPTIONAL

For transactions processed via the MasterCard Network this is the MasterCard Network Reference Date.
Existence
OPTIONAL
Fixed value
Validation Rules
Data must comply with ISO 8601 extended date format, yyyy-mm-dd
JSON type
String

authorizationResponse.marketSpecificData  String = OPTIONAL

For example, B may indicate "bill payment" depending on the acquirer.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
1

authorizationResponse.posData  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
13

authorizationResponse.posEntryMode  String = OPTIONAL

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
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
4

authorizationResponse.processingCode  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
6

authorizationResponse.responseCode  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
3

authorizationResponse.returnAci  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
1

authorizationResponse.trackQuality  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
2

authorizationResponse.transactionIdentifier  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
15

authorizationResponse.transactionIntegrityClass  Alphanumeric = OPTIONAL

The indicator is only supported by some schemes and for all regions.
Existence
OPTIONAL
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.validationCode  String = OPTIONAL

This value must be stored to be sent with the capture transaction.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
4

billing   = OPTIONAL

Details of the payer's billing address.
Fixed value

billing.address   = OPTIONAL

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

billing.address.city  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

billing.address.company  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

billing.address.country  Upper case alphabetic text = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data must consist of the characters A-Z
JSON type
String
minimum length
3
maximum length
3

billing.address.postcodeZip  Alphanumeric + additional characters = OPTIONAL

Existence
OPTIONAL
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

billing.address.stateProvince  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
20

billing.address.stateProvinceCode  String = OPTIONAL

Providing this field might improve your payer experience for 3-D Secure payer authentication.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
3

billing.address.street  String = OPTIONAL

For example, this may be the street name and number, or the Post Office Box details.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

billing.address.street2  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

browserPayment   = OPTIONAL

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

browserPayment.operation  Enumeration = OPTIONAL

For a successful Authorization transaction, you must submit a CAPTURE request to move the funds from the payer's account to your account.
Existence
OPTIONAL
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   = OPTIONAL

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

browserPayment.paypal.agreementConfirmation  Enumeration = OPTIONAL

This field is only required when requesting a PayPal billing agreement.
Existence
OPTIONAL
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 = OPTIONAL

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
OPTIONAL
Fixed value
Validation Rules
JSON boolean values 'true' or 'false'.
JSON type
Boolean

browserPayment.paypal.overrideShippingAddress  Boolean = OPTIONAL

By default, the payer is allowed to change the shipping address. For more detailed information about the payer overriding the shipping address on the PayPal website, see PayPal Integration: Display/Override Shipping Address.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON boolean values 'true' or 'false'.
JSON type
Boolean

browserPayment.paypal.paymentConfirmation  Enumeration = OPTIONAL

With the latter option, you must confirm the payment using the CONFIRM_BROWSER_PAYMENT operation.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
CONFIRM_AT_MERCHANT
The payer commits to the payment on your website.
CONFIRM_AT_PROVIDER
The payer commits to the payment on the PayPal website.

browserPayment.preferredLanguage  String = OPTIONAL

Provide the IETF language tag for the language in accordance with RFC 5646. You can provide either the two-letter primary language tag (for example, en, fr) or the two-letter primary language tag plus the region sub-tag (for example, en-US, fr-CA).
Existence
OPTIONAL
Fixed value
Validation Rules
Data must be a language identifier or IETF language tag
JSON type
String
minimum length
2
maximum length
35

browserPayment.returnUrl  Url = OPTIONAL

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
OPTIONAL
Fixed value
Validation Rules
Ensure that the URL begins with 'https' and is longer than 11 characters.
JSON type
String

constraints   = OPTIONAL

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

constraints.paymentPlans   = OPTIONAL

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

constraints.paymentPlans.numberOfDeferrals  Integer = OPTIONAL

Existence
OPTIONAL
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

constraints.paymentPlans.numberOfPayments  Integer = OPTIONAL

Existence
OPTIONAL
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
99

constraints.paymentPlans.supported[n]  String = OPTIONAL

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

See Payment Plans for the supported payment plans and their identifiers.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
40

correlationId  String = OPTIONAL

The value provided is not validated, does not persist in the gateway, and is returned as provided in the response to the request.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
XSD type
string
minimum length
1
maximum length
100

cruise   = OPTIONAL

Cruise industry data.
Fixed value

cruise.bookingReference  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
12

cruise.company   = OPTIONAL

Information about the cruise line.
Fixed value

cruise.company.address   = OPTIONAL

Address of the cruise line.
Fixed value

cruise.company.address.city  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

cruise.company.address.country  Upper case alphabetic text = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data must consist of the characters A-Z
JSON type
String
minimum length
3
maximum length
3

cruise.company.address.postCodeZip  Alphanumeric + additional characters = OPTIONAL

Existence
OPTIONAL
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

cruise.company.address.stateProvince  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
20

cruise.company.address.street  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

cruise.company.address.street2  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

cruise.company.contact   = OPTIONAL

Contact details of the cruise line.
Fixed value

cruise.company.contact.companyPhone  Telephone Number = OPTIONAL

Existence
OPTIONAL
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

cruise.company.contact.customerServicePhone  Telephone Number = OPTIONAL

Existence
OPTIONAL
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

cruise.departureDate  Date = OPTIONAL

The value entered must be equal to or earlier than cruise.returnDate.
Existence
OPTIONAL
Fixed value
Validation Rules
Data must comply with ISO 8601 extended date format, yyyy-mm-dd
JSON type
String

cruise.passenger[n]   = OPTIONAL

Cruise passenger details.
Fixed value

cruise.passenger[n].firstName  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

cruise.passenger[n].folioNumber  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
30

cruise.passenger[n].lastName  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

cruise.passenger[n].middleName  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

cruise.passenger[n].title  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

cruise.returnDate  Date = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data must comply with ISO 8601 extended date format, yyyy-mm-dd
JSON type
String

cruise.shipName  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

cruise.travelAgentCode  Alphanumeric = OPTIONAL

Existence
OPTIONAL
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

cruise.travelAgentName  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
30

cruise.travelPackageItems  Comma separated enumeration = OPTIONAL

Existence
OPTIONAL
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.
CAR_RENTAL
Car rental is included in the travel package.
CRUISE_ONLY
No additional items are included in the cruise travel package.
FLIGHT
Flights are included in the travel package.

currencyConversion   = OPTIONAL

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

You can only provide DCC information on the initial transaction for an order. If provided on subsequent transactions or an order, DCC information will be ignored.
Fixed value

currencyConversion.exchangeRateTime  DateTime = OPTIONAL

The timestamp may need to be displayed to the payer on the merchant site to satisfy regulatory requirements.
Existence
OPTIONAL
Fixed value
Validation Rules
An instant in time expressed in ISO8601 date + time format - "YYYY-MM-DDThh:mm:ss.SSSZ"
JSON type
String

currencyConversion.marginPercentage  Decimal = OPTIONAL

The margin percentage may need to be displayed to the payer on the merchant site to satisfy regulatory requirements.
Existence
OPTIONAL
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
8

currencyConversion.payerAmount  Decimal = OPTIONAL

You must include this field if the payer accepted the DCC offer you presented to them.
Existence
OPTIONAL
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

currencyConversion.payerCurrency  Upper case alphabetic text = OPTIONAL

The currency must be expressed as an ISO 4217 alpha code, e.g. USD and must be different to that provided for transaction currency. You must include this field if the payer accepted the DCC offer you presented to them.
Existence
OPTIONAL
Fixed value
Validation Rules
Data must consist of the characters A-Z
JSON type
String
minimum length
3
maximum length
3

currencyConversion.payerExchangeRate  Decimal = OPTIONAL

The payer exchange rate includes the foreign exchange markup (marginPercentage). The payer exchange rate is displayed to the payer on the merchant site.
Existence
OPTIONAL
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
19

currencyConversion.provider  Enumeration = OPTIONAL

This data is for information purposes, and may be useful if you use multiple DCC providers.
Existence
OPTIONAL
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 = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

currencyConversion.requestId  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

currencyConversion.uptake  Enumeration = OPTIONAL

If not provided, this value defaults to NOT_REQUIRED.
Existence
OPTIONAL
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   = OPTIONAL

Information associated with the customer's account.
Fixed value

customer.dateOfBirth  Date = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data must comply with ISO 8601 extended date format, yyyy-mm-dd
JSON type
String

customer.email  Email = OPTIONAL

The field format restriction ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses.
Existence
OPTIONAL
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

customer.firstName  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

customer.lastName  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

customer.mobilePhone  Telephone Number = OPTIONAL

Existence
OPTIONAL
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 = OPTIONAL

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
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
30

customer.phone  Telephone Number = OPTIONAL

Existence
OPTIONAL
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 = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
30

debtRepayment   = OPTIONAL

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

debtRepayment.paymentRecipient   = OPTIONAL

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

debtRepayment.paymentRecipient.accountIdentifier  String = OPTIONAL

For payments into a card account provide the card number. For payments into other accounts (for example a bank account) provide the account number. The value provided will be returned masked in the response.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

debtRepayment.paymentRecipient.dateOfBirth  Date = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data must comply with ISO 8601 extended date format, yyyy-mm-dd
JSON type
String

debtRepayment.paymentRecipient.lastName  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

debtRepayment.paymentRecipient.postcodeZip  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
10

device   = OPTIONAL

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

device.ani  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
10

device.aniCallType  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
2

device.browser  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
255

device.browserDetails   = OPTIONAL

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

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

device.browserDetails.3DSecureChallengeWindowSize  Enumeration = OPTIONAL

This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
250_X_400
390_X_400
500_X_600
600_X_400
FULL_SCREEN

device.browserDetails.acceptHeaders  String = OPTIONAL

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

This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
2048

device.browserDetails.colorDepth  Integer = OPTIONAL

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

This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
Existence
OPTIONAL
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
48

device.browserDetails.javaEnabled  Boolean = OPTIONAL

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

This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON boolean values 'true' or 'false'.
JSON type
Boolean

device.browserDetails.javaScriptEnabled  Boolean = OPTIONAL

You can determine this by setting the relevant value in a form to false, and then attempting to update it to true using JavaScript.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON boolean values 'true' or 'false'.
JSON type
Boolean

device.browserDetails.language  String = OPTIONAL

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

This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
8

device.browserDetails.screenHeight  Integer = OPTIONAL

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

This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
Existence
OPTIONAL
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
999999

device.browserDetails.screenWidth  Integer = OPTIONAL

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

This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
Existence
OPTIONAL
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
999999

device.browserDetails.timeZone  Browser Time Zone Offset = OPTIONAL

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

This must be provided for authentication operations where authentication.channel is PAYER_BROWSER.
Existence
OPTIONAL
Fixed value
Validation Rules
Browser time zone offset between -840 to +840.
JSON type
String

device.fingerprint  String = OPTIONAL

For example, session ID, blackbox ID.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
4000

device.hostname  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
60

device.ipAddress  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
7
maximum length
15

device.mobilePhoneModel  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
255

gatewayEntryPoint  Enumeration = OPTIONAL

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

locale  String = OPTIONAL

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

Existence
OPTIONAL
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   = OPTIONAL

Information about the order associated with this transaction.
Fixed value

order.acceptPartialAmount  Boolean = OPTIONAL

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
OPTIONAL
Fixed value
Validation Rules
JSON boolean values 'true' or 'false'.
JSON type
Boolean

order.amount  Decimal = OPTIONAL

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 is zero if payer funds are not transferred.
Existence
OPTIONAL
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.cashAdvance  Boolean = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
JSON boolean values 'true' or 'false'.
JSON type
String

order.cashbackAmount  Decimal = OPTIONAL

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

This field corresponds to EMV tag 9F03
Existence
OPTIONAL
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.certainty  Enumeration = OPTIONAL

If you do not provide a value for order.certainty the default configured for you by your payment service provider will be used. The value provided in the response shows the value the gateway sent to the acquirer
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
ESTIMATED
The amount authorized is an estimate of the amount that will be captured. It is possible that the amount captured will be less, or might not be captured at all.
FINAL
The full authorized amount is expected to be captured within the mandated time. The order will only be cancelled in exceptional circumstances (for example, the payer cancelled their purchase).

order.currency  Upper case alphabetic text = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data must consist of the characters A-Z
JSON type
String
minimum length
3
maximum length
3

order.custom  String = OPTIONAL

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
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
250

order.customerNote  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
250

order.customerOrderDate  Date = OPTIONAL

Data must comply with ISO 8601 extended date format, yyyy-mm-dd.
Existence
OPTIONAL
Fixed value
Validation Rules
Data must comply with ISO 8601 extended date format, yyyy-mm-dd
JSON type
String

order.customerReference  ASCII Text = OPTIONAL

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
OPTIONAL
Fixed value
Validation Rules
Data consists of ASCII characters
JSON type
String
minimum length
0
maximum length
25

order.description  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
127

order.discount   = OPTIONAL

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

order.discount.amount  Decimal = OPTIONAL

Existence
OPTIONAL
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.discount.code  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
40

order.discount.description  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
127

order.expectedNumberOfCaptures  Digits = OPTIONAL

You must provide this value where you want the gateway to automatically reverse the outstanding Authorization amount you do not intend to capture. Note that this requires your merchant profile to be configured accordingly. Contact your payment service provider if you are unsure about your configuration.
The field indicates the total number of Capture requests you intend to submit for an order. For example, if you intend to deliver the goods in two shipments and will capture part of the total authorized amount when you make each shipment, set the value of this field to 2.
If the value equals or drops below the actual number of successful Captures, then the gateway will prevent further Captures and void the outstanding Authorization amount (depending on your merchant profile configuration). If you are unsure of the number of Captures, set the value to 99, and to one on your last Capture.
If you do not provided a value for this field, but had previously provided one, the previous value is applied. For example, if you provide a value 2 on the first Capture for the order and then submit a second Capture without a value, the gateway assumes that the value is still 2.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a number between 1 and 99 represented as a string.
JSON type
String

order.gratuityAmount  Decimal = OPTIONAL

The gratuity amount is included in the total amount of the order you provide in order.amount.
Existence
OPTIONAL
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 = OPTIONAL

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
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
40

order.invoiceNumber  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
25

order.localTaxRegistrationId  String = OPTIONAL

If you are a Canadian merchant, use this field to provide your Tax Registration ID for paying Provincial Sales Tax (PST).
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
25

order.merchantCategoryCode  Digits = OPTIONAL

This is also known as the Merchant Category Code (MCC).
You only need to provide the MCC if you want to override the default value configured for your acquirer link.The value you provide must match one of those configured by your payment service provider.
Existence
OPTIONAL
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.netAmount  Decimal = OPTIONAL

If you specify a net amount the gateway will calculate the surcharge for you. Alternatively, you can specify the surcharge amount (order.surchargeAmount) yourself.
Existence
OPTIONAL
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.notificationUrl  Url = OPTIONAL

To receive notifications at this URL, you must enable Webhook notifications in Merchant Administration. Ensure the URL is HTTPS
Existence
OPTIONAL
Fixed value
Validation Rules
Ensure that the URL begins with 'https' and is longer than 11 characters.
JSON type
String

order.owningEntity  String = OPTIONAL

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
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
40

order.purchaseType  Enumeration = OPTIONAL

You must provide a value for purchase type if your Merchant Category Code (MCC) is one of the following:

6051 (Quasi Cash – Merchant or Non-Financial Institutions – Foreign Currency, Non-Fiat Currency) and this transaction is for the purchase of cryptocurrency. Set the value to CRYPTOCURRENCY.

6211 (Securities – Brokers/Dealers) and this transaction is for the purchase of high-risk securities. Set the value to HIGH_RISK_SECURITIES.

6012 (Merchandise and Services—Customer Financial Institutions) or 6051 (Non-Financial Institutions – Foreign Currency, Non-Fiat Currency) and this transaction is for debt repayment. Set the value to DEBT_REPAYMENT.

You may set purchase type to OTHER for any other type of payment.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
CRYPTOCURRENCY
The transaction is for the purchase of a cryptocurrency.
DEBT_REPAYMENT
The transaction is for debt repayment.
HIGH_RISK_SECURITIES
The transaction is for the purchase of high-risk securities.
OTHER
The transaction does not involve the purchase of cryptocurrency, or high-risk securities and is not a debt repayment.

order.reference  String = OPTIONAL

For example, a shopping cart number, an order number, or an invoice number.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
40

order.requestorName  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

order.reward   = OPTIONAL

Information about reward points earned using a card enrolled in a rewards program that are being redeemed as full or part payment for this order.
Fixed value

order.reward.amount  Decimal = OPTIONAL

The reward amount is included in the total amount of the order you provide in order.amount.You must provide this value if the rewards program supports a payer-nominated amount (availableBalance.reward.payerNominatedAmount returned from the Balance Inquiry operation has a value of 'true').
Existence
OPTIONAL
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.reward.balanceId  Alphanumeric + additional characters = OPTIONAL

The presence of this field indicates that rewards are to be redeemed.The gateway will use the details stored against this identifier when authorizing the payment with your acquirer.
Existence
OPTIONAL
Fixed value
Validation Rules
Data may consist of the characters 0-9, a-z, A-Z, '-', '_', ' ', '&', '+', '!', '$', '%', '.', '='
JSON type
String
minimum length
1
maximum length
100

order.shippingAndHandlingAmount  Decimal = OPTIONAL

Existence
OPTIONAL
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   = OPTIONAL

Contact information provided by you for printing on payer's account statements.
Fixed value

order.statementDescriptor.address   = OPTIONAL

Descriptor address of the merchant.
Fixed value

order.statementDescriptor.address.city  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

order.statementDescriptor.address.company  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

order.statementDescriptor.address.country  Upper case alphabetic text = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data must consist of the characters A-Z
JSON type
String
minimum length
3
maximum length
3

order.statementDescriptor.address.postcodeZip  Alphanumeric + additional characters = OPTIONAL

Existence
OPTIONAL
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

order.statementDescriptor.address.stateProvince  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
20

order.statementDescriptor.address.street  String = OPTIONAL

For example, this may be the street name and number, or the Post Office Box details.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

order.statementDescriptor.address.street2  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

order.statementDescriptor.name  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

order.statementDescriptor.phone  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
20

order.subMerchant   = OPTIONAL

These merchants are referred to as your sub-merchants.

The sub-merchant's details you provide may be displayed on the payer's cardholder statement.

Note that your acquirer may require you to register with the card scheme(s) before allowing you to submit sub-merchant details with a transaction.

This data must be on the initial transaction of an order, subsequent transactions with sub-merchant will be rejected.

Note: If you are requesting payer authentication using 3-D Secure Version 2 then you must provide values for order.subMerchant.address.country and order.subMerchant.bankIndustryCode.
Fixed value

order.subMerchant.address   = OPTIONAL

The sub-merchant's address.
Fixed value

order.subMerchant.address.city  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

order.subMerchant.address.company  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

order.subMerchant.address.country  Upper case alphabetic text = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data must consist of the characters A-Z
JSON type
String
minimum length
3
maximum length
3

order.subMerchant.address.postcodeZip  Alphanumeric + additional characters = OPTIONAL

Existence
OPTIONAL
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

order.subMerchant.address.stateProvince  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
20

order.subMerchant.address.stateProvinceCode  String = OPTIONAL

Providing this field might improve your payer experience for 3-D Secure payer authentication.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
3

order.subMerchant.address.street  String = OPTIONAL

For example, this may be the street name and number, or the Post Office Box details.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

order.subMerchant.address.street2  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

order.subMerchant.authentication[n]   = OPTIONAL

For example, using 3-D Secure authentication.
Fixed value

order.subMerchant.authentication[n].3DS2   = OPTIONAL

These details are used to identify the sub-merchant to the card scheme's directory server.
Fixed value

order.subMerchant.authentication[n].3DS2.requestorId  String = OPTIONAL

Do not provide this value for Mastercard SecureCode or Verified by Visa. For these authentication schemes, it will be generated by the gateway.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
35

order.subMerchant.authentication[n].3DS2.requestorName  String = OPTIONAL

Do not provide this value for Mastercard SecureCode or Verified by Visa. For these authentication schemes, it will be generated by the gateway.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
40

order.subMerchant.authentication[n].protocol  Enumeration = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
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 = OPTIONAL

You must provide a value if you want the gateway to perform 3-D Secure Version 2 authentication of the payer.
Existence
OPTIONAL
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 = OPTIONAL

Existence
OPTIONAL
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 = OPTIONAL

You can use this identifier in searches and reports in the gateway.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

order.subMerchant.phone  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
20

order.subMerchant.registeredName  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

order.subMerchant.tradingName  String = OPTIONAL

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
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

order.subMerchant.websiteUrl  Url = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Ensure that the URL begins with 'https' and is longer than 11 characters.
JSON type
String

order.supply   = OPTIONAL

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

order.supply.preorder  Boolean = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
JSON boolean values 'true' or 'false'.
JSON type
Boolean

order.supply.preorderAvailabilityDate  Date = OPTIONAL

Provide this field if the payer is ordering items before you have them available for purchase.
Existence
OPTIONAL
Fixed value
Validation Rules
Data must comply with ISO 8601 extended date format, yyyy-mm-dd
JSON type
String

order.supply.reorder  Boolean = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
JSON boolean values 'true' or 'false'.
JSON type
Boolean

order.surchargeAmount  Decimal = OPTIONAL

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
OPTIONAL
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.tax[n]   = OPTIONAL

Allows you to provide a breakdown of the types of taxes and amount per type of tax included in order.taxAmount.
Fixed value

order.tax[n].amount  Decimal = OPTIONAL

Existence
OPTIONAL
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.tax[n].rate  Decimal = OPTIONAL

Existence
OPTIONAL
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

order.tax[n].type  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

order.taxAmount  Decimal = OPTIONAL

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 data may be used to qualify for better interchange rates on corporate purchase card transactions.

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

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
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
30

order.taxStatus  Enumeration = OPTIONAL

Existence
OPTIONAL
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   = OPTIONAL

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

The default value is NOT_A_TRANSFER.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
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 = OPTIONAL

The default value is order.amount
Existence
OPTIONAL
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 = OPTIONAL

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

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

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
3
maximum length
3

order.walletProvider  Enumeration = OPTIONAL

Provide this value when you process payments for:
  • • Device payment methods such as Apple Pay, Android Pay, Samsung Pay, or Google Pay.
  • • Digital wallets such as Masterpass, Visa Checkout or Amex Express Checkout.
Existence
OPTIONAL
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 = OPTIONAL

If your payment service provider has not provided you with a solution ID, you should ignore this field.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
40

paymentPlan   = OPTIONAL

Payment Plan is a payment option available to cardholders who wish to repay the purchase amount in a number of monthly installments with or without a deferral period.
Fixed value

paymentPlan.numberOfDeferrals  Digits = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data is a number between 0 and 99 represented as a string.
JSON type
String

paymentPlan.numberOfPayments  Digits = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data is a number between 1 and 99 represented as a string.
JSON type
String

paymentPlan.planId  String = OPTIONAL

See Payment Plans for the supported payment plans and their identifiers.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
40

paymentType  Enumeration = OPTIONAL

Existence
OPTIONAL
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
PBBA
POLI
SEPA
SOFORT
UNION_PAY
WECHAT_PAY

responseControls   = OPTIONAL

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

responseControls.sensitiveData  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

risk   = OPTIONAL

Information relevant to risk assessment.
Fixed value

risk.bypassMerchantRiskRules  Enumeration = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
ALL

risk.custom  String = OPTIONAL

This field is only relevant if you use a third-party risk assessment provider, and you have agreed with them the values to provide (maximum 100 characters in a field name from the set A-Z, a-z, 0-9, maximum 4kB in length of values across all custom risk fields). An example might be:
Field: risk.custom.headOfficeLocation
Value: London UK
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
4000

risk.paymentRecipient   = OPTIONAL

Your acquirer may require you to provide these details if you are a financial institution (Merchant Category Code 6012) submitting a transaction for a person paying off outstanding debts. Otherwise, do not provide these data elements.
Fixed value

risk.paymentRecipient.accountIdentifier  String = OPTIONAL

For payments into a card account provide the card number. For payments into other accounts (for example a bank account) provide the account number. The value provided will be returned masked in the response.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

risk.paymentRecipient.dateOfBirth  Date = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data must comply with ISO 8601 extended date format, yyyy-mm-dd
JSON type
String

risk.paymentRecipient.lastName  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

risk.paymentRecipient.postcodeZip  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
10

session.version  ASCII Text = OPTIONAL

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

To use optimistic locking, record session.version when you make your decisions, and then pass that value in session.version when you submit your request operation to the gateway.

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

See Making Business Decisions Based on Session Content.
Existence
OPTIONAL
Fixed value
Validation Rules
Data consists of ASCII characters
JSON type
String
minimum length
10
maximum length
10

shipping   = OPTIONAL

Shipping information for this order.
Fixed value

shipping.address   = OPTIONAL

The address to which this order will be shipped.
Fixed value

shipping.address.city  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

shipping.address.company  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

shipping.address.country  Upper case alphabetic text = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data must consist of the characters A-Z
JSON type
String
minimum length
3
maximum length
3

shipping.address.postcodeZip  Alphanumeric + additional characters = OPTIONAL

Existence
OPTIONAL
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

shipping.address.sameAsBilling  Enumeration = OPTIONAL

Provide this value if you are not providing the full shipping and billing addresses, but you can affirm that they are the same or different.

The default value for this field is:

SAME - if the shipping and billing address are supplied, and all fields are the same (ignoring non-alphanumerics).
DIFFERENT - if the shipping and billing address are supplied, and at least one field is different (ignoring non-alphanumerics).
UNKNOWN - either shipping address or billing address is absent.
Existence
OPTIONAL
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.address.source  Enumeration = OPTIONAL

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

shipping.address.stateProvince  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
20

shipping.address.stateProvinceCode  String = OPTIONAL

Providing this field might improve your payer experience for 3-D Secure payer authentication.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
3

shipping.address.street  String = OPTIONAL

For example, this may be the street name and number, or the Post Office Box details.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

shipping.address.street2  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

shipping.contact   = OPTIONAL

Details of the contact person at the address the goods will be shipped to.
Fixed value

shipping.contact.email  Email = OPTIONAL

The field format restriction ensures that the email address is longer than 3 characters and adheres to a generous subset of valid RFC 2822 email addresses.
Existence
OPTIONAL
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

shipping.contact.firstName  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

shipping.contact.lastName  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

shipping.contact.mobilePhone  Telephone Number = OPTIONAL

Existence
OPTIONAL
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 = OPTIONAL

Existence
OPTIONAL
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 = OPTIONAL

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

Existence
OPTIONAL
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 = OPTIONAL

Existence
OPTIONAL
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   = OPTIONAL

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

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

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

  • 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
OPTIONAL
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 = OPTIONAL

Retrieve this information from the payer.
Existence
OPTIONAL
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 = OPTIONAL

Retrieve this information from the payer.
Existence
OPTIONAL
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 = OPTIONAL

Also known as:
  • Routing number,
  • Transit number, or
  • ABA number

Retrieve this information from the payer.

See also http://en.wikipedia.org/wiki/Routing_transit_number.

Existence
OPTIONAL
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 = OPTIONAL

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

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

sourceOfFunds.provided.alipay.payerCode  String = OPTIONAL

It is generated by the Alipay wallet app on the payer's mobile device.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
255

sourceOfFunds.provided.boletoBancario   = OPTIONAL

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.actionType  Enumeration = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
WRITE_OFF
Write off the Boleto.

sourceOfFunds.provided.boletoBancario.bankAccountHolder  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
255

sourceOfFunds.provided.boletoBancario.customerType  Enumeration = OPTIONAL

If the value is not provided it will be defaulted to INDIVIDUAL.
Existence
OPTIONAL
Fixed value
Validation Rules
JSON type
String
Value must be a member of the following list. The values are case sensitive.
COMPANY
Customer is an organization.
INDIVIDUAL
Customer is an individual.

sourceOfFunds.provided.boletoBancario.daysBeforeAction  Digits = OPTIONAL

Existence
OPTIONAL
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.boletoBancario.dueDate  Date = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data must comply with ISO 8601 extended date format, yyyy-mm-dd
JSON type
String

sourceOfFunds.provided.card   = OPTIONAL

Details as shown on the card.
Fixed value

sourceOfFunds.provided.card.accountType  Enumeration = OPTIONAL

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

Use this parameter group when you have sourced payment details using:
  • • Device payment methods such as Apple Pay, Android Pay, Samsung Pay, or Google Pay.
  • • Digital wallets such as Masterpass, Visa Checkout or Amex Express Checkout.
  • • Card scheme tokens. This applies when you have tokenized the payer's card number using a card scheme tokenization service such as Mastercard Digital Enablement Service (MDES).
Fixed value

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

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

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

Existence
OPTIONAL
Fixed value
Validation Rules
Data is Base64 encoded
JSON type
String
minimum length
1
maximum length
128

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

Existence
OPTIONAL
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 = OPTIONAL

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
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
16384

sourceOfFunds.provided.card.emvRequest  String = OPTIONAL

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
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
250

sourceOfFunds.provided.card.expiry   = OPTIONAL

Expiry date, as shown on the card.
Fixed value

sourceOfFunds.provided.card.expiry.month  Digits = OPTIONAL

Months are numbered January=1, through to December=12.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a number between 1 and 12 represented as a string.
JSON type
String

sourceOfFunds.provided.card.expiry.year  Digits = OPTIONAL

The Common Era year is 2000 plus this value.
Existence
OPTIONAL
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.maskedFpan  Masked digits = OPTIONAL

You should use this value for display on confirmation or receipt pages presented to the payer.

RequestNormally you do not need to populate this field, as the gateway will populate this field in the session, and populate it into the payment request when you submit the payment using the session. You would only provide this value, if you had access to FPAN information that was not available to the gateway. On responses, the gateway populates it with a form that the payer would recognize (also explained in more detail below).

Retrieve session response

The gateway always populates this field with its best understanding of the masked FPAN.If you are showing PAN data from the session to the payer, then use this field rather than sourceOfFunds.provided.card.number from the session. This is because this field contains a PAN that the payer will recognize whereas sourceOfFunds.provided.card.number could contain a scheme token, or device PAN which the payer will not recognize. After the payment is processed, the gateway will populate the sourceOfFunds.provided.card.number in the payment response with its best understanding of the masked FPAN. You can show this value to the payer after the payment is complete. This logic also applies to the maskedFpanExpiry field.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9, plus 'x' for masking
JSON type
String
minimum length
9
maximum length
19

sourceOfFunds.provided.card.maskedFpanExpiry   = OPTIONAL

Expiry date, The expiry date of the Funding Primary Account Number (FPAN) in sourceOfFunds.provided.card.maskedFpan.
Fixed value

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

Months are numbered January=1, through to December=12.
Existence
OPTIONAL
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 = OPTIONAL

The Common Era year is 2000 plus this value.
Existence
OPTIONAL
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   = OPTIONAL

Use this parameter group when accepting payments from mobile wallet providers such as Apple Pay, Android Pay or Samsung Pay.
Fixed value

sourceOfFunds.provided.card.mobileWallet.3DSecure   = OPTIONAL

Cryptogram data for mobile wallet payments provided in 3DSecure format.
Fixed value

sourceOfFunds.provided.card.mobileWallet.3DSecure.eciIndicator  Digits = OPTIONAL

It indicates the level of security and authentication of the transaction.
Existence
OPTIONAL
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.mobileWallet.3DSecure.onlinePaymentCryptogram  Base64 = OPTIONAL

This will be in Base64 format for MasterCard and Visa transactions and binary format for American Express transactions.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is Base64 encoded
JSON type
String
minimum length
1
maximum length
128

sourceOfFunds.provided.card.mobileWallet.cryptogramFormat  Enumeration = OPTIONAL

You must provide the cryptogram format when you decrypt the payment token and provide the payment details (including the online payment cryptogram) in the transaction request.
Existence
OPTIONAL
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.nameOnCard  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
256

sourceOfFunds.provided.card.number  Digits = OPTIONAL

Existence
OPTIONAL
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.card.provided.card.p2pe   = OPTIONAL

This holds the PAN in the case where it is encrypted by the terminal using DUKPT key exchange.
Fixed value

sourceOfFunds.provided.card.provided.card.p2pe.cardBin  Digits = OPTIONAL

If you provide this, the gateway will check that the decrypted PAN has these leading six digits. If the check fails, the gateway will reject the transaction.

If you do not provided this, the gateway will not perform this check.
Existence
OPTIONAL
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.card.provided.card.p2pe.encryptionState  String = OPTIONAL

INVALID means the terminal detected some form of error in the encryption process. The gateway will decline transactions with INVALID encryption state. This field may be omitted when the value is VALID.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
5
maximum length
7

sourceOfFunds.provided.card.provided.card.p2pe.initializationVector  Hex = OPTIONAL

Omit this value if the terminal is not using an initialization vector to seed encryption.
Existence
OPTIONAL
Fixed value
Validation Rules
Data is hexadecimal encoded
JSON type
String
minimum length
16
maximum length
16

sourceOfFunds.provided.card.provided.card.p2pe.keySerialNumber  Hex = OPTIONAL

Existence
OPTIONAL
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 = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data is hexadecimal encoded
JSON type
String
minimum length
32
maximum length
1024

sourceOfFunds.provided.card.provided.card.prefix  Digits = OPTIONAL

Existence
OPTIONAL
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 = OPTIONAL

Existence
OPTIONAL
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 = OPTIONAL

This field corresponds to EMV tag 5F34
Existence
OPTIONAL
Fixed value
Validation Rules
Data is a number between 0 and 999 represented as a string.
JSON type
String

sourceOfFunds.provided.card.storedOnFile  Enumeration = OPTIONAL

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

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

Existence
OPTIONAL
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 = OPTIONAL

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

Existence
OPTIONAL
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 = OPTIONAL

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

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

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
255

sourceOfFunds.provided.giftCard   = OPTIONAL

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

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
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
4
maximum length
50

sourceOfFunds.provided.giftCard.number  Digits = OPTIONAL

Existence
OPTIONAL
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 = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
JSON type
String
minimum length
4
maximum length
8

sourceOfFunds.provided.giropay   = OPTIONAL

Additional information required by the gateway to initiate a giropay browser payment.
Fixed value

sourceOfFunds.provided.giropay.bankIdentifier  Digits = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data is a string that consists of the characters 0-9.
JSON type
String
minimum length
8
maximum length
8

sourceOfFunds.provided.giropay.bic  Alphanumeric = OPTIONAL

Existence
OPTIONAL
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.ideal   = OPTIONAL

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

sourceOfFunds.provided.ideal.bic  Alphanumeric = OPTIONAL

Existence
OPTIONAL
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.openBankingBankTransfer   = OPTIONAL

Additional details related to Open Banking Bank Transfer.
Fixed value

sourceOfFunds.provided.openBankingBankTransfer.aspspId  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
256

sourceOfFunds.provided.oxxo   = OPTIONAL

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

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
255

sourceOfFunds.provided.oxxo.dueDate  Date = OPTIONAL

Do not provide a due date for USD currency transactions.
Existence
OPTIONAL
Fixed value
Validation Rules
Data must comply with ISO 8601 extended date format, yyyy-mm-dd
JSON type
String

sourceOfFunds.provided.paypal   = OPTIONAL

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.accountEmail  Email = OPTIONAL

Existence
OPTIONAL
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

sourceOfFunds.provided.paypal.accountHolder  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
255

sourceOfFunds.provided.paypal.billingAgreement   = OPTIONAL

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

Existence
OPTIONAL
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 = OPTIONAL

This description is displayed to the payer when they are asked to approve the billing agreement.
Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
255

sourceOfFunds.provided.paypal.billingAgreement.id  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
100

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

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
255

sourceOfFunds.provided.paypal.payerId  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
13

sourceOfFunds.provided.pbba   = OPTIONAL

Additional details related to Pay by Bank app payment.
Fixed value

sourceOfFunds.provided.pbba.returnUrl  Url = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Ensure that the URL begins with 'https' and is longer than 11 characters.
JSON type
String

sourceOfFunds.provided.poli   = OPTIONAL

Additional details related to a POLi browser payment.
Fixed value

sourceOfFunds.provided.poli.bankAccountHolder  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
255

sourceOfFunds.provided.sepa   = OPTIONAL

Details about the payer's bank account used for a payment made using SEPA
Fixed value

sourceOfFunds.provided.sepa.bankAccountHolder  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
3
maximum length
100

sourceOfFunds.provided.sepa.bic  Alphanumeric = OPTIONAL

Existence
OPTIONAL
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.sepa.iban  String = OPTIONAL

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
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

sourceOfFunds.provided.sofort   = OPTIONAL

The format of the bank account details differs per country.
Fixed value

sourceOfFunds.provided.sofort.bic  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
50

sourceOfFunds.provided.weChatPay   = OPTIONAL

Additional details related to a WeChat Pay browser payment.
Fixed value

sourceOfFunds.provided.weChatPay.accountHolder  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
255

sourceOfFunds.schemeTokenProvisioningIdentifier  ASCII Text = OPTIONAL

Using the identifier provided by the issuer, the gateway will retrieve the scheme token details from the token service provider and store them against the gateway token.

When providing this field, you must not provide card details in the sourceOfFunds.provided.card parameter group, and you must set the sourceOfFunds.type field to CARD.

Existence
OPTIONAL
Fixed value
Validation Rules
Data consists of ASCII characters
JSON type
String
minimum length
1
maximum length
64

sourceOfFunds.token  Alphanumeric = OPTIONAL

Existence
OPTIONAL
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

sourceOfFunds.tokenRequestorID  Alphanumeric = OPTIONAL

This field is mandatory for payments where the Chase Pay wallet was used.
Existence
OPTIONAL
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 = OPTIONAL

If you are passing card data (in any form) on the API, then you need to set this value, and also provide the card details in the sourceOfFunds.provided.card group. In the case of digital wallets or device payment methods, you must also populate the order.walletProvider field.

If you are making a payment with a gateway token, then you can leave this field unset, and only populate the sourceOfFunds.token field. However you can set this to CARD if you want to overwrite or augment the token data with a card security code, expiry date, or cardholder name.
Existence
OPTIONAL
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 payments that obtained the card details either directly from the card, or from a POS terminal, or from a wallet, or through a device payment method.
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.
MERCADO_PAGO_CHECKOUT
The payer selected the payment method Mercado Pago Checkout.
OPEN_BANKING_BANK_TRANSFER
The payer selected the payment method Open Banking Bank Transfer.
OXXO
The payer selected the payment method OXXO.
PAYPAL
The payer selected the payment method PayPal.
PBBA
The payer selected the payment method Pay by Bank app
POLI
The payer selected the payment method POLi.
SCHEME_TOKEN
Use this value for payments using scheme tokens provided by Mastercard Digital Enablement Service (MDES), or Visa Token Service (VTS), or American Express Token Service (AETS).
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   = OPTIONAL

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 a value for field order.merchantCategoryCode

Fixed value

subgatewayMerchant.acquirer[n]   = OPTIONAL

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

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

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

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

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
24

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

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

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
24

subgatewayMerchant.acquirer[n].3DS1.verifiedByVisa   = OPTIONAL

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

subgatewayMerchant.acquirer[n].3DS1.verifiedByVisa.cardAcceptorId  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
15

subgatewayMerchant.acquirer[n].3DS1.verifiedByVisa.cardAcceptorTerminalId  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
1
maximum length
8

subgatewayMerchant.acquirer[n].acquirerMerchantId  String = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data can consist of any characters
JSON type
String
minimum length
0
maximum length
40

subgatewayMerchant.acquirer[n].countryCode  Upper case alphabetic text = OPTIONAL

Existence
OPTIONAL
Fixed value
Validation Rules
Data must consist of the characters A-Z
JSON type
String
minimum length
3
maximum length
3

subgatewayMerchant.acquirer[n].fraudRate  Integer = OPTIONAL

Existence
OPTIONAL
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
99999

subgatewayMerchant.acquirer[n].id</