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

# Verify a payment

> Confirm a transaction on your server with the reference before you fulfill.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://server.staging.vestrapay.app/v1/payment/verify/VPY_TXN_ACME001 \
  -H "x-api-key: sk_test_yourkey"
```

`Authorization: Bearer sk_test_yourkey` is accepted. Lookup is by our reference (`VPY_TXN_…`).

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "success",
  "data": {
    "id": "3f2a0c1e-8b44-4d91-9c2a-1a2b3c4d5e6f",
    "reference": "VPY_TXN_ACME001",
    "amount": "100.00",
    "total": "101.50",
    "amountSettled": "100.00",
    "currency": "NGN",
    "status": "success",
    "channel": "card",
    "fees": "1.50",
    "merchantBearsCost": false,
    "paidAt": "2026-05-10T14:30:00.000Z",
    "metadata": { "orderId": "ORD_12345" }
  }
}
```

| Field           | Meaning                                                                     |
| --------------- | --------------------------------------------------------------------------- |
| `amount`        | What you initialized.                                                       |
| `total`         | What the customer paid.                                                     |
| `amountSettled` | What you receive after fees, once `status` is `success`. `null` until then. |
| `fees`          | Fee on this transaction.                                                    |
| `channel`       | `card`, `bank_transfer`, `bank_payment`, or `ussd`.                         |
| `metadata`      | Echo of initialize `metadata`.                                              |
| `split`         | Present when you passed `distribution`.                                     |

Fulfill when `data.status` is `success` and `data.amount` matches the order.

| `data.status` | Meaning                       |
| ------------- | ----------------------------- |
| `pending`     | Created, not finished.        |
| `processing`  | In flight.                    |
| `success`     | Paid.                         |
| `failed`      | Terminal failure.             |
| `abandoned`   | Customer left without paying. |

## Idempotent fulfillment

Webhooks retry. The customer can reload the callback URL.

1. Load the order by `reference`.
2. If it is already marked paid, return 200.
3. If verify says `success` and the amount matches, mark paid once.

## Checkout helpers (access code)

* `GET /v1/payment/checkout/status`
* `GET /v1/payment/checkout/verify`
* `GET /v1/payment/checkout/events`

Use secret-key verify on the server.