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

# Verify a payment

> Confirm that a payment really succeeded before you deliver an order.

When a customer finishes paying, the widget hands your page a payment **reference**. Treat that as a message that "something happened", not as proof of payment. Before you ship goods or unlock a service, **always confirm the payment with Afara**.

> [!WARNING]
>
> Anyone can run code in their own browser. Never mark an order as paid based only on what the browser tells your page. Confirm with Afara first.

## Three ways to confirm a payment

> [card] 1. Check the dashboard
>
> Open **Transactions** in the [merchant portal](https://merchant.afarapartners.com/login) and search for the reference. This is the easiest option for small shops that handle orders by hand.

> [card] [2. Let Afara notify you (recommended)](https://docs.afarapay.com/payments/webhooks.md)
>
> Afara sends your server a message the moment a payment is completed. This is reliable even if the customer closes their browser before the page finishes loading.

> [card] 3. Ask Afara from your server
>
> Your server asks Afara for the status of a reference, using the steps below.

## Ask Afara for the status of a payment

Call this from your **server**, never from the browser. Use the reference you received from the widget.

```bash theme={null}
curl "https://merchant-service.afarapartners.com/api/v1/merchant/transaction/status/YOUR_REFERENCE" \
  --header "Api-Public-Key: YOUR_PUBLIC_KEY"
```

Look at these fields in the response before you deliver the order:

| Field | What to check |
| - | - |
| `transactionStatus` | Should be `SUCCESS`. |
| `paymentStatus` | Should be `COMPLETED`. A value of `INCOMPLETE_PAYMENT` means the customer paid less than the amount due. |
| `amountInMinor` | Matches the amount you expected, in kobo. |
| `transactionReference` | Matches the reference of the order you are confirming. |
| `transactionMode` | `TEST` for test payments and `LIVE` for real ones. |

> [!NOTE]
>
> **This section is still being verified.** The endpoint and fields above come from the Afara source code. We are confirming the exact request and response against the live system. See the [API Reference](https://docs.afarapay.com/api-reference/introduction.md) for the full draft.

## What the statuses mean

| Status | Meaning |
| - | - |
| `INITIATED` or `PENDING` | The payment has started but the customer has not finished. |
| `IN_PROGRESS` | Afara is processing the payment. |
| `SUCCESS` | The payment succeeded. |
| `FAILED` | The payment failed. The customer can try again. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.