# Payment Transaction Record ## What is Payment Transaction Record? **Payment Transaction Record** allows a PMS to retrieve reservation payment transaction data. These transactions represent payments made against a reservation using SiteMinder Pay, which facilitates secure payment processing for booking channels and direct bookings through the SiteMinder Platform. Each payment transaction includes specific details related to the payment and its corresponding reservation. As multiple payments can be processed at different stages of a reservation's lifecycle, these transactions should be treated as a single entity within the PMS. {% hint style="warning" %} To implement **Payment Transaction Record**, the PMS must certify for [Reservations PUSH](https://developer.siteminder.com/siteminder-apis/pms-rms/introduction/pmsxchange/api-reference/reservations/reservations-push) or [Reservations PULL](https://developer.siteminder.com/siteminder-apis/pms-rms/introduction/pmsxchange/api-reference/reservations/reservations-pull). {% endhint %} To successfully process Payment Transaction Record, your PMS must handle the following reservation identifiers from the Reservations PUSH or PULL messages: * The `SiteMinder Reservation ID` (`UniqueID Type="14"`). * The `Payment Context ID` (`HotelReservationIDResID_Type="34"`), which serves as the master record for all payments linked to a SiteMinder reservation. {% code title="Where to find the Reservation ID and Payment Context ID in a reservation received from SiteMinder:" expandable="true" %} ```xml ``` {% endcode %} ## Integration Requirements Understand the essential requirements for API integration, including connectivity, authentication, message formats, and security protocols.

Category	Requirement
Web Service Endpoint	SiteMinder will provide a single global endpoint for all hotels for PMS to send pull requests `SM_HotelResPaymentReadRQ` and receive payment data responses `SM_HotelResPaymentReadRS`. Test Environment Endpoint: https://tpi-pmsx.preprod.siteminderlabs.com/webservices/{RequestorID}
Authentication	SiteMinder will provide a single username/password for all hotels (PMS Level authentication). PMS must include authentication credentials within the SOAP Security header of each request (`SM_HotelResPaymentReadRQ` and `SM_HotelResPaymentResultRQ`).
Message Structure	All messages must adhere to the SOAP message format. OTA message must be encapsulated within the SOAP Body. Requests must include a SOAP Security Header for authentication. Responses will be returned in a SOAP envelope with empty SOAP Header.
Content-Type	`text/xml; charset=utf-8`
Version	`SOAP 1.1`
Protocol & Security	All communication must occur over HTTPS using TLS 1.2 or higher. Non-secure (HTTP) connections are not permitted. Communication is synchronous request/response pairs. Each message is atomic - processed entirely or not at all.

## Message Exchange Flow 1. **Pull Request (PMS to SiteMinder):** `SM_HotelResPaymentReadRQ`\ Requests undelivered payment transactions for a specific hotel from SiteMinder. 2. **Payment Data Response (SiteMinder to PMS):** `SM_HotelResPaymentReadRS`\ Delivers a list of undelivered payment transactions (reserves, charges or refunds) including both card-based and alternative payment methods. 3. **Confirmation Request (PMS to SiteMinder):** `SM_HotelResPaymentResultRQ`\ Confirms successful storage and processing of payment transactions, or reports processing failures with specific error codes. 4. **Receipt Response (SiteMinder to PMS):** `SM_HotelResPaymentResultRS`\ Acknowledges the confirmation and marks transactions as delivered (successfully or with errors), removing them from future undelivered pulls. ## Security Header The Security Header is a mandatory SOAP header that authenticates every request from your PMS to SiteMinder endpoint. It contains the username and password credentials that we provide to the PMS during integration setup. **Key Requirements:** * **Validation**: Our endpoint will validate these credentials on every request. * **Scope**: One set of credentials is used for all properties in your integration. * **Security**: Credentials are transmitted as plain text within the HTTPS encrypted channel. * **Response**: Invalid credentials will return a SOAP fault with appropriate error code. {% hint style="info" %} The only acceptable value for the **Password @Type** attribute is *.* Plain text passwords are acceptable as all communication is done over encrypted HTTP (HTTPS). {% endhint %} {% tabs %} {% tab title="Pull Request" %} Requests must include a SOAP Security Header for authentication. {% code expandable="true" %} ```xml

USERNAME PASSWORD

``` {% endcode %} {% endtab %} {% tab title="Payment Data Response" %} Responses must be returned in a SOAP envelope with an empty SOAP Header. ```xml

``` {% endtab %} {% tab title="Confirmation Request" %} Requests must include a SOAP Security Header for authentication. ```xml

