# Resolving Action Required Payments

## Overview

When an incoming bank transfer cannot be automatically matched to an existing order or payment link, the payment enters an "Action Required" state. This guide explains how to identify the type of action required and resolve it.

## Types of Action Required Payments

### Actionable (You Can Resolve These)

These payments show a "Find Matching Payin" button in the top-right corner of the payment details screen.

#### 1. Unmatched Payment (Payin Not Found)

The incoming bank transfer could not be automatically matched to any existing order or payment link. You will see a yellow banner: "Unmatched payment. This incoming bank transfer could not be automatically matched to an existing order or payment link."

![Unmatched payment — Action required screen with Find Matching Payin button](/assets/unmatched-payment.f2f983bf1055f27286a59337294a1b1047c03515fd044ef8326de4ba035834c1.b1ca6591.png)

#### 2. Amount Mismatch

The received amount does not match the original order amount. You will see a yellow banner: "Amount mismatch detected. The received amount does not match the original order amount."

![Amount mismatch — Action required screen](/assets/amount-mismatch.cac121478c096b28f548de54672a60a922b6ab1499302a02b0285f93a687ebc6.b1ca6591.png)

### Non-Actionable (Contact Support)

For all other action required reasons (e.g., additional verification required), you will see a message directing you to contact support@glomopay.com. The "Find Matching Payin" button will not be visible for these cases.

![Non-actionable — Contact support message](/assets/non-actionable-contact-support.25fbcb653ba56eab9daae8a12da5afaa0291ed875e69b3530cbc2300c4d360bc.b1ca6591.png)

## How to Resolve Actionable Payments

### Step 1: Open the Payment Details

Navigate to the payment that is in "Action Required" state. You will see the payment summary, amount, sender details, and the reason for the hold.

### Step 2: Click "Find Matching Payin"

Click the "Find Matching Payin" button in the top-right corner. A dialog will open showing:

- **Left panel** — Incoming payment details: amount, sender name, sender account number, received date, and payment ID.
- **Right panel** — A list of eligible payment links/orders that match the payment amount and currency.


![Match payment to payin dialog showing eligible payins](/assets/match-payment-to-payin-dialog.6241e5046e704ca31fd12862a423f67e4f25627abe37d304a377777e6fe02c65.b1ca6591.png)

### Step 3: Filter Results (If Needed)

If there are many eligible payins, use the filter dropdown and search bar at the top of the dialog to narrow results by:

- **Customer ID** — Filter by exact customer ID
- **Invoice Number** — Filter by invoice number
- **Reference Number** — Filter by reference number


Select the filter type from the dropdown, enter the value, and click Search.

![Filtering eligible payins by invoice number](/assets/filter-eligible-payins.19da0a708a7949122dbea39e6dcd28be0f9ace80023ebbd84e49f67d952c4d6b.b1ca6591.png)

### Step 4: Select a Payin and Review

Choose the correct payment link or order from the list. Each payin card displays the following fields:

- **Payin ID** — The unique identifier for the payment link or order (e.g., `plink_69cb95b0DffDK`).
- **Amount & Currency** — The expected payment amount (e.g., 18.00 USD).
- **Customer Name** — The name of the customer associated with the payin.
- **Email** — The customer's email address.
- **Invoice Number** — The invoice number linked to the payin (e.g., RG12FF590). Displayed if available.
- **Reference Number** — The reference number associated with the payin (e.g., R0001). Displayed if available.
- **Type Badge** — Indicates whether the entry is a Payment link or an Order.


> **Note:** Invoice Number and Reference Number are only shown on the card when they have been provided for that payin. Not all payins will display these fields.


Click "Review Match" to proceed. A review screen will appear showing the payment details and the selected payin side by side. Verify that the details are correct, then click "Confirm Match" to complete the matching.

![Review match screen — Payment and payin details side by side](/assets/review-match-screen.3c1ee3d60b9f9b93c8837423f5a928aab44ec68c52203cdd17005c2e3e312dc7.b1ca6591.png)

## What If No Eligible Payins Are Found?

If the dialog shows "No eligible payment links or orders found", it means there is no active payment link or order with a matching amount for this payment.

![No eligible payment links or orders found](/assets/no-eligible-payins-found.1a0c86a9a48201297b2e28d04ca28ebb6e0e4906534a3f9736238f00b009de8d.b1ca6591.png)

**To resolve this:**

1. Create a new payment link or order with the same amount and currency as the stuck payment.
2. Return to the action required payment.
3. Click "Find Matching Payin" again — the newly created payin will now appear in the eligible list.
4. Select it, review, and confirm the match.


