> ## Documentation Index
> Fetch the complete documentation index at: https://getequity.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Fetch a transaction / verify a payment

> Look up a transaction by the reference we issued, or by its id, and find out whether the payment went through

Answers the question the payment redirect leaves open.

[Fund and invest](/docs/api-reference/endpoint/Members/fund-invest) sends the buyer to Flutterwave and
brings them back to the `redirectUrl` you supplied, with the outcome appended as query
parameters:

```
?status=successful&tx_ref=GETXN_FI_2M094EW4MJSOC5&transaction_id=10459445
?status=cancelled&tx_ref=GETXN_FI_KGBW0Y3O2W2GNN
```

That `status` is the browser's account of the checkout — it is not proof of payment, and it can be
edited by anyone who can edit a URL. Call this endpoint with the `tx_ref` before you render
anything on your return page.

Two different things are reported, because they settle at different times:

| Field             | Means                                                                |
| ----------------- | -------------------------------------------------------------------- |
| `status` / `paid` | whether the payment succeeded **at the provider**                    |
| `settled`         | whether **GetEquity** has received the money and credited the wallet |

A payment is regularly `paid: true, settled: false` for a few seconds: the buyer gets back to your
page before our webhook has run. Show "payment received, investment processing" and poll this
endpoint until `settled` is `true` — do not tell the buyer the payment failed.

`settled: true` means the funding is on the books. On a fund-and-invest the token purchase is
queued at that moment and completes just after, so the units appear on
[Member Token Balance](/docs/api-reference/endpoint/Members/member-token-balance) a beat later than the
wallet credit. If your page confirms the holding rather than the payment, read the balance.

<ParamField path="reference" type="string" required>
  The `tx_ref` returned when the payment was initiated (`GETXN_FI_…`), or the transaction's own id.
</ParamField>

<ParamField query="transaction_id" type="string">
  The `transaction_id` from the redirect, when you have it. Saves a lookup. Pass only the one that
  came back with this `tx_ref` — it is what gets verified, so an id from a different payment
  returns that payment's outcome.
</ParamField>

## Scope

The reference must belong to you — a transaction of your organisation's, or a payment you
initiated for one of your members. Anything else returns `404`, whether or not it exists.

<ResponseExample>
  ```json theme={null}
  {
    "status": "success",
    "message": "Transaction gotten successfully",
    "data": {
      "reference": "GETXN_FI_2M094EW4MJSOC5",
      "status": "successful",
      "paid": true,
      "settled": true,
      "amount": 50000,
      "currency": "NGN",
      "paymentId": 10459445,
      "transaction": {
        "_id": "66a1f0c39d3e4b0012ab34cd",
        "type": "Fund",
        "status": "Completed",
        "user": "6a82ea8c0864460002a5745e",
        "reference": "GETXN_FI_2M094EW4MJSOC5",
        "volume": 50000,
        "currency": "NGN",
        "createdAt": "2026-08-20T10:15:00.000Z"
      },
      "provider": null
    }
  }
  ```
</ResponseExample>

## Paid, not yet settled

`transaction` is `null` and `provider` carries Flutterwave's verification, because our webhook has
not written the funding yet. Poll until `settled` is `true`.

```json theme={null}
{
  "status": "success",
  "message": "Transaction gotten successfully",
  "data": {
    "reference": "GETXN_FI_2M094EW4MJSOC5",
    "status": "successful",
    "paid": true,
    "settled": false,
    "amount": 50000,
    "currency": "NGN",
    "paymentId": 10459445,
    "transaction": null,
    "provider": {
      "status": "successful",
      "amount": 50000,
      "currency": "NGN",
      "transaction_id": 10459445,
      "payment_type": "card",
      "created_at": "2026-08-20T10:14:52.000Z",
      "meta": {
        "type": "fund_invest",
        "userId": "6a82ea8c0864460002a5745e",
        "tokenId": "660018c2f4a1b20011a9e0b1",
        "investmentAmount": 50000
      }
    }
  }
}
```

## Cancelled or abandoned

The buyer came back with `status=cancelled`, and Flutterwave has no record of the reference.

```json theme={null}
{
  "status": "success",
  "message": "Transaction gotten successfully",
  "data": {
    "reference": "GETXN_FI_KGBW0Y3O2W2GNN",
    "status": "not_found",
    "paid": false,
    "settled": false,
    "amount": null,
    "currency": null,
    "paymentId": null,
    "transaction": null,
    "provider": null
  }
}
```

## Status values

| `status`     | `paid`  | Meaning                                                        |
| ------------ | ------- | -------------------------------------------------------------- |
| `successful` | `true`  | The payment went through                                       |
| `pending`    | `false` | The provider has it, no verdict yet                            |
| `failed`     | `false` | The payment was attempted and declined                         |
| `not_found`  | `false` | No payment against this reference — cancelled or never started |

## Error responses

| Status | Error code                         | When                                                             |
| ------ | ---------------------------------- | ---------------------------------------------------------------- |
| 404    | `TRANSACTION_NOT_FOUND_ERROR`      | No transaction or in-flight payment of yours with this reference |
| 400    | `PAYMENT_REFERENCE_REQUIRED_ERROR` | No reference supplied                                            |

<Note>
  A reference for a payment that never reached the provider — a checkout closed before it was
  submitted — stops being resolvable **24 hours** after it was initiated, and returns `404`
  from then on. Anything the provider has a record of, settled or not, stays resolvable.
</Note>