USERNAME PASSWORD

``` {% endtab %} {% tab title="Receipt Response" %} Responses must be returned in a SOAP envelope with an empty SOAP Header. ```xml

``` {% endtab %} {% endtabs %} ## Multiplicity In the SOAP Specification tables **M** refers to the number of instances or occurrences of an element or attribute that are allowed or required in a given context. It defines how many times a particular component (element or attribute) can appear within a specific structure.

M	Definition
1	The element or attribute must be present exactly once.
0..1	The element or attribute is optional; it can be present zero or one time.
0..n	The element or attribute can be present zero or more times, with no upper limit (where n represents an infinite number of occurrences).
1..n	The element or attribute must be present at least once and can be present any number of times, with no upper limit.
n..m	Specific range, the element or attribute must be present at least n times and no more than m times (where n and m are specific numbers).

## **1. Pull Request** The PMS uses `SM_HotelResPaymentReadRQ` to pull undelivered payment transactions from SiteMinder at regular intervals between 2-5 minutes. The request frequency must be no more than every 2 minutes (e.g. not every 1 minute) and no less than every 5 minutes (e.g. not every 6 minutes). {% tabs %} {% tab title="PMS Level" %} Returns all undelivered payment transactions for all hotels associated with PMS code: `{PMSCODE}` **Requirements:** PMS Level authentication. {% code expandable="true" %} ```xml ``` {% endcode %} {% endtab %} {% tab title="Hotel Level" %} Returns all undelivered payment transactions for a specific hotel with code: `{HOTELCODE}` **Requirements:** Either PMS Level or Hotel Level authentication. {% code expandable="true" %} ```xml ``` {% endcode %} {% endtab %} {% endtabs %}

Element / @Attribute	Type	M	Description
`SM_HotelResPaymentReadRQ`	Element	1	Root element for the request.
`@xmlns`	String	1	Defines the XML namespace for the request. Will be set to `http://www.opentravel.org/OTA/2003/05`
`@EchoToken`	String	1	Unique identifier for the request, used to match requests and responses. Preferred format: UUID `8-4-4-4-12`.
`@TimeStamp`	DateTime	1	Time when the request was generated. `TimeStamp` must use `ISO 8601` format.
`@Version`	Decimal	1	Specifies the API version. Must be set to `1.0`.
`POS/Source/RequestorID`	Element	1	Identifies the system which is sending the request. Container for the PMS code.
`@Type`	Integer	1	Fixed at `22` (ESRP)
`@ID`	String	1	PMS Code assigned by SiteMinder. Remains the same throughout the messages.
`SelectionCriteria`	Element	1
`@HotelCode`	String	0..1	Hotel code as recognised by SiteMinder.
`@SelectionType`	String	1	Must be `Undelivered`

## 2. Payment Data Response SiteMinder returns `SM_HotelResPaymentReadRS` with undelivered payment transactions. The PMS must push these payment transactions to a queue or event stream for offline processing. **Transaction Types Returned:** * **Reserve**: This indicates that a hold for the indicated amount has been placed on a credit card or that a cash amount has been taken from the customer to guarantee final payment. * **Charge**: This indicates that an actual payment has been made. * **Refund**: This indicates that the payment amount of this `PaymentInfo` element is for a refund. {% tabs %} {% tab title="Card Based Payment Response" %} {% code expandable="true" %} ```xml ``` {% endcode %} {% endtab %} {% tab title="Non Card Based Payment Response" %} {% code expandable="true" %} ```xml ``` {% endcode %} {% endtab %} {% tab title="Empty Payment Response" %} ```xml ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="PMS does not exist" %} Returned when the PMS Code provided in the endpoint is incorrect. ```xml Authentication failed - PMS does not exist ``` {% endtab %} {% tab title="Invalid username/password" %} Returned when username and/or password are incorrect. ```xml Authentication failed - PMS received request with invalid username/password ``` {% endtab %} {% tab title="Inconsistent PMS codes" %} Returned when PMS Code provided in the endpoint and `RequestorID` `ID` are not the same. ```xml Inconsistent PMS codes. PMS “PMSCODE” does not match RequestorID “PMSCODEX”. ``` {% endtab %} {% tab title="Incorrect HotelCode" %} Returned when `HotelCode` provided is not assigned to any property. ```xml PMS is not authorized to access hotel with HotelCode=HOTELCODEX ``` {% endtab %} {% endtabs %}

