API

Payment Status

Merchants can read the same transaction states shown in the VenPay console from the payment-status APIs.

Endpoint

Endpoint	Auth	Use
`POST /merchant/payment-status`	`X-API-KEY` (secret / legacy)	Authoritative status for your backend

Request

{ "track_id": "11111111-2222-3333-4444-555555555555" }

Response

{
  "status": "pending_user",
  "track_id": "11111111-2222-3333-4444-555555555555"
}

Status values

Status	Meaning
`pending_merchant`	Awaiting the next merchant or engine step
`pending_user`	Customer is on checkout
`redirecting`	Mid-redirect / callback
`success`	Captured / completed
`failed`	Declined or failed
`error`	System / initiation error
`cancelled`	Shopper left checkout, or the payment was not completed within 30 minutes
`refunded`	Fully refunded
`partial_refund`	Partially refunded

Legacy note: a bare pending value may still appear in older records; treat it as in-flight, same as pending_merchant.

Consistency with the console

The VenPay merchant console displays engine transaction statuses such as pending_merchant and pending_user. These APIs return the same strings so you can reconcile without opening the console.

Client guidance

Fulfill only on success (and your webhook confirmation).
Treat pending_merchant, pending_user, redirecting, and legacy pending as in progress.
Treat failed, error, and cancelled as terminal non-success outcomes (retry with a new initiation).
Card checkout, Apple Pay, Benefit, and Benefit Web Checkout that stay pending_merchant, pending_user, or redirecting are set to cancelled after 30 minutes without payment. A PAYMENT_FAILED webhook is sent; confirm with this status call before you fulfill.
refunded / partial_refund apply after a successful capture.

See also Payment lifecycle and Payment statuses.

Session and authorization

Add "include_lifecycle": true to the same request when you need session usage, authorization progress, and whether a new charge is safe.

{
  "track_id": "11111111-2222-3333-4444-555555555555",
  "include_lifecycle": true
}

{
  "status": "pending_merchant",
  "track_id": "11111111-2222-3333-4444-555555555555",
  "lifecycle": {
    "session": {
      "state": "consumed",
      "created_at": "2026-09-22T10:00:00Z",
      "expires_at": "2026-09-22T10:15:00Z",
      "consumed_at": "2026-09-22T10:02:00Z"
    },
    "authorization": {
      "received": true,
      "received_at": "2026-09-22T10:02:00Z",
      "state": "processing",
      "request_id": "8f3c1a2e-4b5d-4e6f-9a0b-1c2d3e4f5a6b"
    },
    "client_signals": {
      "still_processing": true,
      "authorization_received": true,
      "session_used": true,
      "session_expired_unused": false,
      "waiting_for": "processor",
      "safe_to_abandon": false
    },
    "reattempt": {
      "decision": "do_not_retry",
      "allow_retry": false,
      "reconcile_required": false,
      "reason": "may_still_complete",
      "terminal_kind": "in_flight"
    }
  }
}

Field	Values
`session.state`	`active`, `consumed`, `expired`, `cancelled`
`authorization.state`	`none`, `received`, `processing`, `completed`
`authorization.request_id`	Correlation id for the authorize attempt
`client_signals.waiting_for`	`user_action`, `processor`, `merchant_action`
`reattempt.decision`	`retry_allowed`, `do_not_retry`, `reconcile_first`

allow_retry is true only when decision is retry_allowed. Start a new payment in that case. When decision is reconcile_first, read this endpoint again before charging again. When it is do_not_retry, the payment already succeeded or may still complete.

How to act on each case, including Apple Pay user cancellation versus an in-flight request cancellation: Payment lifecycle.