PayFacto API - v2.0 - Solution : Oracle Opera PMS

PayFacto API - v2.0 - Solution : Oracle Opera PMS

PayFacto API - v2.0 - Solution : Oracle Opera PMS
PayFacto Payments Integration

Connect Oracle Opera Cloud PMS to PayFacto Payments to enable seamless room charge posting, card-present terminal transactions, and card-not-present flows from hotel POS systems including Maitre'D and Veloce. The integration uses the Oracle Hospitality Integration Platform (OHIP) REST API alongside PayFacto's OPI microservice.

Product: Opera PMS   |  Protocol: OHIP REST + OPI XML

What This Integration Enables

🏒

Room Charge Posting

Restaurant, spa, and golf POS systems post charges directly to a guest's Opera Cloud room account in real time. The guest settles at check-out.

πŸ’³

Card-Present Terminal

Card payments are processed through a PayFacto terminal at the POS. A payment token is stored against the reservation for pre-auth, increment, and completion flows.

πŸ“‹

Card-Not-Present

Reservations booked via Opera Cloud or third-party booking systems include card data that is tokenized and used for pre-authorization and billing without a terminal.

1

  System Architecture

The integration connects four systems: the hotel POS workstation, Opera Cloud PMS, the PayFacto OPI microservice (Titan SIP), and the payment terminal. Opera Cloud acts as the central orchestrator β€” it sends API calls to PayFacto, which drives the terminal and communicates with the card acquirer.

Transaction Flow β€” 8 Steps

πŸ’»

Hotel POS

Workstation

1. Request
8. Response + Receipt

⇄
☁

Opera Cloud

PMS / OHIP

2. API Call
7. API Response

⇄
πŸ”’

PayFacto

Titan OPI / SIP

3. Terminal Request
4. Card Data
5. Auth Request
6. Auth Response

⇄
πŸ“³

Terminal

Card Present

Cardholder
interaction

⇄
🏭

Acquirer

Card Network

Authorization
response

StepFromToDescription
1Hotel POSOpera CloudPOS requests a payment or room charge operation (new/update reservation trigger).
2Opera CloudPayFacto (Titan OPI)Opera Cloud sends an API call to PayFacto using the OPI XML protocol, converted to PayFacto format by Titan SIP.
3PayFactoTerminalPayFacto sends a terminal request β€” the terminal prompts the cardholder.
4TerminalPayFactoCardholder taps/inserts card; terminal reads card data and sends it to PayFacto.
5PayFactoAcquirerPayFacto sends an authorization request to the card acquirer.
6AcquirerPayFactoAcquirer responds with approval or decline.
7PayFactoOpera CloudPayFacto returns the API response including auth code and token.
8Opera CloudHotel POSOpera Cloud sends final response with receipt data to the POS workstation.
2

   Transaction Flows

πŸ“³ Card Present Terminal

  1. Opera Cloud receives a New/Update Reservation request from the hotel POS.
  2. Opera sends an OPI XML Get Token request to PayFacto Titan SIP.
  3. Titan SIP converts the OPI XML to PayFacto format and triggers card data collection at the terminal.
  4. Terminal prompts the cardholder and captures the card.
  5. PayFacto submits a card verification request to the processor.
  6. Processor responds; PayFacto returns the result to Titan SIP.
  7. Titan SIP converts the response to OPI XML Token Response format.
  8. Opera Cloud stores the token against the reservation.
  9. Pre-Auth, Increment, and Completion flows commence using the stored token.

πŸ“‹ Card Not Present

  1. New reservation arrives via Opera Cloud or a third-party booking system (OTA, Opera Pay, etc.) with PAN data already collected.
  2. Opera sends an OPI XML Get Token request including PAN data to PayFacto Titan SIP.
  3. Titan SIP converts and sends to Titan Core; Titan Core tokenizes the PAN and submits a card verification.
  4. Processor responds; PayFacto stores the token and returns it to Opera via OPI XML.
  5. Opera stores the token against the reservation β€” no terminal interaction needed.
  6. Pre-Auth is submitted using the stored token (no terminal).
  7. Increment authorization is performed if the stay amount changes.
  8. Sales Completion (final charge) is submitted at checkout using the token.

🍽 Room Charge Posting (Restaurant / Spa / Golf POS)

  1. Guest requests to charge their meal/service to their room at the POS outlet.
  2. POS staff enters the room number or the guest provides their name.
  3. POS calls Opera Cloud getReservations to verify the guest is checked in.
  4. Opera returns reservation details including guest name, folio window, and posting restriction flag.
  5. POS checks the postingRestriction flag β€” if true, do not post charges. Guest staff must resolve the restriction.
  6. If no restriction, POS staff confirms the reservation with the guest.
  7. POS calls Opera Cloud postBillingCharges with the revenue amount, transaction code, folio window, and cashier ID.
  8. Opera responds with HTTP 201. The charge appears on the guest's folio immediately.
  9. Optionally, the POS posts a copy of the check receipt using postGuestCheckDetails.
