The Payment Service API (PaymentRQ) is used to perform various payment-related functions.
What is it?
The PaymentRQ API is a web-based credit card authorization service which is available for Travel agency customers to consume. PaymentRQ includes support for authorization with 3D-Secure eCommerce authentication results, which is commonly used by Online Travel Agencies but any Travel Agency with an Online consumer website that supports 3DS may submit authentication data in PaymentRQ.
Why use it?
The PaymentRQ API allows an Online Travel Agency to submit a payment authorization request which includes 3D-Secure authentication results obtained under the agency’s own merchant agreement. Sabre will then output the same 3D-Secure results to ARC or BSP for settlement. As the payment ecosystem evolves, there is a growing need for stronger customer authentication for eCommerce transactions to mitigate fraud. Passing 3DS authentication results helps to reduce the Agencies exposure to Agent Debit Memo’s (ADM) for fraud as including the authentication result provides a liability shift for the airline merchant in most instances.
How does it work?
When a PaymentRQ request is submitted, Sabre's Payment Gateway (SEPG) transforms the request according to the applicable card vendor's specifications/requirements and forwards the request to the card vendor for processing. The vendor, along with the credit card issuer will either Authorize or Decline the transaction, and return the response to SEPG. If the transaction is Authorized/Approved, the Travel agency customer uses the Approval code as returned in the PaymentRS to issue documents in the Sabre GDS. 3D-Secure data which is passed in the PaymentRQ-Auth, will also be included in the Offline settlement files to ARC/BSP to complete the payment flow.
How do I use it?
All web services provided by the Payment Gateway are part of the Sabre Web Services (SWS) framework, which is why any applications that use it should be in compliance with SWS. The credentials of every web service user must have a PaymentUser attribute.
Request Structure
The following table provides detailed descriptions of all elements and attributes included in the request structure:
Element |
Attribute |
Description |
PaymentRQ | The request root element. | |
Action |
This is for the credit card authorization requests and it also includes those are set with 3D-Secure authentication results. Set this field to Auth. |
|
POS |
|
The element contains all parameters related to point of sales information. |
CityCode |
(Optional) The three alpha city code. Example: DFW for Dallas |
|
PseudoCityCode (PCC) |
An alphanumeric identifier for a travel agency of a Global Distribution System (GDS) such as Sabre. Used to designate agency access exclusively to Sabre APIs. Example: B3Q6 |
|
StationNumber |
The IATA (International Air Transport Association) number as it appears in the TJR (Travel Journal Record). Example: 11111111 |
|
AgencyName |
The travel agency name as it appears in the TJR. |
|
ISOCountry |
The agency country code as designated in the agency's TJR. Example: US |
|
AgentSine |
Also known as an Agent ID, it is required for Sabre. Example: ABC |
|
AgentDutyCode |
An authorized code assigned to a requestor, which is required for Sabre Virtual payment transactions. |
|
LNIATA |
(Optional) An agent code set defined on Sabre Host. Example: 457A2A |
|
ChannelID |
Set this field to AGY. |
|
SourceID |
Set this field to OTA.
|
|
IP_Address |
(Optional) Where the transaction originated from. Example: 10.135.114.169 |
|
LocalDateTime |
The local date and time in YYYY-MM-DDThh:mm: ss format. Example: 2017-10-05T12:35:09 |
|
BrowserDetail |
(Optional) An element applicable to web transactions only. |
|
HttpHeaders |
(Optional) This element is used for new implementations. |
|
HttpHeader |
The HTTP header is a value in the name-value pair and is repeated for each header data. |
|
Name |
The name of the header. |
|
POS_Address | The address information of the agency as it appears in the agency's TJR. | |
CityName |
The travel agency's full city name as it appears in TJR. Example: Dublin |
|
PostalCode | Describes the travel agency's zip or postal code, if applicable. | |
StateProv | Contains state and province information. | |
StateCode |
The state code of the travel agency. Example: WA |
|
CountryCode |
The 2 alpha country code of the travel agency. Example: US |
|
MerchantDetail |
Contains all information related to the merchant. |
|
MerchantID |
GDS prime host used for the transaction. Example: 1S, 1F, 1B |
|
MerchantName |
The full name of the validating carrier. Example: American Airlines |
|
OrderDetail | Contains all information related to the order. | |
OrderID |
(Optional) Identifier of the order for tracking purposes. Example: AAABBB111017 |
|
OrderType |
(Optional) The type of order : OI – Original Issuance (default) EA – Exchange with Additional Collection |
|
RecordLocator |
PNR Record Locator if available, or ABCDEF if PNR has not yet been created. Example: ABCDEF |
|
ValidatingCarrierCode |
The 2-alphanumeric IATA validation carrier airline code. Example: AA |
|
ValidatingCarrierNbr |
(Optional) The 3-digit numeric airline designator. Example: 001 |
|
OneWayInd |
(Optional) Indicates whether the booking is a one-way trip or not. |
|
ProductDetail | Contains product details. All fields are required if applicable. | |
ProductID |
The product’s unique identifier. Example: Air Ticket - 0001 EMD - 1004 Travel agency service fee - 2000 |
|
PassengerDetail |
(Optional) This element contains all information related to the passenger. All the fields are required if applicable, and the element can be repeated up to 99 times. |
|
NameInPNR |
(Optional) Passenger name as it is displayed in the PNR. Example: SMITH/JOHN |
|
NameNumberInPNR |
(Optional) The Name number which is directly taken from the PNR. Example: NameNumberInPNR is 1.1 as shown below: RECORD LOCATOR REQUESTED 1.1TRAVELER/JOHNNY |
|
FirstName |
(Optional) Passenger's first name. |
|
LastName |
(Optional) Passenger's last name. |
|
PassengerType |
(Optional) Determines whether the passenger is an adult or child. Example: ADT, CHD |
|
FlightDetail |
(Optional) Contains the detail of the flight. This element is required if the itinerary is present. |
|
AirlineCode |
The 2-alpha IATA airline code. Example: AA |
|
FlightNumber |
The 1 to 4 digit flight number. For flight segments that are OPEN or ARNK, this field can be ignored. Example: 1 |
|
ClassOfService |
The 1 alpha class of service. i.e the booking level which an agent sells. Example: 1 AM 286Y 11OCT F MEXGDL HK1 105P 225P /DCAM /E F stands for the Class Of Service. |
|
DepartureInfo |
The information related to the flight's departure. |
|
DepartureAirport |
The 3-alpha IATA city code of the departure airport. |
|
DepartureDateTime |
Departure date and time in YYYY-MM-DDThh:mm: ss format. Example: 2017-10-05T12:35:09 |
|
CurrentLocalDateTime |
Current local date/time of the departure city. This data is needed to calculate the hours/days before departure, which is required by some merchants to effectively screen for fraud. If the current local date/time is Nov 6, 2017, 8:15 am, the value expected in this field is: 2017-11-06T08:15:00 Note to Sabre apps: This value can be obtained from Sabre Host via “T*city” command, where the city is the 3 alpha city code. |
|
FareBasisCode |
(Optional) It is taken from the price quote and it is used as a fraud tool for messaging American Express CAPN. |
|
ArrivalInfo |
(Optional) It is an element of 1-alpha class of service. |
|
ArrivalAirport | The 3-alpha IATA city code of the departure airport. | |
ArrivalDateTime |
Arrival airport date and time in YYYY-MM-DDThh:mm: ss format. Example: 2017-10-05T12:35:09 |
|
PaymentDetail | This element contains different forms of payment. | |
Type |
At present, the OTA should always set it as CC for Credit card. |
|
PaymentCard | The details of the payment card. | |
CardCode |
The 2-character card code. See Appendix A.2 for a list of applicable Card codes. |
|
CardNumber |
The 16 or less digit Card account number. Note: Although 16 digits are common, this value can be less. |
|
ExpireDate | Payment card expiration date in MMYYYY format. | |
ExtendPayment | Extended payment -and the number of instalments, if applicable. | |
CardSecurityCode |
(Optional) Different codes are used based on the card types as shown below:
|
|
T3DS_Ind |
(Optional) Set to true to populate the 3D Secure transaction details in the <T3DS> element. |
|
<T3DS> |
(Optional) If T3DS_Ind is set to true, this element is required. |
|
CAVV |
CAVV token from 3D Secure Authentication. The token string must be the exact same string as returned by the 3DS MPI and NOT to be converted to any other form. Cardholder Authentication Verification Value is included in the authorization request and it is recognized by the card issuer from the previous 3D-secure authentication attempt. Example: jPxDi6b55rKoABEAAAAgjUxc1OE= |
|
ECI |
ECI value from 3D Secure Authentication. Electronic Commerce Indicator (a value which is returned to the merchant, via their Merchant plug-in, which indicates the result of the 3D-secure authentication attempt.) Example: “05” “06” “07” for Visa, Amex “00”, “01”, “02” for MasterCard |
|
XID | Transaction ID returned from the 3DS MPI. | |
DirectoryServerTrxID |
Supported for 3D Secure 2. The unique transaction identifier assigned by the Directory Server to identify a single transaction. |
|
Version | Set to ‘2.0’ if 3D Secure is a 2.0 transaction. Set to ‘1’ if 3D Secure is a 1.0 transaction. | |
CardHolderName |
(Optional) Contains the name of the cardholder. |
|
Name | Cardholder’s full name (as appears on the card). | |
FirstName | Cardholder’s first name. | |
LastName | Cardholder’s last name. | |
Address |
(Optional) Contains address information. |
|
AddressLine1 | Street number and name. | |
AddressLine2 | Any further added information w.r.t Address Line 1. | |
CityName | Full name of the city | |
PostalCode | Zip or Postal Code number. | |
StateProv | State or Province name if applicable. | |
StateCode | The 2 letter state, or province code if applicable. | |
Country | (Optional) | |
Code | The 2 alpha country code. | |
EmailAddress |
(Optional) The email address of the cardholder. Example: TEST@OTA.COM |
|
AmountDetail | The details of the total transaction amount. | |
Amount |
Total amount to be authorized. The amount should include minor units based on Sabre currency decimal. Example: 250.50 for a currency with a minor unit of 2. |
|
CurrencyCode |
The 3-alpha currency code. Example: USD |
Response Structure
The PaymentRS API contains different types of result or response codes depending on what was included in the request message as listed below:
Element |
Attribute |
Description |
PaymentRS | It is a root element which describes the responses related to payment. | |
SystemDateTime |
(Optional) The creation date and time of the message in YYYY-MM-DDThh:mm:ss format. Example: 2017-10-05T12:35:09 |
|
SabreTransactionID | The Transaction ID generated for the particular request. | |
Version | It indicates the version of the schema. | |
Result | It is an element which describes the results of the request. | |
ResultCode |
A code indicating the result of the request. A Result Code of SUCCESS does not necessarily mean that the card issuer approved the auth request. It indicates that the request was successfully sent to the supplier and a response was received. |
|
Description |
(Optional) Short description of the result code. |
|
AuthorizationResult |
(Optional) This is an element which describes the results of authorization. In case a valid response is received from a supplier it should be present. |
|
ResponseCode |
Authorization response code can be one of the following values: APPROVED DECLINED ERROR |
|
Description |
(Optional) Short description of the response code as returned by a supplier. |
|
ApprovalCode |
(Optional) Approval code used for ticketing, as returned by a supplier. |
|
SupplierTransID |
(Optional) Transaction Identifier returned by a supplier. |
|
SupplierResponseCode |
(Optional) Response code as returned by a supplier. |
|
PaymentRef | System generated reference number for this payment request (This reference can be used to cancel the payment). | |
AuthRemarks1 |
(Optional) Auth Remarks to be added to the PNR. |
|
AuthRemarks2 |
(Optional) Auth Remarks to be added to the PNR. |
|
CSC_Result |
(Optional) This is a root element. It is all about card security code verification results. |
|
CSC_ResultCode |
(Optional) Card security code result code as returned from the vendor. |
|
CSC_Remarks |
(Optional) CSC Remarks to be added to the PNR. |
|
AVS_Result |
(Optional) It is an element which is all about AVS results. |
|
AVS_ResultCode |
(Optional) Address Verification result code as returned from the vendor |
|
AVS_Remarks |
(Optional) AVS Remarks to be added to the PNR. |
|
AdditionalRemarks |
(Optional) List of additional remarks that may be returned depending on the FOP. |
|
Remark |
An additional Remark containing 3DS authentication result. Example: 3DS/AUTHENTICATION SUCCESSFUL/02 |
Appendix A. Tables
A.1 Result Codes
Code | Explanation |
SUCCESS | Successful transaction. |
PWS-INVALID-ACTION | Action specified is not valid. |
PWS-INVALID-PAYLOAD | Payload is missing required Elements/Attributes or contains invalid data. |
PWS-TRANS-NOT-FOUND | Specified PaymentRef is not found in Payment database. |
PWS-SYSTEM-ERR | Payment Service System Error. |
PWS-SYSTEM-EX | Payment Service Internal System Exception. |
PWS-ERR-TIMEOUT | SSG/MOM timeout. |
PWS-SUP-SECURITY_ERR | Merchant accounts invalid or not configured on the supplier side. |
PWS-SUP-TIMEOUT | Supplier timeout. |
PWS-SUP-DN | Supplier system is down. |
PLAUSIBILITY-ERR | Any plausibility check error such as invalid card BIN range, check digit, length. |
SSG-ERR | All SSG errors |
A.2 FOP Card Codes
FOP Type | FOP/Card Code | Description |
CC | AX | American Express |
CC | CA | Master Card |
CC | DC | Diners Club |
CC | DS | Discover |
CC | JB | JCB |
CC | TP | UATP |
CC | VI | Visa |
A.3 Testing in Lower Environments
The TSTS/INT and CERT environment supports testing, it is to be noted that the test cards which are provided to you by the merchant plug-in (to 3D-Secure tests) might not be compatible with the card vendors test stimulators.
To assist you with the end tests, Sabre has set up the below cards to return with the Approval and Declined responses. We recommend you to work with MPI to see if the below cards can be configured in the systems so that you can invoke the 3D-Secure authentication authorization for testing.
CardCode | CardNumber | Authorization Outcome |
VI (Visa) | 4111111111111111 | APPROVED |
VI (Visa) | 4005111111111177 | DECLINED |
CA (MasterCard) | 5101080000000074 | APPROVED |
CA (MasterCard) | 5419222222222303 | DECLINED |
AX (American Express) | 372055555555550 | APPROVED |
AX (American Express) | 372022222222220 | DECLINED |
<PaymentRQ xmlns="http://www.opentravel.org/OTA/2003/05/beta" SystemDateTime="2019-10-11T13:58:09" Version="4.17">
<Action>Auth</Action>
<POS CityCode="DFW" PseudoCityCode="AABB" AgencyName="TEST NAME" AgentSine="ABC" AgentDutyCode="*" LNIATA="457A2A" StationNumber="11111111" ISOCountry="US" IP_Address="10.135.114.169" SettlementPlan="ARC" ChannelID="AGY" LocalDateTime="2017-10-11T11:58:00.000" SourceID="OTA">
<POS_Address>
<CityName>BELLEVUE</CityName>
<PostalCode>98005</PostalCode>
<StateProv StateCode="WA"/>
<Country Code="US"/>
</POS_Address>
</POS>
<MerchantDetail MerchantID="1S" MerchantName="AMERICAN AIRLINES"/>
<OrderDetail OrderID=" AAABBB111017" RecordLocator="AAABBB" ValidatingCarrierCode="AA" ValidatingCarrierNbr="001">
<ProductDetail ProductID="0001"/>
<FlightDetail>
<AirlineCode>AA</AirlineCode>
<FlightNumber>1</FlightNumber>
<ClassOfService>S</ClassOfService>
<DepartureInfo DepartureAirport="JFK" DepartureDateTime="2019-12-05T10:49:00" CurrentLocalDateTime="2019-12-04T10:00:05"/>
<ArrivalInfo ArrivalAirport="FLL" ArrivalDateTime="2019-12-05T13:49:00" FinalDestinationInd="true"/>
</FlightDetail>
</OrderDetail>
<PaymentDetail>
<FOP Type="CC"/>
<PaymentCard CardCode="VI" CardNumber="4444########1111" PIN="" CardSecurityCode="123" T3DS_Ind="true" ExpireDate="122019" ExtendPayment="00">
<T3DS CAVV="AAABAIc1YoInY2VCQTViEB/aleQ=" ECI="05" XID="EuComjmcxoAF+JJshUGXz91zMo="/>
<CardHolderName Name="TEST TESTER" FirstName="TEST" LastName="TESTER"/>
<Address>
<AddressLine1>123 MAIN STREET</AddressLine1>
<CityName>EULESS</CityName>
<PostalCode>76040</PostalCode>
<StateProv StateCode="TX"/>
<Country Code="US"/>
</Address>
<EmailAddress>TEST@OTA.COM</EmailAddress>
</PaymentCard>
<AmountDetail Amount="2.00" CurrencyCode="USD"/>
</PaymentDetail>
</PaymentRQ>
<PaymentRS xmlns="http://www.opentravel.org/OTA/2003/05/beta" SystemDateTime="2019-10-11T15:09:10" SabreTransactionID="01311507752550299106" Version="4.17">
<Result ResultCode="SUCCESS" Description="Successful Transaction"/>
<AuthorizationResult ResponseCode="APPROVED" Description="Approved" ApprovalCode="123456" AuthAmountSent="2.00" SupplierID="VISA" SupplierTransID="123456789098765" SupplierResponseCode="00" AuthRemarks1="AUTH-VISA/VI1111/11OCT*3DS//01311507752550299106" AuthRemarks2=" AUTH-APV/123456/00/USD2.00" PaymentConfirmInd="R" PaymentRef="01311507752550299106">
<CSC_Result CSC_Remarks=" AUTH-CSC NOT SUPPLIED/"/>
<AVS_Result AVS_ResultCode="S" AVS_Remarks=" AUTH-ADDRESS VERIFICATION NOT SUPPORTED/S"/>
<AdditionalRemarks>
<Remark>3DS/AUTHENTICATION SUCCESSFUL/05</Remark>
</AdditionalRemarks>
</AuthorizationResult>
</PaymentRS>