Verify a payment

Verification is the step that turns “something happened” into “this order is paid”. Webhooks and browser callbacks tell you to look. Verify is the authoritative answer. It is a single authenticated GET from your server that returns the current state of one payment as Vestrapay records it. Never fulfil an order from a callback URL, a webhook body or a client-side result alone. Always call verify with your secret key and decide from its response.

The request

Look up a payment by the reference that initialise returned, which has the form VPY_TXN_….

curl https://api.sandbox.vestrapay.app/v1/payment/verify/VPY_TXN_ACME001 \
  -H "x-api-key: $VESTRAPAY_SECRET_KEY"

const res = await fetch(
  `https://api.sandbox.vestrapay.app/v1/payment/verify/${encodeURIComponent(reference)}`,
  { headers: { "x-api-key": process.env.VESTRAPAY_SECRET_KEY } },
);
const body = await res.json();

import os, requests

res = requests.get(
    f"https://api.sandbox.vestrapay.app/v1/payment/verify/{reference}",
    headers={"x-api-key": os.environ["VESTRAPAY_SECRET_KEY"]},
    timeout=15,
)
body = res.json()

<?php
$ch = curl_init("https://api.sandbox.vestrapay.app/v1/payment/verify/" . rawurlencode($reference));
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER => ["x-api-key: " . getenv("VESTRAPAY_SECRET_KEY")],
  CURLOPT_RETURNTRANSFER => true,
]);
$body = json_decode(curl_exec($ch), true);

Authorization: Bearer with the same secret key also works. Use the key and host of the environment where the payment was created. A sandbox reference cannot be verified on live, and the reverse, and returns transaction.not_found.

The response

{
  "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
`id`	Vestrapay’s internal UUID for the transaction.
`reference`	The reference you looked up.
`amount`	What you initialised. Compare this to your order.
`total`	What the customer paid, including the fee when the customer bears it.
`amountSettled`	What you receive after fees, once `status` is `success`. `null` until then.
`fees`	The fee on this transaction.
`merchantBearsCost`	Whether the fee came from your side.
`currency`	The currency, normally NGN.
`channel`	`card`, `bank_transfer`, `bank_payment` or `ussd`. `null` before the customer chooses one.
`paidAt`	When the payment succeeded. `null` until then.
`metadata`	An echo of the metadata you sent on initialise.
`split`	Present only when the payment carried a distribution and has been allocated. See below.

Payment statuses

`data.status`	Meaning	What to do
`pending`	Created, the customer has not finished.	Wait. Do not fulfil.
`processing`	A charge is in flight.	Wait for the webhook, or verify again shortly.
`success`	Paid.	Fulfil if the amount matches.
`failed`	Terminal failure.	Do not fulfil. The customer can start a new payment.
`abandoned`	The customer left without paying.	Do not fulfil.

Only success means paid. Treat anything else as not paid, and do not guess from the channel or from timing.

The fulfilment decision

Fulfil when both conditions hold:

data.status is success.
data.amount equals the amount you expected for that order.

If the status is success but the amount differs, do not fulfil. Hold the order and investigate, because the payment may belong to a different order or to a tampered request. Compare amounts as strings or decimals, never as binary floats.

Idempotent fulfilment

Webhooks are retried and customers reload callback pages. Your fulfilment code will run more than once for the same payment. Design for that.

Load the order by reference.
If it is already marked paid, return HTTP 200 and stop.
Call verify. If the payment is success and the amount matches, mark the order paid and fulfil in a single atomic step, using a database transaction, a conditional update or a unique constraint.

async function onPaymentSignal(reference) {
  const order = await db.orders.findByReference(reference);
  if (!order || order.status === "paid") return; // unknown or already handled

  const payment = await verify(reference);
  if (payment.status !== "success" || payment.amount !== order.amount) return;

  // Conditional update: only one concurrent caller gets changed === true
  const changed = await db.orders.markPaidIfPending(order.id, payment.paidAt);
  if (changed) await fulfil(order);
}

Return a 2xx to the webhook as soon as the signal is queued. Do the verify and fulfilment in the worker, not in the request handler.

Splits on verify

When the payment was initialised with a distribution, verify includes a split object once the payment has been allocated. Allocation follows success by a short moment, so a verify call made in the first instant after payment may not yet include it. The payment is still success and safe to fulfil.

{
  "status": "success",
  "data": {
    "reference": "VPY_TXN_ACME001",
    "amount": "1000.00",
    "status": "success",
    "split": {
      "primaryAccountAmount": "250.00",
      "currency": "NGN",
      "entries": [
        { "status": "RECONCILED", "ledgerID": "…", "amount": "510.00" },
        { "status": "RECONCILED", "ledgerID": "…", "amount": "90.00" },
        { "status": "RECONCILED", "ledgerID": "…", "amount": "150.00" }
      ]
    }
  }
}

Field	Meaning
`primaryAccountAmount`	What went to your primary settlement account.
`entries[].amount`	The amount allocated to one destination.
`entries[].ledgerID`	An opaque identifier for the destination account. It is not the sub-account `id`.
`entries[].status`	`RECONCILED` when the destination was credited. `FALLBACK` when it could not be, for example because the sub-account was inactive, and the amount was kept in your primary account instead. A fallback entry has an `amount` of 0.00 and a `message` saying why.

The allocation rules are explained on Distribution.

Errors and retries

Situation	Response	What to do
Unknown reference or wrong environment	404 `transaction.not_found`	Check the reference and the key.
Bad or missing key	401 `invalid_credentials` and related codes	Check the header and the key.
Network failure or 5xx	No body or an error	Retry with exponential backoff. Verify is read-only and safe to repeat.

If a payment stays pending or processing for longer than you expect, keep it in a waiting state rather than failing the order. Webhooks and later verify calls will reflect the final outcome. For anything that looks stuck, contact tech@vestrapay.com with the reference.

Checkout helpers

The access-code endpoints GET /v1/payment/checkout/status, GET /v1/payment/checkout/verify and GET /v1/payment/checkout/events are for pay screens that want to show progress. They are not a substitute for your server’s secret-key verify before fulfilling.

Get started

Accept payments

Services & splits

Partners

Settlements

The request

The response

Payment statuses

The fulfilment decision

Idempotent fulfilment

Splits on verify

Errors and retries

Checkout helpers

​The request

​The response

​Payment statuses

​The fulfilment decision

​Idempotent fulfilment

​Splits on verify

​Errors and retries

​Checkout helpers

The request

The response

Payment statuses

The fulfilment decision

Idempotent fulfilment

Splits on verify

Errors and retries

Checkout helpers