## Resolve an Action Required Payment Over the API

You can also do this matching over the API. Use it to resolve unmatched payments from your own systems, or to build your own matching screen.

The flow has five steps.

> **Note:** A quote expires 30 minutes after you create it. Create the payin (an order or a payment link) from the `quote_id` inside these 30 minutes. The payin expires at the same time as its quote. Steps 2 to 5 must complete inside this window. If the quote expires, cancel the payin and start again from step 2.


### Step 1 - Read the Payment

Call [Retrieve a payment](/api-reference/openapi/payment/getpaymentbyid). A payment that you can resolve this way has these values:

- `status`: `action_required`
- `error_code`: `PAYIN_NOT_FOUND` or `PAYIN_AMOUNT_MISMATCH`
- `payment_method.type`: `bank_transfer`


`payment_amount` and `payment_currency` are the amount and currency that the customer sent. Use both in step 2.

If the `error_code` is a different value, you cannot resolve the payment by matching. Contact support@glomopay.com.

### Step 2 - Create a Quote for the Amount That Arrived

Call [Create a quote](/api-reference/openapi/quote/createquote) with these fields:

| Field | Value |
|  --- | --- |
| `resource` | `payin` |
| `source_amount` | The `payment_amount` of the payment |
| `source_currency` | The `payment_currency` of the payment |
| `destination_currency` | The currency that you want the order in |
| `payment_method.type` | `bank_transfer` |
| `payment_method.subtype` | `local_transfer` or `swift_transfer`, the same as the transfer type of the payment |


The `destination_amount` in the response is the amount of the order.

### Step 3 - Create a Payment Link or an Order

Call [Create a payment link](/api-reference/openapi/payment_link/createpayin) or [Create an order](/api-reference/openapi/orders/createorder) with the `quote_id` from step 2. Do this inside 30 minutes of the creation of the quote. After 30 minutes the quote expires, and you cannot use its `quote_id`.

The amount, the currency and the expiry come from the quote. A customer is necessary.

### Step 4 - List the Eligible Payins

Call [List eligible payins](/api-reference/openapi/payment/geteligiblepayins) on the payment.

A payin is eligible when its amount and currency are equal to `payment_amount` and `payment_currency`. A payin is also eligible when the `source_amount` and `source_currency` of its quote are equal to these values. The payin from step 3 is in this list.

The endpoint returns a maximum of 10 payins, the newest first. To make a long list shorter, use the `customer_id`, `reference_number` and `invoice_number` query parameters. Each one is an exact match.

```json
{
  "payment_id": "payt_6aad0bc0cZtlS",
  "payment_amount": 10000,
  "payment_currency": "AED",
  "eligible_payins": [
    {
      "payin_id": "plink_6aad0ec19b3bT",
      "payin_status": "pending",
      "payin_type": "payment_link",
      "amount": 2723,
      "currency": "USD",
      "customer_id": "cust_69eb2cf0FYSDF",
      "invoice_number": "R0001",
      "reference_number": "RG12FF590",
      "created_at": "2026-09-18T10:38:19.237Z"
    }
  ]
}
```

If `eligible_payins` is empty, no open payin matches the amount. Create one as in steps 2 and 3. Then call this endpoint again.

### Step 5 - Connect the Payin

Call [Connect a payin](/api-reference/openapi/payment/connectpayin) with the `payin_id` that you selected:

```json
{ "payin_id": "plink_6aad0ec19b3bT" }
```

Glomo connects the payin to the payment. Then Glomo processes the bank transfer, which includes screening and fees. The response is the full payment object.

After a successful connect, the payment is `success` and the payin is `success`. The `converted_amount` and `converted_currency` come from the quote of the payin.

The endpoint is idempotent. If you send the same `payin_id` again after a successful connect, the endpoint returns `200` with the same payment. If the payment was `PAYIN_AMOUNT_MISMATCH` and pointed at a pending payin, a different payin replaces that connection.

### Payments That You Cannot Resolve This Way

Both endpoints return `400 Bad Request` when you cannot match the payment:

| Message | Meaning |
|  --- | --- |
| `Payment is not in correct state to link a payin` | The payment is not in the `action_required` state. |
| `Payment already belongs to a payin that is not in pending state` | The payin that the payment points at is no longer pending. |
| `Only applicable for bank transfers` | The `payment_method.type` of the payment is not `bank_transfer`. |
| `The payin to be linked to the given payment is in an invalid state` | The payin is not `pending` and not `partially_paid`. It can be expired or cancelled. |
| The merchant description of the error code | The payment is on a hold, such as `SANCTION_HIT` or `TXM_HOLD`. Contact support for these payments. |