Payments

Payment lifecycle

Every VenPays payment is identified by a track_id and moves through engine states before merchants see a simplified status.

Happy path

Your backend initiates payment
        ↓
Payment Engine creates track_id (+ payment_url or native session)
        ↓
Customer authenticates (hosted page / Apple Pay / Benefit)
        ↓
PSP result returns to Payment Engine
        ↓
Transaction status updated
        ↓
Webhook (PAYMENT_SUCCESS or PAYMENT_FAILED) → your server
        ↓
You confirm with payment-status and fulfill the order

Merchant-facing statuses

From POST /merchant/payment-status:

Status	Meaning
`success`	Payment completed
`failed`	Failed or error terminal states
`pending`	Not yet terminal (includes user checkout, redirecting, and some non-success states)

Engine statuses are richer (pending_merchant, pending_user, redirecting, cancelled, refunded, …). See Payment statuses.

Timeouts and pending

A network timeout on your HTTP client does not mean the payment failed. The customer may still complete checkout. Always:

Persist track_id before relying on the response
Poll or await webhooks
Use authenticated payment-status for reconciliation

Native Apple Pay authorize may return HTTP 202 with processing under concurrency — recover with the SDK status GET while the native session is valid.