Element / @Attribute	Type	M	Description
`SM_HotelResPaymentReadRS`	Element	1	Root element for the request.
`@xmlns`	String	1	Defines the XML namespace for the request. Will be set to `http://www.opentravel.org/OTA/2003/05`
`@EchoToken`	String	1	Unique identifier for the request, used to match requests and responses. Preferred format: UUID `8-4-4-4-12`.
`@TimeStamp`	DateTime	1	Time when the response was generated. `TimeStamp` must use `ISO 8601` format.
`@Version`	Decimal	1	Specifies the API version. Must be set to `1.0`
`HotelResPaymentList`	Element	1	List of `HotelResPayments`.
`HotelResPayment`	Element	0..n	HotelResPayment data
`@HotelCode`	String	1	Hotel code as recognised by SiteMinder.
`@TransactionID`	String	1	Transaction Identifier.
`@CreateDateTime`	DateTime	1	Transaction Create timestamp. `CreateDateTime` must follow the `ISO 8601` Date and Time format.
`UniqueID`	Element	2
`@ID`	String	1	Reservation Identifier.
`@Type`	Integer	1	`14` - Reservation ID `34` - Payment Context ID
`PaymentInfo`	Element	1
`@PaymentTransactionTypeCode`	Enumeration	1	`reserve` `charge` `refund`
`@PaymentType`	Integer	1	Identifies the payment type: `5` - Credit Card `6` - Debit Card `46` - Online Payment
`@Remark`	String	0..1	Card Based: Open Notes/Remarks. Non-Card Based: Will include the payment provider used.
`@PaymentRef`	String	0..1	Payment reference (e.g. Paypal reference).
`@ChargeTypeCode`	Enumeration	1	RM = Room FD = Food/Beverage OT = Other EX = Stay Extras
`PaymentCard`	Element	0..1	Card Based Payment.
`@CardCode`	String	1	2-character code of the credit card issuer. Refer to Payment Card Provider Codes.
`@CardType`	String	1	OTA Card Type `1` - Credit `2` - Debit
`@ExpireDate`	String	1	Expiry date of the credit card (format `MMyy`).
`@Mask`	String	1	Masked CC number.
`@CardHolderName`	String	1	Name of card holder.
`PaymentAmount`	Element	1	Payment Amount container.
`@Amount`	Decimal	1	Transaction amount.
`@CurrencyCode`	String	1	Use `ISO 4217` currency codes.
`@Due`	Decimal	0..1	Amount outstanding.
`Errors`	Element	0..1	Present if unsuccessfully processed.
`Error`	Element	1	Mandatory if Error present. Text must contain a human readable description of the error.
`@Code`	String	1	Any code from Error Codes (ERR)
`@Type`	String	1	Any type from Error Warning Types (EWT)

## 3. Confirmation Request The PMS sends `SM_HotelResPaymentResultRQ` to confirms successful storage and processing of payment transactions, or reports processing failures with specific error codes. #### Unique IDs To link payments to reservations, an additional ID is now required: * `UniqueID Type=“14”` (SiteMinder Reservation ID) remains unchanged and continues to identify the individual reservation reference (e.g., `ABC-1234567890`). * `UniqueID Type=“34”` (Payment Context ID) that identifies the reservation as a whole (not just a message). If a reservation is split across multiple messages, each message will carry the same `Type=“34”` `ID`. **Grouping Transactions** `SM_HotelResPaymentReadRS` can return multiple payment transactions at once. However: * Each `SM_HotelResPaymentResultRQ` must include either `` or ``, never both. * If some payments succeed and others fail, you must: * Send one request with `Success` + IDs of successful transactions. * Send another request with `Errors` + IDs of failed transactions. {% tabs %} {% tab title="Success" %} ```xml ``` {% endtab %} {% tab title="Error" %} ```xml Booking reference not found ``` {% endtab %} {% endtabs %}

Element / @Attribute	Type	M	Description
`SM_HotelResPaymentResultRQ`	Element	1	Root element for the request.
`@xmlns`	String	1	Defines the XML namespace for the request. Will be set to `http://www.opentravel.org/OTA/2003/05`
`@EchoToken`	String	1	Unique identifier for the request, used to match requests and responses. Preferred format: UUID `8-4-4-4-12`.
`@TimeStamp`	DateTime	1	Time when the request was generated. `TimeStamp` must use `ISO 8601` format.
`@Version`	Decimal	1	Specifies the API version. Must be set to `1.0`.
`HotelResPaymentResult`	Element	0..n
`@HotelCode`	String	1	Hotel code as recognised by SiteMinder.
`@TransactionID`		1	Transaction Identifier.
`UniqueID`	Element	2..3
`@ID`	String	1	Identifier.
`@Type`	String	1	`14` - Reservation ID `34` - Payment Context ID `40` - Delivery Confirmation ID (no returned if `Error`)
`Success`	Element	0..1	Present if successfully stored and processed
`Errors`	Element	0..1	Present if unsuccessfully processed.
`Error`	Element	1	Mandatory if Error present. Text must contain a human readable description of the error.
`@Code`	String	1	Any code from Error Codes (ERR)
`@Type`	String	1	Any type from Error Warning Types (EWT)

