Appearance
Verify and confirm payment with the gateway after customer returns
POST
/rest/v1/checkout/confirm-payment/{orderId}
Asks the gateway whether this order was actually paid and, if so, settles it. Returns {orderId, status, confirmed}, plus reason when the order was not in a confirmable state.
status IS THE PAYMENT VERDICT; confirmed IS NOT. confirmed answers only whether THIS call verified the payment with the gateway. An order can come back status: PAID with confirmed: false — because it was already settled before the call (reason is then already_paid), or because a webhook settled it first. Branch on status: SETTLED is PAID or PENDING_ACCEPTED, awaiting payment is PENDING.
⚠️ PENDING_ACCEPTED is the TERMINAL state of the offline payways (delivery, bank_transfer, paid_at_store) — they settle at placement and never reach PAID.
isPaid WAS REMOVED from both response arms (#754): it published a reconciliation marker, not a payment status, and reported paid orders as unpaid. See GET /rest/checkout/payment-status/{orderId} for the full explanation.
⚠️ FOR vivawallet YOU MUST SEND THE TRANSACTION ID (#796), or this call can never confirm the order. Viva appends it to the return URL as the t query parameter — forward it as {"transactionId": "<uuid>"} in the request body. It is the ONLY source: the order row stores Viva's orderCode, which is a different identifier, and Viva's Retrieve Transaction endpoint is keyed on the transaction UUID. Without it the call answers confirmed: false and the order is eventually cancelled by the incomplete-order sweep despite the money having been taken. The body is optional and ignored by every other payway.
A supplied transaction id is not trusted on its own: the transaction Viva describes must name the same order code the checkout stored, its status must be settled, and its amount must match the order total. A transaction Viva reports as still IN PROGRESS (StatusId: A) does NOT confirm the order — it is not paid yet, and the order stays PENDING for a later poll.
Verification is gateway-specific and FAILS CLOSED: only stripe, vivawallet and paypaladvanced have a verification arm, so for any other payway this returns confirmed: false and changes nothing. That is by design, not a defect — eurobank is settled by the gateway posting to its server-owned callback, and paybybank by its webhook. Poll this endpoint or payment-status rather than expecting this call to settle them.
Authorizations
bearerAuth
JWT access token obtained from /rest/auth/admin/login or /rest/auth/customer/login
Type
HTTP (bearer)
Parameters
Path Parameters
orderId*
Type
Requiredinteger
Request Body
application/json
JSON "transactionId": "string"
{
}
Responses
Payment confirmation result