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

# Verify a Payment — GET /payments/verify/{reference}

> GET /payments/verify/{reference} — retrieves the current status and details of a payment transaction by its unique reference string.

Use this endpoint to confirm the outcome of a payment after a customer completes (or abandons) checkout. Supply the transaction `reference` returned by [Initialize Payment](/api-reference/payments/initialize) and Paylink returns the latest status and full transaction details.

```http theme={null}
GET https://sandbox.lyseis-pay.com/payments/verify/{reference}
```

<Note>
  Replace `sandbox.lyseis-pay.com` with `live.lyseis-pay.com` when moving to production.
</Note>

## Headers

| Header        | Value                                   |
| ------------- | --------------------------------------- |
| `X-Key-Id`    | Your merchant key ID                    |
| `X-Timestamp` | Unix timestamp of the request (seconds) |
| `X-Signature` | HMAC-SHA256 signature of the payload    |

## Path Parameters

<ParamField path="reference" type="string" required>
  The unique payment reference. This is either the value you provided at initialization or the auto-generated reference returned in the initialization response.
</ParamField>

## Response

<ResponseField name="status" type="string">
  Top-level request status. `"success"` means the API call completed and data was found — it does **not** indicate whether the payment itself succeeded. Inspect `data.status` for the payment outcome.
</ResponseField>

<ResponseField name="message" type="string">
  A human-readable summary of the response (e.g. `"Transaction retrieved"`).
</ResponseField>

<ResponseField name="data" type="object">
  The transaction object.

  <Expandable title="data fields">
    <ResponseField name="data.reference" type="string">
      The merchant-facing transaction reference.
    </ResponseField>

    <ResponseField name="data.transaction_id" type="string">
      Paylink's internal unique identifier for this transaction. Use this for support queries.
    </ResponseField>

    <ResponseField name="data.status" type="string">
      The payment status. See the [Payment Statuses](#payment-statuses) table below.
    </ResponseField>

    <ResponseField name="data.amount" type="number">
      The payment amount in the smallest currency unit (e.g. kobo for NGN).
    </ResponseField>

    <ResponseField name="data.currency" type="string">
      ISO 4217 currency code (e.g. `NGN`).
    </ResponseField>

    <ResponseField name="data.customer_email" type="string">
      Email address of the customer who initiated the payment.
    </ResponseField>

    <ResponseField name="data.payment_method" type="string">
      The method used to complete the payment, e.g. `card`, `bank_transfer`, `ussd`, `direct_debit`.
    </ResponseField>

    <ResponseField name="data.metadata" type="object">
      The metadata object passed at initialization, returned unchanged.
    </ResponseField>

    <ResponseField name="data.created_at" type="string">
      ISO 8601 timestamp when the payment session was created.
    </ResponseField>

    <ResponseField name="data.updated_at" type="string">
      ISO 8601 timestamp of the most recent status change.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Request

```http theme={null}
GET https://sandbox.lyseis-pay.com/payments/verify/order_12345
X-Key-Id: mk_sandbox_xxxxxxxxxx
X-Timestamp: 1751234567
X-Signature: <hmac-sha256-signature>
```

## Example Response

```json theme={null}
{
  "status": "success",
  "message": "Transaction retrieved",
  "data": {
    "reference": "order_12345",
    "transaction_id": "txn_98765abcde",
    "status": "success",
    "amount": 2500.00,
    "currency": "NGN",
    "customer_email": "customer@example.com",
    "payment_method": "card",
    "metadata": { "order_id": "12345" },
    "created_at": "2026-09-15T10:22:00Z",
    "updated_at": "2026-09-15T10:23:45Z"
  }
}
```

## Payment Statuses

| Status       | Meaning                                                                                |
| ------------ | -------------------------------------------------------------------------------------- |
| `success`    | Payment was completed and funds were received successfully.                            |
| `processing` | Payment is in progress. The customer has initiated payment but it has not yet settled. |
| `failed`     | The payment attempt was declined or encountered an error.                              |
| `abandoned`  | The customer left the checkout page without attempting payment.                        |
| `reversed`   | A previously successful payment has been reversed or refunded.                         |
| `expired`    | The checkout session timed out before the customer completed payment.                  |

<Warning>
  Always verify payment status **server-side** using this endpoint or your webhook handler before fulfilling an order. Do not rely solely on the `callback_url` redirect, as customers can manipulate query parameters in the browser.
</Warning>