---
schema_version: "1"
id: 7cc4544405fd4828345981036b83203c8dc64c3fd34383923853db97891a3e6a
title: Payment Error Handling
collection: admin
version: current
locale: en-us
portal_url: https://docs.salesforce.com/admin/current/en-us/commerce/264-0-0/rt_adv_config_pay_gate_error_handling.md
canonical_url: https://help.salesforce.com/s/articleView?id=commerce.rt_adv_config_pay_gate_error_handling.htm&release=264.0.0&type=5
source_site: help.salesforce.com
content_type: documentation
content_hash: f8344f5af0ed3d46bc8e9cbd84d422641934504524ec4463a05d99321ae042b6
description: An order failure with unknown payment statuses is critical. Point of Sale made enhancements addressing this issue by adding additional parameters and descriptive order statuses in the CMS reporting. Additionally, there is the abort option in the app's user interface to mark the payment status as unknown in case of communication failures between the app and the terminal. This enables you to verify and reconcile the transaction later depending on the order status in the CMS failed order report.
products:
  - Commerce
release: "264"
---
# Payment Error Handling

An order failure with unknown payment statuses is critical. Point of Sale made enhancements addressing this issue by adding additional parameters and descriptive order statuses in the CMS reporting. Additionally, there is the abort option in the app's user interface to mark the payment status as unknown in case of communication failures between the app and the terminal. This enables you to verify and reconcile the transaction later depending on the order status in the CMS failed order report.

## Set Payment Timeouts

Control the timeout duration for terminal requests so the POS app waits for a payment gateway response. You can also set the duration for API requests so the system waits for a response from the payment status check API. Setting the request duration ensures efficient communication and prevents delays during transactions. Configure the duration to optimize performance and maintain a smooth user experience.