3

   OHIP API Operations Used

ℹ️

The following Oracle Hospitality Integration Platform (OHIP) REST API operations are used by this integration. All calls are authenticated using OAuth 2.0 tokens with a client ID and client secret.

OperationHTTP MethodEndpointPurpose
getReservationsGET/rsv/v1/hotels/{hotelId}/reservationsLook up a guest reservation by room number, name, or reservation ID before posting charges.
postBillingChargesPOST/csh/v1/hotels/{hotelId}/reservations/{reservationId}/chargesPost revenue charges (food, beverage, spa, golf) to a guest account or paymaster account. Supports multiple sub-amounts in a single call.
postGuestCheckDetailsPOST/csh/v1/hotels/{hotelId}/check/{checkNumber}Transmit a copy of the POS guest check (as base64 image or pre-formatted text) into Opera Cloud so it can be shown to the guest at checkout.

Room lookup β€” query parameters

Query parameterDescription
roomIdLook up by room number. Most common for restaurant POS charge flows.
surnameLook up by guest last name.
reservationIdLook up by Opera reservation ID.
searchType=InHouseFilter to in-house guests only. Always include this to avoid posting to future or past reservations.
⚠️

Always check the postingRestriction flag in the getReservations response before calling postBillingCharges. If postingRestriction: true, the guest has not provided sufficient payment guarantee β€” do not post charges. The API does not enforce this automatically.

4

   Supported Transactions β€” Opera PMS

ℹ️

The following OPI transaction types are supported by the PayFacto–Opera integration. Transactions that require a token can bypass terminal interaction if the token is already stored against the reservation.

OPI CodeTransaction TypeNotes
01Sale / PurchaseFull card-present purchase. Supports terminal card capture or token-based (no terminal interaction if token present).
05Pre-AuthorizationPlaces a hold on the card. Can require terminal card capture or use a stored token. Initiates the Pre-Auth β†’ Increment β†’ Completion flow.
06Top-Up Authorization (Incremental Auth)Increases the pre-authorized amount. Executes in the background when the final completion amount is higher than the original pre-auth. Supports token-based flow.
07Sales CompletionCaptures the final amount against an existing pre-authorization. Supports terminal card capture or stored token.
03RefundIssues a refund. Supports linked refund (with original RRN), token-based, or standalone (β€œnaked”) refund. Used to cancel transaction types 07 and 01.
16Authorization ReleaseVoids a pre-authorization (type 05 only). RRN in the request must match the original pre-auth RRN.
39Void RefundReverses a previously issued refund. Original transaction RRN is required.
04ReversalUsed solely for timeouts between Opera PMS and OPI. If OPI cannot complete a transaction, it sends a reversal to PayFacto. Uses the sequence number of the transaction being reversed.
20Transaction InquiryGenerated automatically by OPI on a timeout to determine the status of a transaction in progress.
10End of DayTriggers settlement. Response contains only a text confirmation (RespText) β€” no totals are returned.
23Get TokenRetrieves a payment token for a card via insert or swipe only (no tap). Used to tokenize a card outside of a financial transaction. Includes a CardValid flag.
25GetToken BulkConverts multiple PANs to tokens in a single request. Used when migrating a merchant from another payment provider to PayFacto.
70Connection Status CheckVerifies connectivity between Opera PMS and PayFacto. Returns 00 for a good connection, 06 for a failed connection.
5

   Transactions Not Supported

❌ Not Supported by PayFacto

  • Manual Authorization (37) β€” PayFacto does not support auth codes sent from POS (Store and Forward)
  • Token Exchange β€” GetPAN (bulk)
  • Update Token (bulk)
  • Gift Card Bulk Requests (activate, redeem, balance)

❌ Not Supported by Opera Cloud

  • Void (08)
  • Gift Card Void (31)
  • Gift Card Cashout (32)
  • Gift card data collection at terminal (Opera PMS only supports gift card data collection at POS, not terminal)

🚫 Out of Scope

  • Simphony POS transaction support
  • DCC (Dynamic Currency Conversion)
  • Quick Chip (US-specific terminal flow)
  • IsOnline message (Cruise only)
  • 3DS2 Fingerprint and Challenge result processing
  • Credit Card Surcharge
  • Donations
  • Loyalty support for Opera
  • Pay by Link (OPI transaction types 56 and 57)

πŸ• Pending Development

  • Top-Up Authorization (06) as a standalone API call β€” currently handled automatically in the background during completion
  • Gift Activate (29) β€” requires DataCandy integration development
  • Pay by Link (56/57) β€” under review against Oracle OPI spec Section 4
  • Ecommerce Pre-Auth (17) and Sale (18) β€” require MID mapping changes and optional 3DS2 support
6

   Onboarding & Setup

