Payments

Verify a payment

After checkout, ask Tunnel to confirm the final status with the provider. The response uses the same unified collection shape; the raw PSP verify payload is in raw.

POST/v1/transactions/:id/verify

Verify with the provider that processed the charge

Which id?

Use Tunnel’s transactionId from the create response (e.g. txn_…). You can also look up the collection first via GET /v1/collections/{reference}.

cURL example

cURL
curl -X POST "https://xv9ni4gwk9.execute-api.us-east-1.amazonaws.com/dev/v1/transactions/txn_8f2a1c0b4e9d7a6c/verify" \
  -H "Authorization: Bearer sk_test_…" \
  -H "X-Tunnel-Origin: https://api.yourapp.com"

Response

Successful verification
{
  "success": true,
  "data": {
    "success": true,
    "transactionId": "txn_8f2a1c0b4e9d7a6c",
    "reference": "ord_1001",
    "providerReference": "txn_8f2a1c0b4e9d7a6c",
    "provider": "paystack",
    "status": "successful",
    "amount": 5000,
    "currency": "NGN",
    "channel": "card",
    "raw": {
      "status": true,
      "message": "Verification successful",
      "data": {
        "status": "success",
        "reference": "txn_8f2a1c0b4e9d7a6c",
        "amount": 500000,
        "currency": "NGN"
      }
    },
    "createdAt": "2026-08-04T06:00:00.000Z"
  },
  "meta": { "requestId": "…", "timestamp": "…" }
}

Note: amounts in Tunnel fields are major units. Values inside raw follow the provider’s native units (Paystack returns kobo).

Status values you will see

statusMeaning
successfulPayment confirmed
pendingStill processing — poll or wait for webhook
requires_actionCustomer action still needed
failedDeclined or errored
cancelledAbandoned by customer

Next: Webhooks →