Language
EN繁简

Docs Navigation

OverviewAuthentication & SigningEndpointQR Code ResolveOrder ValidateOrder RedemptionTesting

QR Code Resolve

Use this endpoint when your staff scans the customer QR code directly. Send the raw scanned QR string to Yuter, and Yuter will verify the QR token, resolve the booking, and confirm that it belongs to your merchant account.

POST/api/integrations/merchant/bookings/resolve-qr

Resolve a scanned Yuter QR code into a redeemable booking for the authenticated merchant.

Request Fields

Field
Type
Required
Description
qrCode
string
Yes
The exact raw string returned by the QR scanner. Send it exactly as scanned.

Response Fields

Field
Type
Description
code
number
Response code.
success
boolean
Present when the QR code is resolved successfully.
message
string
Human-readable summary.
bookingId
string
Resolved voucher id. Use this in later validate or redeem calls.
booking
object
Booking summary returned after the QR code is resolved.
qr
object
QR metadata such as token age in milliseconds.
reason
string
Controlled error reason for code 4 responses.

Response Codes

Yuter standardizes the booking integration response into four top-level codes so merchant-side documentation and cashier UI can stay simple.

Code
Meaning
Notes
1
Success
The booking is valid or redeemed successfully.
2
Already redeemed
The booking has already been redeemed before this request.
3
Invalid booking
The booking id is invalid or the booking record cannot be found.
4
Other errors
Authentication failed, booking not redeemable, merchant not allowed, or other controlled failure.

QR Code Resolve Example

Example request and response for resolving a scanned QR code.

cURL example

API_KEY='<raw merchant api key>'
SCANNED_QR='<raw qr string from scanner>'
TIMESTAMP=$(($(date +%s) * 1000))
NONCE=$(uuidgen)
BODY='{"qrCode":"'"$SCANNED_QR"'"}'
PATH='/api/integrations/merchant/bookings/resolve-qr'
PAYLOAD="POST
$PATH
$TIMESTAMP
$NONCE
$BODY"
SIGNATURE=$(printf "%s" "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_KEY" -hex | sed 's/^.* //')

curl -X POST "https://www.yuterwellness.com$PATH" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-nonce: $NONCE" \
  -H "x-signature: $SIGNATURE" \
  -d "$BODY"

Response Example

{
  "code": 1,
  "success": true,
  "message": "QR code resolved successfully",
  "bookingId": "69ce982e96a5b33a356abab0",
  "booking": {
    "_id": "69ce982e96a5b33a356abab0",
    "programTitle": "Private Merchant Test Event",
    "userName": "Test User",
    "userEmail": "test@example.com",
    "quantity": 1,
    "date": "2026-04-10",
    "status": "paid"
  },
  "qr": {
    "tokenAgeMs": 1834
  }
}