Payment status

Read back a payment's current state. This is the polling half of the payment contract: after a 202 Accepted from submit payment, poll this endpoint every ~1 second until status reaches a terminal state (confirmed or failed).

GET /v1/pat/venue/{venueId}/order/{orderId}/payment/{externalReference}
Authorization: Bearer <token>

The response is the identical payment object shape returned by the payment POST - you parse exactly one shape across both endpoints.

Keyed on your reference - crash-safe

The lookup key is your own externalReference, not Mozrest's paymentId. If your process crashes right after POSTing - before it could store Mozrest's response - you can still recover the payment's state with the one identifier you are guaranteed to have persisted before calling us.

Path parameters

Name	Type	Notes
venueId	string	Mozrest venue identifier (must be in token scope)
orderId	UUID	Order the payment was submitted against
externalReference	string	The externalReference you sent on submit payment

Response - 200 OK (pending)

Confirmation still in flight. Keep polling.

{
  "paymentId": "3c2a5d1e-77f0-4b2a-9c41-5b8d2e0f6a17",
  "orderId": "00ceefd4-8cc8-428b-985a-207b97cc3cba",
  "status": "pending",
  "failureCode": null,
  "type": "full",
  "amount": 92.40,
  "currency": "EUR",
  "paymentMethod": "card",
  "tip": 5.00,
  "externalReference": "blitz-txn-9f2b1a",
  "orderStatus": "open",
  "recordedAt": "2026-05-11T06:27:07+00:00",
  "confirmedAt": null
}

Response - 200 OK (confirmed)

Terminal success. The POS applied the payment; for type: "full" the order is now closed.

{
  "paymentId": "3c2a5d1e-77f0-4b2a-9c41-5b8d2e0f6a17",
  "orderId": "00ceefd4-8cc8-428b-985a-207b97cc3cba",
  "status": "confirmed",
  "failureCode": null,
  "type": "full",
  "amount": 92.40,
  "currency": "EUR",
  "paymentMethod": "card",
  "tip": 5.00,
  "externalReference": "blitz-txn-9f2b1a",
  "orderStatus": "closed",
  "recordedAt": "2026-05-11T06:27:07+00:00",
  "confirmedAt": "2026-05-11T06:27:11+00:00"
}

Response - 200 OK (failed)

Terminal failure. The POS rejected the payment after dispatch, or confirmation timed out. failureCode says why (table below). The payment does not count toward the bill; the order stays open.

{
  "paymentId": "3c2a5d1e-77f0-4b2a-9c41-5b8d2e0f6a17",
  "orderId": "00ceefd4-8cc8-428b-985a-207b97cc3cba",
  "status": "failed",
  "failureCode": "pos_confirmation_timeout",
  "type": "full",
  "amount": 92.40,
  "currency": "EUR",
  "paymentMethod": "card",
  "tip": 5.00,
  "externalReference": "blitz-txn-9f2b1a",
  "orderStatus": "open",
  "recordedAt": "2026-05-11T06:27:07+00:00",
  "confirmedAt": null
}

A failed payment is data, not an HTTP error

This endpoint answers 200 OK for any existing payment, whatever its state. status: "failed" + failureCode in the body is the failure signal - do not expect a 4xx/5xx for a payment that failed asynchronously. HTTP errors on this endpoint (below) only ever mean the payment could not be found or you lack access.

Polling guidance

• Poll every ~1 second while status is "pending".
• The loop is bounded: every payment reaches a terminal state within 120 seconds of submission. If the POS never confirms, Mozrest fails the payment with failureCode: "pos_confirmation_timeout" - you will never poll forever.
• Stop polling the moment status is "confirmed" or "failed".

Failure codes

failureCode is set only when status is "failed". The slugs are stable - safe to branch on. Where applicable they use the same vocabulary as the 502 forwarding failure cases.

failureCode	Meaning	Recommended partner action
pos_confirmation_timeout	The POS did not confirm the payment within 120 seconds of submission.	Refund/void the charge on your side and inform the guest. Report recurring cases to Mozrest - it usually indicates a venue-side connectivity problem.
pos_check_not_found	The check was closed or moved by staff while the payment was in flight.	Re-fetch /bill and restart the flow from the current state of the table.
pos_overpaid	The payment would exceed the outstanding balance - e.g. staff took a payment on the till concurrently.	Re-fetch /bill and submit a corrected amount (the new totalDue) with a fresh externalReference.
pos_config_missing	Pay-at-Table is not correctly configured for this venue's POS.	Do not retry - contact Mozrest support.

Guest experience while pending

The guest's money is already captured by you (the partner) before Mozrest is called - "pending" only means the restaurant's till has not acknowledged the payment yet. The guest is not at risk of paying twice by waiting. Recommended UX:

• While polling, show a "Confirming with the restaurant…" state.
• Past roughly 10 seconds, switch to a soft-success screen ("Payment received - finalizing with the restaurant") and keep polling in the background - don't hold the guest hostage to a slow till.
• On "confirmed", show full success.
• On "failed", refund/void the charge and inform the guest, following the action column in the failure codes table.

Errors

Status	When
401 Unauthorized	Token invalid or revoked. OAuth-style body, not the standard envelope - see Errors
403 Forbidden	Missing Authorization header, token does not have partner access, or venue not in scope
404 Not Found	Order not found in venue (message: Order "{orderId}" not found for venue "{venueId}".) or no payment with that reference on the order (message: No payment with externalReference "{externalReference}" on order "{orderId}".). Same status either way; the message states which case applies