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

# Verify Payment

> Verify the status of a payment.

This endpoint allows you to check the status of a payment using the `payment_id` returned by the Generate Payment endpoint.
In this endpoint, it is crucial to ensure that the "success" field is true before attempting to parse the API's content. Once confirmed, the payload will reveal the precise status of the transaction at the time of the API call. The transaction status can be one of the following:

* **SUCCESS**: This indicates that the transaction has been confirmed and the payment was successful.
* **PENDING**: The session is still active, and a payment can still be confirmed.
* **EXPIRED**: The session has expired, and no payment is expected.
* **FAILURE**: The payment has failed, and details regarding the failure, including the reason, are accessible via the API.

To confirm a payment, it is essential to verify that the "success" field is true and the status is "SUCCESS". It is advisable to invoke this function upon receiving a success or failure webhook to confirm the transaction's status. However, it is important to avoid making multiple successive calls (pings) to prevent rate limiting and potential IP bans.

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET 'https://developers.flouci.com/api/v2/verify_payment/{payment_id}' \
    -H 'authorization: Bearer <APP_PUBLIC>:<APP_SECRET>' \
  ```
</RequestExample>

### Path Parameters

<ParamField path="payment_id" type="string" required>
  The ID of the payment to verify.
</ParamField>

<ResponseExample>
  ```json Success theme={null}
  {
      "success": true,
      "result": {
          "type": "wallet",
          "amount": 1250,
          "status": "SUCCESS",
          "details": {
              "order_number": "Pb3pNSdyRRWOBdXHDTEdBw",
              "name": "FOULEN BEN FOULEN",
              "approval_code": "182848",
              "phone_number": "",
              "email": "",
              "destination": []
          },
          "developer_tracking_id": "your_internal_tracking_id",
          "settlement_status": "AVAILABLE"
      },
      "status_code": 200,
      "name": "developers",
      "code": 0,
      "version": "2.0.0"
  }
  ```

  ```json Error theme={null}
  {
    "result": {
      "status": 404,
      "message": "Payment not found"
    }
  }
  ```
</ResponseExample>

### Response Fields

<ResponseField name="type" type="string" required>
  Payment method used. One of `card`, `wallet` (Flouci wallet), `mpayment` (mobile switch), or `NA`.
</ResponseField>

<ResponseField name="amount" type="integer" required>
  Amount paid in millimes.
</ResponseField>

<ResponseField name="status" type="string" required>
  Payment status: `SUCCESS`, `PENDING`, `EXPIRED`, `FAILURE`, `PREAUTH_SUCCESS`, or `SYSTEM_FAILURE`.
</ResponseField>

<ResponseField name="details" type="object">
  Buyer information. Shape depends on the payment `type`.
</ResponseField>

<ResponseField name="developer_tracking_id" type="string">
  Your merchant-supplied reference passed at payment creation. May be `null`.
</ResponseField>

<ResponseField name="settlement_status" type="string" required>
  Where this transaction sits in the settlement lifecycle. See [Settlement Status](#settlement-status) below. One of `PROCESSING`, `AVAILABLE`, `IN_PAYOUT`, `PAID`, or `NOT_APPLICABLE`.
</ResponseField>

***

## Settlement Status

Every transaction returned by the Verify endpoint carries a `settlement_status` field describing where the funds sit between the moment of payment and the moment they reach your bank account.

<Info>
  `settlement_status` is **independent** of `status`. A `SUCCESS` payment can still be `PROCESSING` (settling), `AVAILABLE` (in your balance), `IN_PAYOUT` (committed to a payout), or `PAID` (wired to your bank). Existing fields are unchanged — clients that ignore `settlement_status` see no behavior change.
</Info>

### Lifecycle

On the happy path of a card payment, the status moves forward through these stages:

```
PROCESSING → AVAILABLE → IN_PAYOUT → PAID
```

Wallet, mobile-switch, and POS payments skip `PROCESSING` and land directly in `AVAILABLE` on success — they never enter the card payout pipeline.

### The five values

| Value            | Meaning                                                                                                                                                              |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PROCESSING`     | Card payment succeeded but is inside the T+1 settlement window (the day-after-midnight cutoff). For POS, also used while a payment authorization is still in flight. |
| `AVAILABLE`      | Eligible for inclusion in the next payout. Reached automatically once a card payment passes T+1, or immediately for wallet, mobile-switch, and POS payments.         |
| `IN_PAYOUT`      | Committed to a payout request that has been initiated, but the bank wire has **not yet been sent**. Brief in-flight window.                                          |
| `PAID`           | Payout wire transfer has been **sent to your bank account**. Terminal state.                                                                                         |
| `NOT_APPLICABLE` | Transaction is outside the settlement lifecycle — failed, expired, refunded, cancelled, pending authorization, or pre-authorized but not finalized.                  |

### Lifecycle by payment type

| Payment type                           | Possible values                                                                                                                                                                    |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Online card (`type=card`)              | `PROCESSING` → `AVAILABLE` → `IN_PAYOUT` → `PAID`, plus `NOT_APPLICABLE`                                                                                                           |
| Online wallet (`type=wallet`)          | `AVAILABLE` on success, `NOT_APPLICABLE` on failure. Never `PROCESSING`, `IN_PAYOUT`, or `PAID`.                                                                                   |
| Online mobile switch (`type=mpayment`) | Same as wallet.                                                                                                                                                                    |
| POS                                    | `PROCESSING` (auth pending), `AVAILABLE` (settled into wallet), `NOT_APPLICABLE` (failed / refunded). Never `IN_PAYOUT` or `PAID` — POS doesn't enter the gateway payout pipeline. |

### How to use it

<AccordionGroup>
  <Accordion title="Is this payment in my available balance?">
    Look for `settlement_status == "AVAILABLE"`.
  </Accordion>

  <Accordion title="Will this be on my next payout?">
    Once you request a payout, `AVAILABLE` transactions move to `IN_PAYOUT`, then to `PAID` once the wire is sent.
  </Accordion>

  <Accordion title="Has this hit my bank account?">
    `settlement_status == "PAID"`. This is the terminal state.
  </Accordion>

  <Accordion title="Why isn't this showing up in my balance?">
    Check `status` first — if the payment failed, expired, or is still pending, `settlement_status` will be `NOT_APPLICABLE`. Otherwise it is most likely `PROCESSING` (inside the T+1 window for a card payment).
  </Accordion>
</AccordionGroup>

<Tip>
  For bookkeeping, combine both fields: a transaction is "money that belongs to you" only when `status == "SUCCESS"` **and** `settlement_status` is one of `AVAILABLE`, `IN_PAYOUT`, or `PAID`.
</Tip>