- Modern POS App Build: 8.1.1 or above
- Platform Support: iPhone & iPad
- Offline Support: Limited
- [A configured payment gateway](https://help.salesforce.com/s/articleView?id=commerce.rt_adv_config_pay_gate_config.htm&release=264.0.0&type=5 "Configure payment gateways in Point of Sale CMS to securely process customer payments. By connecting preferred payment providers, you streamline transactions and enhance the customer checkout experience. Accept a variety of payment methods, reduce friction, and improve overall sales efficiency.")

### Set Payment Request Timeout

Set the duration of the terminal requests to control how long the POS app will wait for a response from the payment gateway before timing out. The default duration is set to 150 seconds, and it's recommended not to use extremely low values to avoid potential issues.

1. Go to **Integrations** | **Payment Gateways**.
2. Edit a configuration.
3. Set **Terminal Request Timeout Interval In Seconds** to your desired value.
4. Save your changes.

### Set Payment Status Verification Request Timeout

Set the duration of the API requests to control how long the system will wait for a response from the payment status check API. Negative values are not allowed, and the recommended default value is 5 seconds.

1. Go to **Integrations** | **Payment Gateways**.
2. Edit a configuration.
3. Set **Payment Status Check API Timeout In Seconds** to your desired value.
4. Save your changes.

## Failed Orders Corrective Action

Get details of how to identify various failed order scenarios and address their corrective actions in Point of Sale.

<table class="slds-table slds-table_bordered slds-max-medium-table_stacked slds-m-bottom_small ">
          <colgroup>
            <col style="width:33.33333333333333%">
            <col style="width:33.33333333333333%">
            <col style="width:33.33333333333333%">
          </colgroup>
          <tbody>
            <tr class="">
              <td class="slds-cell-wrap" style="vertical-align:top;">Failure Type</td>

              <td class="slds-cell-wrap" style="vertical-align:top;">
                <p>Likely User Scenario</p>
                <p>/</p>
                <p style="margin-bottom:0;">Probable Cause</p>
              </td>

              <td class="slds-cell-wrap" style="vertical-align:top;">Corrective Actions</td>

            </tr>
            <tr class="">
              <td class="slds-cell-wrap" style="vertical-align:top;">
                <p>Successful Orders without Payments</p>
                <p style="margin-bottom:0;"><em>Order number is available in the terminal console but not in CMS success/failed
                    order reports</em></p>
              </td>

              <td class="slds-cell-wrap" style="vertical-align:top;">Not an expected scenario</td>

              <td class="slds-cell-wrap" style="vertical-align:top;">This is not an expected behavior for the POS app. If this is experienced, contact
                Salesforce Customer Support.</td>

            </tr>
            <tr class="">
              <td class="slds-cell-wrap" style="vertical-align:top;">
                <p>Orders having Aborted payments</p>
                <p style="margin-bottom:0;"><em>Order with payment status UNKNOWN (before 8.1.1) and ABORTED (from 8.1.1) in CMS
                    Failed Order report</em></p>
              </td>

              <td class="slds-cell-wrap" style="vertical-align:top;">
                <ul>
                  <li>Payment gateway timeout</li>

                  <li>Check Wi-Fi connectivity at the store</li>

                  <li>Consult with the payment processor on why the delay in processing occurs</li>

                </ul>
              </td>

              <td class="slds-cell-wrap" style="vertical-align:top;">Merchant should manually refund customers directly from the Payment Gateway tied
                to each individual order.</td>

            </tr>
            <tr class="">
              <td class="slds-cell-wrap" style="vertical-align:top;">
                <p>Orders having Auto-Reverted payments</p>
                <p style="margin-bottom:0;"><em>Order is listed in the payment reversal CMS report</em></p>
              </td>

              <td class="slds-cell-wrap" style="vertical-align:top;">
                <ul>
                  <li>Merchant's API Endpoint errors</li>

                  <li>Check why order processing failed</li>

                  <li>Check Point of Sale's platform on why the scenario occurred</li>

                  <li>Check your merchant's OMS on why order processing failed</li>

                </ul>
              </td>

              <td class="slds-cell-wrap" style="vertical-align:top;">No action needed</td>

            </tr>
            <tr class="">
              <td class="slds-cell-wrap" style="vertical-align:top;">
                <p>Orders Pending Payments</p>
                <p style="margin-bottom:0;"><em>Order is listed in Failed Order report with UNKNOWN (before 8.1.1) and FAILED
                    (from 8.1.1) order status and PENDING payment status</em></p>
              </td>

              <td class="slds-cell-wrap" style="vertical-align:top;">
                <ul>
                  <li>Associate force closed app</li>

                  <li>App crashes</li>

                  <li>Check if there are any Phase 2 API issues in the Point of Sale platform</li>

                </ul>
              </td>

              <td class="slds-cell-wrap" style="vertical-align:top;">
                <ul>
                  <li>The app should not be closed during an ongoing transaction.</li>

                  <li>Crashes or submission failures are not expected behavior and need to be
                    resolved. </li>

                  <li>Make sure to relaunch the app as the app verifies the payment status if it's a
                    card payment and sends the correct status to the platform.</li>

                </ul>
              </td>

            </tr>
            <tr class="">
              <td class="slds-cell-wrap" style="vertical-align:top;">
                <p>Orders having Cancelled Payment</p>
                <p style="margin-bottom:0;"><em>Order is listed in Failed Order report with FAILED order status and CANCELED
                    payment status.</em></p>
              </td>

              <td class="slds-cell-wrap" style="vertical-align:top;">
                <ul>
                  <li>Customer changed their mind</li>

                  <li>Associates are canceling the payments</li>

                  <li>Check if there are any card processing issues.</li>

                </ul>
              </td>

              <td class="slds-cell-wrap" style="vertical-align:top;">No action needed</td>

            </tr>
            <tr class="">
              <td class="slds-cell-wrap" style="vertical-align:top;">
                <p>Orders having Declined Payment</p>
                <p style="margin-bottom:0;"><em>Order is listed in Failed Order report with FAILED order status and DECLINED
                    payment status</em></p>
              </td>

              <td class="slds-cell-wrap" style="vertical-align:top;">
                <ul>
                  <li>Customer credit card declined</li>

                  <li>Bad payment terminal hardware</li>

                  <li>Check why payments are declined by consulting with the payment processor</li>

                </ul>
              </td>

              <td class="slds-cell-wrap" style="vertical-align:top;">No action needed</td>

            </tr>
            <tr class="">
              <td class="slds-cell-wrap" style="vertical-align:top;">
                <p>Orders having Approved Payment but order submission failed</p>
                <p style="margin-bottom:0;"><em>Order is listed in Failed Order report with FAILED order status and APPROVED
                    payment status</em></p>
              </td>

              <td class="slds-cell-wrap" style="vertical-align:top;">
                <ul>
                  <li>Customer's credit card was accepted</li>

                  <li>POS was closed while payment was in progress but payment completed on
                    terminal</li>

                  <li>When the order was synced by the app to Point of Sale's platform the order
                    couldn't be processed by the platform so the payment is reverted.</li>

                </ul>
              </td>

              <td class="slds-cell-wrap" style="vertical-align:top;">No action needed</td>

            </tr>
            <tr class="">
              <td class="slds-cell-wrap" style="vertical-align:top;">
                <p>Orders having UNKNOWN (before 8.1.1) or CANCELLED (from 8.1.1) cash orders</p>
                <p style="margin-bottom:0;"><em>Cash order is listed in Failed Order report with FAILED order status and UNKNOWN
                    (before 8.1.1) or CANCELLED (from 8.1.1) payment status</em></p>
              </td>

              <td class="slds-cell-wrap" style="vertical-align:top;">
                <ul>
                  <li>Associate cancels the cash tender payment by using the cross button in the cash
                    payment interstitial after choosing OPEN DRAWER</li>

                  <li>App doesn’t know if cash was returned to the customer as the payment was
                    canceled after opening the drawer</li>

                </ul>
              </td>

              <td class="slds-cell-wrap" style="vertical-align:top;">
                <ul>
                  <li>
                    <p>No action needed assuming that the cash would be returned to the customer by
                      the associate as order was cancelled</p>
                  </li>

                </ul>
              </td>

            </tr>
            <tr class="">
              <td class="slds-cell-wrap" style="vertical-align:top;">
                <p>Orders having FAILED for In Store Pay By Link or Remote Pay By Link order</p>
                <p style="margin-bottom:0;"><em>Order with FAILED status and FAILED In Store Pay By Link or Remote Pay By Link
                    tender will be in CMS</em></p>
              </td>

              <td class="slds-cell-wrap" style="vertical-align:top;">
                <ul>
                  <li>Click on In Store Pay By Link or Remote Pay By Link tender on Cart screen in the
                    app</li>

                  <li>While generating QR code, if there is a problem generating QR code, you will see
                    payment error with generating payment QR code</li>

                </ul>
              </td>

              <td class="slds-cell-wrap" style="vertical-align:top;">
                <p style="margin-bottom:0;">No action needed</p>
              </td>

            </tr>
            <tr class="">
              <td class="slds-cell-wrap" style="vertical-align:top;">
                <p>Orders having DISCARDED card tender orders</p>
                <p style="margin-bottom:0;"><em>Order with FAILED status and DISCARD card tender will be in CMS</em></p>
              </td>

              <td class="slds-cell-wrap" style="vertical-align:top;">
                <ul>
                  <li>Go to multi tender screen and add a cash value</li>

                  <li>Swipe the cell where cash value is present, you will get an option to delete
                    it</li>

                </ul>
              </td>

              <td class="slds-cell-wrap" style="vertical-align:top;">
                <p style="margin-bottom:0;">No action needed</p>
              </td>

            </tr>
            <tr class="">
              <td class="slds-cell-wrap" style="vertical-align:top;">
                <p>FAILED order having Approved cash tenders </p>
                <p style="margin-bottom:0;"><em>Order with FAILED status and approved cash tender will be in CMS</em></p>
              </td>

              <td class="slds-cell-wrap" style="vertical-align:top;">
                <ul>
                  <li>Click on the cash tile on the cart screen </li>

                  <li>Complete a partial payment and then delete it</li>

                  <li>Reset tender pop-up will be shown</li>

                  <li>If any cash were accepted during this order, then either cash drawer will be
                    opened or QR code camera screen will be shown on the POS to return the cash</li>

                </ul>
              </td>

              <td class="slds-cell-wrap" style="vertical-align:top;">No action needed</td>

            </tr>
            <tr class="">
              <td class="slds-cell-wrap" style="vertical-align:top;">
                <p>PENDING ORDERS with missing order IDs</p>
                <p style="margin-bottom:0;"><em>Orders with a PENDING ORDER status and missing order IDs will be in CMS</em></p>
              </td>

              <td class="slds-cell-wrap" style="vertical-align:top;">Adyen callback URL configured at the parent account level in the Adyen Portal,
                allowing events to be received from all regions</td>

              <td class="slds-cell-wrap" style="vertical-align:top;">Merchant should configure individual region-specific callback URLs for only the
                region-specific Adyen account</td>

            </tr>
          </tbody>
        </table>

## Scenarios That Result in Failed Orders

These scenarios explore cases where the payment can be approved in the terminal but the CMS report can have the order status as FAILED/ UNKNOWN.

### Order Fails After Terminal Payment Approval

A payment can be approved by the terminal and fail in the order submission phase in the Point of Sale platform. In this case, the payment will be reverted by the platform, and the same information will become available in the CMS Payment Reversals report.

![An iPad displays an online shopping cart with a notification that a transaction is not complete.](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/retail/images/rt_adv_config_pay_gate_error_handling_fails_post_term_app.png)

### Payment Request Fails at Terminal

On checkout after selecting card as the mode of payment, the POS app initiates the payment request to the terminal. A communication failure can occur between the POS app and the terminal which would cause the app to not receive any response from the terminal after payment initiation. Payment Request Failures can occur in the following scenarios:

#### Payment Request Timeout

The default timeout value for a payment request is 150 seconds and is configurable in CMS. In the case of a timeout, the response from the terminal wasn’t received by the POS and hence it performs an additional request to the terminal to verify the transaction status of the previously initiated payment. This identifies the success or failure of the payment and submits the same information to the platform so that it can get reported in the CMS.

![Note](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/images/icon_note.png)

Note There is a possibility of a transaction status verification request timeout as well. In this case, the associate can cancel the transaction from the POS app or from the terminal using the "X" button. In case of a cancel request timeout, the user will be able to abort the transaction.

![An iPad screen displays an online retail app with a timed out payment request.](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/retail/images/rt_adv_config_pay_gate_error_fails_at_term_timeout.png)

#### Payment Request Fail Due to Internet Failure

When there is an internet failure after a payment request is initiated, the payment request fails due to network unavailability which disrupts communication between POS and the terminal. The POS app sends a request to the terminal to verify the transaction status of the previously initiated payment. With a network failure, the transaction status request also fails. The associate can cancel the transaction from the POS app or from the terminal using a button. In the case of a cancel request failing, the user will be able to abort the transaction.

The Payment Tender Status for the order will be reported as "ABORTED" in the CMS Failed Orders report as the POS app is unable to know the exact payment status of the order. You will need to manually verify and reconcile the transaction.

![A screenshot of a point of sale app on a tablet.](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/retail/images/rt_adv_config_pay_gate_error_fails_at_term_internet_warn.png)![An application screen displays an abort message.](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/retail/images/rt_adv_config_pay_gate_error_fails_at_term_internet_abort.png)

### Cancel Request Fails During Payment in Progress

After the POS app initiates the payment request to the terminal, while the payment is in progress, the associate can cancel the request using the "X" button. There can be communication failure between the POS app and the terminal causing the app to not receive any cancel response from the terminal. Payment In-Progress with Cancel Request Failures can occur in the following scenarios:

#### Cancel Request Timeout

The default timeout value for cancel requests is 150 seconds and is configurable from CMS. When the cancel request timeouts, the POS app sends a request to the terminal to verify the transaction status of the canceling payment. In the case of a transaction request time out, the user will be able to abort the transaction. In case of an abort, the Payment Tender status is reported as "ABORTED" in the CMS Failed Order reports as the POS app is unable to know the exact payment status of the order. You will need to manually verify and reconcile the transaction.

![A tablet displaying a point of sale system screen.](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/retail/images/rt_adv_config_pay_gate_error_fails_in_process_timeout.png)

#### Cancel Request Fail Due to Internet Failure

When an internet failure occurs after a cancellation request from the POS app, there is no communication between the POS app and the terminal. The POS app will not know the status of the cancel request. The POS app will send a request to the terminal to verify the transaction status of the previously initiated payment. In the case of a transaction request time out/fail due to network failure, the user will be able to abort the transaction.

![A screen displays a fashion item and associated payment options.](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/retail/images/rt_adv_config_pay_gate_error_fails_in_process_internet.png)

### Payment and Order Successful but Missing in CMS

When the payment is approved in the terminal but there are intermittent network failures during communication to the platform, the POS app persists these pending orders locally as failed and syncs them to the platform when the network is online. The associate is shown the failure message and then the cart is voided as we cannot confirm the order. These pending orders will show up in the checkout screen for the subsequent orders and the user can see the details and manually sync them from the pending orders screen. The associate can also see all the pending orders by choosing the pending orders deep link if configured in the Hamburger Menu. Until the orders sync up to the platform, the Payment Tender Statuses for these orders are shown as "PENDING" and Order Status as "UNKNOWN" in CMS Failed Orders report.

![The POS app shows the order failed and cart voided warning.](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/retail/images/rt_adv_config_pay_gate_error_fails_cms_missing_warning.png)

![Note](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/images/icon_note.png)

Note It is possible that the platform received the order request, but the POS did not receive a confirmation response due to network failure. In that case, the order will show up as a successful order in CMS but the POS will persist the order locally as failed. On pending order sync, the order will appear in the failed order report.

### Pending Payment and Unknown Order Status in CMS

When the POS app is force-closed after the payment is initiated, and before the app receives a response from the terminal and communicates it to the platform, the Payment Tender Status remains "PENDING", and the Order Status as "UNKNOWN" in CMS Failed Orders report. These orders will not be listed in the pending orders screen in the POS app.

![Note](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/images/icon_note.png)

Note The app should never be closed during an ongoing payment.

#### Adyen-Specific Scenario

In such scenarios, in the case of Adyen's credit card payment, the associate will not be able to return the money to the customer. Hence, the app will remember these order references, verify the payment status with the terminal, and report the same during the next session to the platform. These pending verification orders are seen in the pending orders screen below:

![The POS app displays details of a failed order from an Ayden's transaction.](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/retail/images/rt_adv_config_pay_gate_error_fails_in_cms_adyen.png)

The payment verification is done during the next successful order placement in the case of 1:1 card reader topology and during the next successful card order for 1:N card reader topology settings. If the payment was successful, then the platform refunds these payments as the app did not show the order confirmation screen for these orders. These orders are modified to have a Payment Tender Status as "APPROVED" and an Order Status as "FAILED" in the Failed Orders report in CMS. If the app is unable to retrieve the status from the terminal, it reports the Payment Tender Status as "ABORTED" and they have to be reviewed and manually refunded to the customer.

#### Verifone-Specific Scenario

In the case of Verifone terminals, if there is a loss of Wi-Fi or an internet failure, attempting to cancel a transaction will prompt an error message: "Transaction Failed: Lost connection to the payment terminal." When the associate voids the cart, they have the option to reset tenders. At this point, any accepted payment tenders will be returned to the customer. This scenario will report the Payment Tender Status as "Canceled," which is different from Adyen terminals, where the Payment Tender Status is reported as "ABORTED".

![The POS app displays an error message indicating the connection has been lost.](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/retail/images/rt_adv_config_pay_gate_error_fails_in_cms_verifone.png)

### Online Payments Restricted During Network Issues

The current app doesn't switch to offline mode when there is an intermittent network failure if a payment is in progress or partially applied for a transaction. The app allows the user to complete the current transaction in the same online mode. As an enhancement in the version 8.0.1 release, the POS app will also now restrict the app of online-only tenders such as GiftCard, Check, Finance, Store Credit, Remote Pay By Link, In Store Pay By Link, Reward Card, Miscellaneous and Loyalty Card when there is an intermittent network failure. The app will be shown an error message and the user will automatically be allowed to use these online-only tenders when the network connectivity issue is resolved.

![The POS app displays the error message ​​​​:This tender cannot be applied at the moment due to an intermittent internet failure”.](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/retail/images/rt_adv_config_pay_gate_error_fails_network.png)

### Online Payment Restrictions During Network Instability

For app builds 9.8.1, Point of Sale introduced handling for scenarios when the POS system is online but operating in Adyen's Store-and-Forward (SAF) mode, and a payment confirmation from Adyen is pending. Now, during return transactions, if the payment status remains unverified, the system will prevent the return from proceeding. Users will be notified with the error message, "Payment is still processing for this order, return can't be initialized".

![The POS app displays the error message “Payment is still in process for this order return can't be initialized.”](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-commerce-retail-264-0-0-production-enus/17d647fb-8988-49fb-9add-c4f4cc79c9e4/retail/images/rt_adv_config_pay_gate_error_fails_network_instability.png)

### Unable to Process Refunds for New Store

If you're unable to process refunds for a newly set-up store and encounter the error:

_"Expected BEGIN\_OBJECT but was STRING at line 1 column 1 path $"_, check your [Adyen configuration](https://help.salesforce.com/s/articleView?id=commerce.rt_cms_hardware_ayden_gateway_info.htm&release=264.0.0&type=5 "You can configure different payment gateways at the store level, such as store-level settlements, reporting, and currency requirements and integrate Adyen into Point of Sale.") in CMS. If there's a configuration marked as Default, check that the Secondary URL Base is correctly configured. An incorrect or missing URL can cause refund requests to fail.

## Known Issues & Restrictions

Discovered known issues and restrictions with the Point of Sale payment error handling.

- Phase 1 error simulation is not supported for return flows as it is only for sales.
- Phase 2 error simulation failed order reports do not update for a failed return flow.
- If the app is closed before receiving a response from the payment terminal, reopening the app will display the pending transaction in the "Pending Verification Pending Orders" section.
    - In a 1:1 configuration, tapping on the order entry will trigger a status verification and sync the order with the backend.
    - In a 1:N configuration, the terminal must be connected in the Device Manager screen before tapping on the order to sync. Otherwise, a "Terminal not connected" error will be displayed, and the sync will not occur.