## 4. **Receipt Response** SiteMinder returns `SM_HotelResPaymentResultRS` with a `Success` message and will internally mark the payment transaction as either successfully delivered or delivered with an error. In both scenarios, the transaction will not be included in future requests for undelivered payment transactions. {% tabs %} {% tab title="Success" %} ```xml ``` {% endtab %} {% tab title="Unable to update payment" %} Error returned when `TransactionID` in the `SM_HotelResPaymentReadRS` is not found in our system. ```xml

SOAP-ENV:Server Unable to update payment message status

``` {% endtab %} {% endtabs %}

Element / @Attribute	Type	M	Description
`SM_HotelResPaymentResultRS`	Element	1	Root element for the request.
`@EchoToken`	String	1	Unique identifier for the request, used to match requests and responses. Preferred format: UUID `8-4-4-4-12`.
`@TimeStamp`	DateTime	1	Time when the response was generated. `TimeStamp` must use `ISO 8601` format.
`@Version`	Decimal	1	Specifies the API version. Must be set to `1.0`.
`Success`	Element	0..1	Present if successfully stored and processed
`Errors`	Element	0..1	Present If unsuccessfully processed
`Error`	Element	1	Mandatory if Error present. Text can contain a human readable description of the error
`@Code`	String	1	Any code from Error Codes (ERR)
`@Type`	String	1	Any type from Error Warning Types (EWT)

## Common Questions

How often should I pull payment transactions?

Pull undelivered transactions every 2-5 minutes. * Minimum frequency: Every 2 minutes (not faster) * Maximum frequency: Every 5 minutes (not slower) This ensures timely payment processing without overloading the system.

Can I query for transactions for all properties at the same time?

Yes, if using PMS-level authentication. Omit the `HotelCode` parameter in `SM_HotelResPaymentReadRQ` to retrieve all undelivered transactions across all properties associated with your PMS code. For hotel-level authentication, you must query each property separately by including the `HotelCode`.

Can I query for transactions for a specific reservation?

No. You can only pull all undelivered transactions per PMS (all hotels) or per hotel. Use `SM_HotelResPaymentReadRQ` with `SelectionType="Undelivered"` to retrieve all pending transactions, then filter by reservation ID (Type="14" or Type="34") in your PMS.

Where does the value in UniqueID Type="40" come from?

The PMS creates this value when confirming successful payment processing. Type="40" (Delivery Confirmation ID) only appears in the `SM_HotelResPaymentResultRQ` message after your PMS successfully stores and processes a payment transaction.

What happens when I don't acknowledge a transaction?

You have 4 attempts to pull and acknowledge a transaction. After the 4th attempt, SiteMinder marks the delivery as failed. Your PMS should be able to pull and process multiple pending transactions in each `SM_HotelResPaymentReadRQ` request.

Do I need to acknowledge successful AND failed transactions?

Yes. Send separate acknowledgments for successful and failed transactions. * **Success**: Send `SM_HotelResPaymentResultRQ` with `` + successful transaction IDs * **Failure**: Send `SM_HotelResPaymentResultRQ` with `` + failed transaction IDs Each acknowledgment must contain only `` OR ``, never both.

What happens to transactions when a reservation is cancelled?

You may receive additional transactions after cancellation. Properties can create charges (for cancellation fees) or refunds (for deposit returns) via SiteMinder Pay even after a reservation is cancelled. Your PMS should continue pulling and processing all pending transactions regardless of reservation status.

Would refunds always cover the entire amount, or are partial refunds possible?

Partial refunds are possible. Properties can enter any refund amount through SiteMinder Pay, so your PMS should handle both full and partial refund transactions.

{% hint style="success" icon="sparkles" %} ## Still have questions? Use the **Ask** button at the top of the page to chat with our AI assistant — it can help you navigate the guide, understand requirements, and troubleshoot issues. If you need more support, visit [Integration Support](/integration-support/integration-support.md). {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developer.siteminder.com/pmsxchange-api/reference/payment-transaction-record.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.