# Troubleshoot the app

Learn how to troubleshoot the Stripe app for Oracle Opera.

Use this guide to troubleshoot common issues with the Stripe app for Oracle Opera, including installation failures, payment and 3DS errors, and refund discrepancies.

## Access the app’s logs

To troubleshoot an issue, review the app’s log file, located at `C:\Program Files (x86)\Stripe\OpiMiddleware\data\logs\debug.log` on the machine or server where the app is installed. Open `debug.log` directly, or send it to Stripe support to help diagnose the issue. Oracle can also provide OPI-side logs for the same time window.

If `debug.log` doesn’t contain enough detail, set the `Serilog` **Default** log level to `Verbose` in your `appsettings.json` file and [restart the Windows service](https://docs.stripe.com/use-stripe-apps/oracle/opera/configuration.md#restart-service) to apply the change. See [Configure the app parameters](https://docs.stripe.com/use-stripe-apps/oracle/opera/configuration.md#configure-parameters) for the full list of supported log levels.

> Defer to Oracle for Opera or OPI-specific debugging. Otherwise, try clearing the Opera cache and retrying.

## Installation failure 

If your first installation of the Stripe app for Oracle Opera fails, uninstall the app, remove the cached data, and then reinstall it.

1. Navigate to **Windows Program Management** > **Apps** > **Installed apps**.
2. Uninstall the Stripe Oracle Opera app.
3. Navigate to the installation folder. For example, `C:\Program Files (x86)\Stripe\OpiMiddleware`.
4. Delete the `data` folder.
5. [Re-install](https://docs.stripe.com/use-stripe-apps/oracle/opera/installation.md) the app.

## Verify the connector version

Before you troubleshoot further, confirm you’re running the current version of the app.

1. Go to **Windows Program Management** > **Apps** > **Installed apps**.
2. Find the Stripe Oracle Opera app in the list and check its version number.

If the version is out of date, [install the new version](https://docs.stripe.com/use-stripe-apps/oracle/opera/troubleshooting.md#install-a-new-version).

## Install a new version 

To upgrade to a new version of the app, uninstall the existing version and remove its cached data before you install the new version.

1. Navigate to **Windows Program Management** > **Apps** > **Installed apps**.
2. Uninstall the Stripe Oracle Opera app.
3. Navigate to the installation folder. For example, `C:\Program Files (x86)\Stripe\OpiMiddleware`.
4. Delete the `data` folder.
5. Open the Windows Services app and confirm the **Stripe OPI App Service** isn’t listed to verify a full uninstall.
6. [Install](https://docs.stripe.com/use-stripe-apps/oracle/opera/installation.md) the new version of the app.

## Common issues

| Issue | Resolution |
| --- | --- |
| Reader not found | Check which reader Opera defaults to and clear the cache. Confirm that the Terminal ID in Opera Cloud exactly matches the Workstation ID for the reader in the app’s dashboard. Then, check the app’s logs to confirm the `WSNo`/`WSNum` field in the OPI request matches the Workstation ID configured in the app’s dashboard. |
| Resource missing | This error can mean that the payment method token is from your previous PSP. In Opera, click the information icon next to the payment method token and confirm it begins with `pmu`. A token that doesn’t use the `pmu` prefix belongs to your previous PSP, not Stripe. If the token originates from a booking site, check that your booking site integration [saves Stripe payment method IDs](https://docs.stripe.com/use-stripe-apps/oracle/opera/overview.md#support-online-bookings-with-saved-payment-methods) using the `pmu` prefix. |
| Incomplete payment status | This status can indicate that 3D Secure is being triggered unexpectedly. First, ask Oracle to confirm that your Payment Services Directive setting is configured correctly. If that setting is correct, the issue is likely related to how the app handles mail order or telephone order (MOTO) transactions. Contact [Stripe Support](https://support.stripe.com) for further assistance. |
| Payment declined by PSP (error code `06`) | This decline usually means you’re using a test card that the other party can’t process. Stripe can’t process Oracle’s own test card numbers, and Oracle can’t process Stripe’s test cards. If declines continue during migration testing, use a live card. |
| Issuer or switch inoperative error (error code `01`) | This error means the Terminal reader is unreachable. Confirm the Terminal ID in Opera matches the Workstation ID in the app’s dashboard, then check both the OPI and app logs to confirm the request’s `WSNo`/`WSNum` field maps to the Workstation ID configured in the app’s dashboard. |
| Charge already refunded | This error usually means the refund request referenced the wrong charge. See [Troubleshoot refunds](https://docs.stripe.com/use-stripe-apps/oracle/opera/troubleshooting.md#troubleshoot-refunds). |

## Troubleshoot refunds 

By default, when you refund an amount on a booking, OPI sends Stripe a reference (`AlternateTransRef`) to only the most recent charge, whose amount might be less than the refund you’re requesting. For example, a guest’s booking might have the following charges:

- 2,000 USD for the room, charged during check-in
- 150 USD for parking, charged shortly after check-in
- 25 USD for breakfast, charged the next day
- 15 USD for snacks, charged two days later

If the hotel operator tries to refund the guest 150 USD for parking, OPI sends that refund request to Stripe with a reference to the 15 USD snack charge instead. Stripe rejects this request as an over-refund, because 150 USD exceeds the referenced charge’s balance.

To refund an earlier charge, [configure refunds](https://docs.stripe.com/use-stripe-apps/oracle/opera/configuration.md#configure-refunds) by asking Oracle to disable Rebate Validation Check in Opera Cloud. Consider the following when you process refunds:

- Operators can select an earlier charge. Refunds aren’t limited to the most recent charge on a booking. The app uses `AlternateTransRef` to refund the specific charge selected.
- Process refunds per charge rather than per booking total. If a booking has two separate charges that need refunds, submit one refund against each charge instead of a single refund for the combined amount.
- You can issue multiple partial refunds. Operators can issue multiple partial refunds against the same charge until its refundable balance is exhausted.
- Don’t refund more than the selected charge’s remaining balance. Stripe rejects the request, even if other charges on the same booking have funds available.

Before you go live, test the following scenarios in your property’s environment:

- A full refund against an earlier, non-latest charge
- A partial refund
- A second partial refund against the same charge
- An over-amount refund, which the app should reject

After testing, operators can independently refund any referenced charge, including a non-latest charge, and Stripe continues to enforce the refundable limit of each individual charge.

## Get more help

If you can’t resolve an issue using this guide, gather the relevant logs (see [Access the app’s logs](https://docs.stripe.com/use-stripe-apps/oracle/opera/troubleshooting.md#access-the-apps-logs)) and contact your Stripe account executive or [Stripe Support](https://support.stripe.com). Include the property’s Site ID, the affected PaymentIntent or Charge ID, and a description of the issue to help Stripe investigate.