πŸ”„ Existing PayFacto Merchant Converting to Opera PMS

  1. Opera creates a Site ID consisting of a Chain ID (PSP value, e.g. PAYF β€” static, already coded in Titan) and a Property/Resort Code (hotel-specific).
  2. Merchant provides their Opera Resort Code and Workstation Number.
  3. Merchant confirms which Opera Workstation maps to which PayFacto terminal (one-to-one mapping).
  4. PayFacto configures the Opera and workstation values in Titan Merchant Back Office.
  5. Refer to the Opera Support and Setup Guide for full Titan configuration instructions.

πŸ₯₯ New PayFacto Merchant with Opera PMS

  1. In the OMR (Onboarding) application under Processing Account Config, select:
    β€” Integration Type: SIP β€” Semi Integrated Payment
    β€” POS Type: Opera PMS
  2. The Resort Code field appears on the application. Merchant provides their Resort Code / Property ID (e.g. HOTE).
  3. On terminal deployment, Workstation IDs are configured in Titan Merchant Back Office.
  4. Refer to the Opera POS and Terminal Deployment Guide for full setup instructions.
ℹ️

The Chain ID (PSP value) is a static value already coded in Titan. Merchants do not need to provide this. The Workstation Number (WSNo) represents a specific POS station and is provided by the merchant during onboarding.

7

   Authentication

ℹ️

The OHIP REST API uses OAuth 2.0. Your integration must obtain a bearer token using a Client ID, Client Secret, and App Key before making any API calls. Tokens expire and must be refreshed.

CredentialDescription
Client IDIdentifies your application. Provided by Oracle/PayFacto during OHIP sandbox onboarding.
Client SecretSecret paired with the Client ID. Used to obtain OAuth tokens. Keep confidential.
App KeyApplication key provided by Oracle. Included as a header on all OHIP API requests.
HostNameThe OHIP base URL for your environment. UAT sandbox: provided during onboarding.
HotelIdThe Opera Cloud property identifier (e.g. SAND01). Used in all endpoint paths.
⚠️

Never expose your Client Secret or App Key in client-side code or public repositories. All OHIP API calls must be made from your server.

8

   API Examples

1. Look up a guest by room number

HTTP β€” getReservations by roomId
GET {{HostName}}/rsv/v1/hotels/{{HotelId}}/reservations?roomId={{RoomId}}&searchType=InHouse
Authorization: Bearer {{oauth_token}}
x-app-key: {{AppKey}}

2. Post a room charge with two sub-amounts (revenue + tax)

JSON β€” postBillingCharges (revenue + tax)
POST {{HostName}}/csh/v1/hotels/{{HotelId}}/reservations/{{ReservationId}}/charges

{
  "criteria": {
    "hotelId": "SAND01",
    "cashierId": 113,
    "reservationId": { "id": "{{ReservationId}}" },
    "charges": [
      {
        "transactionCode": "2010",
        "price": { "amount": 27.33, "currencyCode": "CAD" },
        "postingQuantity": 1,
        "postingReference": "Restaurant Food",
        "postingRemark": "Buffet",
        "checkNumber": "2024011101",
        "folioWindowNo": 1,
        "cashierId": 113
      },
      {
        "transactionCode": "8002",
        "price": { "amount": 2.67, "currencyCode": "CAD" },
        "postingQuantity": 1,
        "postingReference": "Tax 14%",
        "postingRemark": "Food",
        "checkNumber": "2024011101",
        "folioWindowNo": 1,
        "cashierId": 113
      }
    ]
  }
}

3. Post a copy of the POS guest check (preferred: text format)

JSON β€” postGuestCheckDetails (text)
POST {{HostName}}/csh/v1/hotels/{{HotelId}}/check/{{checkNumber}}

{
  "checkDetails": {
    "checkDate": "2026-06-01T14:30:00.000Z",
    "checkText": "TABLE 12\n\nBuffet x1       $27.33\nTax 14%         $ 2.67\n--------------\nTOTAL           $30.00\n\nCHECK #2024011101"
  }
}
9

   Resources & Documentation

πŸ“„

OPI Specification β€” Opera PMS Section 4

Full Oracle Payment Interface specification covering all OPI transaction types, message formats, and field definitions.

πŸ“„

Certificate Requirements

TLS certificate requirements for the OPI connection between Titan SIP and Opera Cloud.

Contact PayFacto Integration team for access

πŸ“„

Opera POS and Terminal Deployment Guide

Step-by-step guide for configuring Workstation IDs and terminal mappings in Titan Merchant Back Office.

Contact PayFacto Integration team for access

🌐

Oracle Hospitality API Documentation

Official Oracle OHIP REST API reference including Postman collections and sandbox setup.

https://docs.oracle.com/cd/F36206_01/doc.193/f35724.pdf

🌐

Oracle Payment Interface β€” Installation and Reference Guide

Oracle's official OPI installation and configuration guide.

https://docs.oracle.com/cd/F36206_01/doc.193/f35724.pdf