{"openapi":"3.1.0","info":{"title":"JEK Platform API","version":"1.0.0","description":"Public REST API for the JEK platform. Use X-JEK-Env to select the environment on the shared API host; use staging for testing. Verify matching X-JEK-Env and X-JEK-Isolation: 1 on consumer responses before reading or caching them. Errors follow RFC 9457 (application/problem+json).","contact":{"name":"JEK Developer Support","url":"https://developer.jek.app"}},"servers":[{"url":"https://api.jek.app","description":"Shared API; select the environment with X-JEK-Env"}],"security":[{"userBearer":[]}],"components":{"securitySchemes":{"userBearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"End-user session token."},"driverBearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Driver / device session token (Driver Pro, M1OS)."},"merchantBearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"wonderHmac":{"type":"apiKey","in":"header","name":"Authorization","description":"Legacy compatibility scheme: `Wonder-HMAC-SHA256 Credential=<appid>/<yyyyMMdd>/<service>, SignedHeaders=..., Signature=<hex>` plus `X-JEK-Timestamp` and `X-JEK-Device-Sn`."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"Problem":{"type":"object","required":["type","title","status","code"],"properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"PageMeta":{"type":"object","properties":{"next_cursor":{"type":["string","null"],"description":"Cursor for the next page."},"page_size":{"type":"integer"},"total_count":{"type":"integer"}}},"Money":{"type":"object","description":"Integer minor units plus an ISO 4217 currency code.","required":["amount","currency"],"properties":{"amount":{"type":"integer","example":8850},"currency":{"type":"string","example":"HKD"}}},"Merchant":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"name_en":{"type":"string","nullable":true},"name_zh":{"type":"string","nullable":true},"cuisine":{"type":"string","nullable":true},"address_en":{"type":"string","nullable":true},"image_url":{"type":"string","nullable":true},"logo_url":{"type":"string","nullable":true},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"michelin_stars":{"type":"integer","nullable":true}}},"Voucher":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"discount_type":{"type":"string","enum":["percent","amount"]},"discount_value":{"type":"number"},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"image_url":{"type":"string","nullable":true}}},"VehicleType":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"base_fare":{"type":"number"},"per_km":{"type":"number"},"per_min":{"type":"number"}}},"RideQuote":{"type":"object","description":"Response when vehicle_type_id was sent.","properties":{"currency":{"type":"string","example":"HKD"},"fare":{"type":"number"},"vehicle_type":{"$ref":"#/components/schemas/VehicleType"},"quote_ref":{"$ref":"#/components/schemas/QuoteRef"},"expires_at":{"$ref":"#/components/schemas/QuoteExpiry"}}},"QuoteRef":{"type":"string","description":"Signed reference to this quote. Present it as `quote_ref` on POST /api/v1/me/rides and the booking is refused with 409 QUOTE_STALE if the fare has moved since. Optional at both ends; absent when the deployment has no signing secret."},"QuoteExpiry":{"type":"string","format":"date-time","description":"When `quote_ref` stops being accepted. Re-quote past this point."},"ClassQuote":{"type":"object","properties":{"vehicle_type_id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"Express Taxi"},"fare":{"type":"number"},"currency":{"type":"string","example":"HKD"}}},"WithheldClass":{"type":"object","description":"A class priced but NOT offered on this trip, with the floor it did not clear.","properties":{"vehicle_type_id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"85% Meter Taxi"},"fare":{"type":"number","description":"What it would have cost — below `min_fare`."},"currency":{"type":"string","example":"HKD"},"min_fare":{"type":"number","example":90,"description":"The fare this class is not offered below."}}},"RideSelectionQuote":{"type":"object","description":"Response when vehicle_class_ids was sent.","properties":{"currency":{"type":"string","example":"HKD"},"authorize":{"type":"number","description":"The dearest fare among the classes sent — what the passenger pre-authorises."},"dearest":{"$ref":"#/components/schemas/ClassQuote"},"quotes":{"type":"array","items":{"$ref":"#/components/schemas/ClassQuote"}},"withheld":{"type":"array","items":{"$ref":"#/components/schemas/WithheldClass"},"description":"Classes dropped from `quotes` because this trip prices below their minimum fare. Render `quotes`, never these — they are here so the omission can be explained, not shown."},"vehicle_class_limit":{"type":"integer","example":6,"description":"How many classes one booking may accept."},"quote_ref":{"$ref":"#/components/schemas/QuoteRef"},"expires_at":{"$ref":"#/components/schemas/QuoteExpiry"}}},"RideAvailability":{"type":"object","properties":{"supply":{"type":"object","properties":{"status":{"type":"string","enum":["ok","none","unavailable","not_applicable"],"description":"`none` is a measured 'there is no car'; `unavailable` is 'we could not measure'. Neither may be rendered as a reason not to book."},"count":{"type":"integer"},"nearest_m":{"type":"integer","nullable":true},"radius_m":{"type":"integer"},"fix_max_age_s":{"type":"integer"},"reason":{"type":"string","description":"Only on `unavailable`."}}},"eta":{"type":"object","nullable":true,"properties":{"pickup_eta_min":{"type":"integer"},"duration_s":{"type":"integer"},"distance_m":{"type":"integer"},"source":{"type":"string","enum":["provider","estimate"],"description":"The one route actually measured per probe."}}},"classes":{"type":"array","items":{"$ref":"#/components/schemas/ClassAvailability"}},"area":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"name":{"type":"string"}}},"fulfilment":{"type":"string","nullable":true},"config_version":{"type":"string"},"cached":{"type":"boolean"},"measured_at":{"type":"string","format":"date-time","nullable":true,"description":"When this answer was measured — NOT when it was served. Null when nothing could be measured."},"expires_at":{"type":"string","format":"date-time","nullable":true,"description":"When the cached answer stops being reused."},"age_s":{"type":"integer","nullable":true,"description":"How old the measurement is right now."}}},"ClassAvailability":{"type":"object","properties":{"vehicle_type_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"available":{"type":"boolean","description":"At least one driver in range may serve this class. Informational — never a booking gate."},"count":{"type":"integer"},"nearest_m":{"type":"integer","nullable":true},"eta_min":{"type":"integer","nullable":true},"eta_source":{"type":"string","nullable":true,"enum":["provider","scaled","estimate"],"description":"`provider` — this class's own nearest car was routed. `scaled` — derived from that one measured route by distance ratio. `estimate` — the router did not answer and the base was a straight line."},"eta_confidence":{"type":"string","nullable":true,"enum":["high","medium","low"],"description":"The same fact as a word. Soften how you draw a low-confidence ETA; never disable the class."}}},"Profile":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true}}},"SuccessEnvelope":{"type":"object","required":["data"],"properties":{"data":{"description":"Resource or list of resources."},"meta":{"$ref":"#/components/schemas/PageMeta"}}}},"responses":{"Problem":{"description":"RFC 9457 problem details","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/api/v1/auth/phone-country":{"get":{"operationId":"getApiV1AuthPhoneCountry","summary":"Suggest a registration phone country from the visitor IP","description":"Unauthenticated, read-only country hint from Cloudflare CF-IPCountry. Requires explicit X-JEK-Env. Returns {code:200,message:'OK',data:{country:ISO-alpha2|null}} with environment/isolation proof and private, no-store. Unknown/Tor countries return null; no IP or coordinates are returned or stored. A suggestion only, never identity or an access rule.","tags":["Consumer Auth"],"parameters":[{"name":"X-User-Scope","in":"header","schema":{"type":"string","enum":["jek","hk_taxi_go"],"default":"jek"},"required":false,"description":"jek (default) or hk_taxi_go. Product membership; never driver/admin permissions."}],"responses":{"200":{"description":"Success: {code:200,message:'OK',data:{...}}. Session data includes scope='user' and user_scope."},"400":{"description":"Invalid request or conflicting scopes"},"401":{"description":"Invalid/expired credential or proof"},"403":{"description":"Phone verification or product membership required"},"409":{"description":"Existing accounts need reconciliation"},"429":{"description":"Supabase rate limit"},"503":{"description":"Auth provider, configuration or storage unavailable"}},"security":[]}},"/api/v1/auth/signin/check":{"post":{"operationId":"postApiV1AuthSigninCheck","summary":"Check whether a phone has completed account setup; unfinished accounts use OTP signup","description":"Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.","tags":["Consumer Auth"],"parameters":[{"name":"X-User-Scope","in":"header","schema":{"type":"string","enum":["jek","hk_taxi_go"],"default":"jek"},"required":false,"description":"jek (default) or hk_taxi_go. Product membership; never driver/admin permissions."}],"responses":{"200":{"description":"Success: {code:200,message:'OK',data:{...}}. Session data includes scope='user' and user_scope."},"400":{"description":"Invalid request or conflicting scopes"},"401":{"description":"Invalid/expired credential or proof"},"403":{"description":"Phone verification or product membership required"},"409":{"description":"Existing accounts need reconciliation"},"429":{"description":"Supabase rate limit"},"503":{"description":"Auth provider, configuration or storage unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone"],"properties":{"phone":{"type":"string","description":"International phone, e.g. +852 91234567"}}}}}},"security":[]}},"/api/v1/auth/register":{"post":{"operationId":"postApiV1AuthRegister","summary":"Send Supabase signup OTP","description":"Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.","tags":["Consumer Auth"],"parameters":[{"name":"X-User-Scope","in":"header","schema":{"type":"string","enum":["jek","hk_taxi_go"],"default":"jek"},"required":false,"description":"jek (default) or hk_taxi_go. Product membership; never driver/admin permissions."}],"responses":{"200":{"description":"Success: {code:200,message:'OK',data:{...}}. Session data includes scope='user' and user_scope."},"400":{"description":"Invalid request or conflicting scopes"},"401":{"description":"Invalid/expired credential or proof"},"403":{"description":"Phone verification or product membership required"},"409":{"description":"Existing accounts need reconciliation"},"429":{"description":"Supabase rate limit"},"503":{"description":"Auth provider, configuration or storage unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone"],"properties":{"phone":{"type":"string","description":"International phone, e.g. +852 91234567"},"deviceId":{"type":"string","description":"Optional device identifier; if supplied, reuse it at every step."}}}}}},"security":[]}},"/api/v1/auth/login":{"post":{"operationId":"postApiV1AuthLogin","summary":"Sign in with Supabase phone and password","description":"Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.","tags":["Consumer Auth"],"parameters":[{"name":"X-User-Scope","in":"header","schema":{"type":"string","enum":["jek","hk_taxi_go"],"default":"jek"},"required":false,"description":"jek (default) or hk_taxi_go. Product membership; never driver/admin permissions."}],"responses":{"200":{"description":"Success: {code:200,message:'OK',data:{...}}. Session data includes scope='user' and user_scope."},"400":{"description":"Invalid request or conflicting scopes"},"401":{"description":"Invalid/expired credential or proof"},"403":{"description":"Phone verification or product membership required"},"409":{"description":"Existing accounts need reconciliation"},"429":{"description":"Supabase rate limit"},"503":{"description":"Auth provider, configuration or storage unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone","password"],"properties":{"phone":{"type":"string","description":"International phone, e.g. +852 91234567"},"password":{"type":"string","description":"New passwords require 8–128 characters and the Supabase password policy."}}}}}},"security":[]}},"/api/v1/auth/forget-password":{"post":{"operationId":"postApiV1AuthForgetPassword","summary":"Send password recovery SMS through Supabase","description":"Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.","tags":["Consumer Auth"],"parameters":[{"name":"X-User-Scope","in":"header","schema":{"type":"string","enum":["jek","hk_taxi_go"],"default":"jek"},"required":false,"description":"jek (default) or hk_taxi_go. Product membership; never driver/admin permissions."}],"responses":{"200":{"description":"Success: {code:200,message:'OK',data:{...}}. Session data includes scope='user' and user_scope."},"400":{"description":"Invalid request or conflicting scopes"},"401":{"description":"Invalid/expired credential or proof"},"403":{"description":"Phone verification or product membership required"},"409":{"description":"Existing accounts need reconciliation"},"429":{"description":"Supabase rate limit"},"503":{"description":"Auth provider, configuration or storage unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone"],"properties":{"phone":{"type":"string","description":"International phone, e.g. +852 91234567"},"deviceId":{"type":"string","description":"Optional device identifier; if supplied, reuse it at every step."}}}}}},"security":[]}},"/api/v1/auth/forgot-password":{"post":{"operationId":"postApiV1AuthForgotPassword","summary":"Alias for forget-password","description":"Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.","tags":["Consumer Auth"],"parameters":[{"name":"X-User-Scope","in":"header","schema":{"type":"string","enum":["jek","hk_taxi_go"],"default":"jek"},"required":false,"description":"jek (default) or hk_taxi_go. Product membership; never driver/admin permissions."}],"responses":{"200":{"description":"Success: {code:200,message:'OK',data:{...}}. Session data includes scope='user' and user_scope."},"400":{"description":"Invalid request or conflicting scopes"},"401":{"description":"Invalid/expired credential or proof"},"403":{"description":"Phone verification or product membership required"},"409":{"description":"Existing accounts need reconciliation"},"429":{"description":"Supabase rate limit"},"503":{"description":"Auth provider, configuration or storage unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone"],"properties":{"phone":{"type":"string","description":"International phone, e.g. +852 91234567"},"deviceId":{"type":"string","description":"Optional device identifier; if supplied, reuse it at every step."}}}}}},"security":[]}},"/api/v1/auth/otp/send":{"post":{"operationId":"postApiV1AuthOtpSend","summary":"Send or resend a Supabase SMS OTP","description":"Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.","tags":["Consumer Auth"],"parameters":[{"name":"X-User-Scope","in":"header","schema":{"type":"string","enum":["jek","hk_taxi_go"],"default":"jek"},"required":false,"description":"jek (default) or hk_taxi_go. Product membership; never driver/admin permissions."}],"responses":{"200":{"description":"Success: {code:200,message:'OK',data:{...}}. Session data includes scope='user' and user_scope."},"400":{"description":"Invalid request or conflicting scopes"},"401":{"description":"Invalid/expired credential or proof"},"403":{"description":"Phone verification or product membership required"},"409":{"description":"Existing accounts need reconciliation"},"429":{"description":"Supabase rate limit"},"503":{"description":"Auth provider, configuration or storage unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone","action"],"properties":{"phone":{"type":"string","description":"International phone, e.g. +852 91234567"},"action":{"type":"string","description":"signin, signup, or pwdreset"},"deviceId":{"type":"string","description":"Optional device identifier; if supplied, reuse it at every step."}}}}}},"security":[]}},"/api/v1/auth/otp/verify":{"post":{"operationId":"postApiV1AuthOtpVerify","summary":"Verify SMS; signin returns session, signup/pwdreset return completion token","description":"Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.","tags":["Consumer Auth"],"parameters":[{"name":"X-User-Scope","in":"header","schema":{"type":"string","enum":["jek","hk_taxi_go"],"default":"jek"},"required":false,"description":"jek (default) or hk_taxi_go. Product membership; never driver/admin permissions."}],"responses":{"200":{"description":"Success: {code:200,message:'OK',data:{...}}. Session data includes scope='user' and user_scope."},"400":{"description":"Invalid request or conflicting scopes"},"401":{"description":"Invalid/expired credential or proof"},"403":{"description":"Phone verification or product membership required"},"409":{"description":"Existing accounts need reconciliation"},"429":{"description":"Supabase rate limit"},"503":{"description":"Auth provider, configuration or storage unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone","action","token","aut_code"],"properties":{"phone":{"type":"string","description":"International phone, e.g. +852 91234567"},"action":{"type":"string","description":"signin, signup, or pwdreset"},"token":{"type":"string","description":"Opaque proof from the previous step; bound to product, device and purpose, expires after 10 minutes."},"deviceId":{"type":"string","description":"Optional device identifier; if supplied, reuse it at every step."},"aut_code":{"type":"string"}}}}}},"security":[]}},"/api/v1/auth/verification":{"post":{"operationId":"postApiV1AuthVerification","summary":"Alias for otp/verify","description":"Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.","tags":["Consumer Auth"],"parameters":[{"name":"X-User-Scope","in":"header","schema":{"type":"string","enum":["jek","hk_taxi_go"],"default":"jek"},"required":false,"description":"jek (default) or hk_taxi_go. Product membership; never driver/admin permissions."}],"responses":{"200":{"description":"Success: {code:200,message:'OK',data:{...}}. Session data includes scope='user' and user_scope."},"400":{"description":"Invalid request or conflicting scopes"},"401":{"description":"Invalid/expired credential or proof"},"403":{"description":"Phone verification or product membership required"},"409":{"description":"Existing accounts need reconciliation"},"429":{"description":"Supabase rate limit"},"503":{"description":"Auth provider, configuration or storage unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone","action","token","aut_code"],"properties":{"phone":{"type":"string","description":"International phone, e.g. +852 91234567"},"action":{"type":"string","description":"signin, signup, or pwdreset"},"token":{"type":"string","description":"Opaque proof from the previous step; bound to product, device and purpose, expires after 10 minutes."},"deviceId":{"type":"string","description":"Optional device identifier; if supplied, reuse it at every step."},"aut_code":{"type":"string"}}}}}},"security":[]}},"/api/v1/auth/signup/completed":{"post":{"operationId":"postApiV1AuthSignupCompleted","summary":"Set name after phone verification; return Supabase session","description":"Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.","tags":["Consumer Auth"],"parameters":[{"name":"X-User-Scope","in":"header","schema":{"type":"string","enum":["jek","hk_taxi_go"],"default":"jek"},"required":false,"description":"jek (default) or hk_taxi_go. Product membership; never driver/admin permissions."}],"responses":{"200":{"description":"Success: {code:200,message:'OK',data:{...}}. Session data includes scope='user' and user_scope."},"400":{"description":"Invalid request or conflicting scopes"},"401":{"description":"Invalid/expired credential or proof"},"403":{"description":"Phone verification or product membership required"},"409":{"description":"Existing accounts need reconciliation"},"429":{"description":"Supabase rate limit"},"503":{"description":"Auth provider, configuration or storage unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token","first_name","last_name"],"properties":{"token":{"type":"string","description":"Opaque proof from the previous step; bound to product, device and purpose, expires after 10 minutes."},"deviceId":{"type":"string","description":"Optional device identifier; if supplied, reuse it at every step."},"first_name":{"type":"string"},"last_name":{"type":"string"},"password":{"type":"string","description":"New passwords require 8–128 characters and the Supabase password policy."}}}}}},"security":[]}},"/api/v1/auth/phone/change/start":{"post":{"operationId":"postApiV1AuthPhoneChangeStart","summary":"Send a code to the number currently on the account","description":"Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.","tags":["Consumer Auth"],"parameters":[{"name":"X-User-Scope","in":"header","schema":{"type":"string","enum":["jek","hk_taxi_go"],"default":"jek"},"required":false,"description":"jek (default) or hk_taxi_go. Product membership; never driver/admin permissions."}],"responses":{"200":{"description":"Success: {code:200,message:'OK',data:{...}}. Session data includes scope='user' and user_scope."},"400":{"description":"Invalid request or conflicting scopes"},"401":{"description":"Invalid/expired credential or proof"},"403":{"description":"Phone verification or product membership required"},"409":{"description":"Existing accounts need reconciliation"},"429":{"description":"Supabase rate limit"},"503":{"description":"Auth provider, configuration or storage unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"deviceId":{"type":"string","description":"Optional device identifier; if supplied, reuse it at every step."}}}}}},"security":[{"userBearer":[]}]}},"/api/v1/auth/phone/change/verify":{"post":{"operationId":"postApiV1AuthPhoneChangeVerify","summary":"Verify the current number's code; returns the proof the next step needs","description":"Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.","tags":["Consumer Auth"],"parameters":[{"name":"X-User-Scope","in":"header","schema":{"type":"string","enum":["jek","hk_taxi_go"],"default":"jek"},"required":false,"description":"jek (default) or hk_taxi_go. Product membership; never driver/admin permissions."}],"responses":{"200":{"description":"Success: {code:200,message:'OK',data:{...}}. Session data includes scope='user' and user_scope."},"400":{"description":"Invalid request or conflicting scopes"},"401":{"description":"Invalid/expired credential or proof"},"403":{"description":"Phone verification or product membership required"},"409":{"description":"Existing accounts need reconciliation"},"429":{"description":"Supabase rate limit"},"503":{"description":"Auth provider, configuration or storage unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token","aut_code"],"properties":{"token":{"type":"string","description":"Opaque proof from the previous step; bound to product, device and purpose, expires after 10 minutes."},"aut_code":{"type":"string","description":"The digits from the SMS. Generated, checked and expired by Supabase."},"deviceId":{"type":"string","description":"Optional device identifier; if supplied, reuse it at every step."}}}}}},"security":[{"userBearer":[]}]}},"/api/v1/auth/phone/change/send":{"post":{"operationId":"postApiV1AuthPhoneChangeSend","summary":"Send a code to the new number; repeatable to resend or correct it","description":"Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.","tags":["Consumer Auth"],"parameters":[{"name":"X-User-Scope","in":"header","schema":{"type":"string","enum":["jek","hk_taxi_go"],"default":"jek"},"required":false,"description":"jek (default) or hk_taxi_go. Product membership; never driver/admin permissions."}],"responses":{"200":{"description":"Success: {code:200,message:'OK',data:{...}}. Session data includes scope='user' and user_scope."},"400":{"description":"Invalid request or conflicting scopes"},"401":{"description":"Invalid/expired credential or proof"},"403":{"description":"Phone verification or product membership required"},"409":{"description":"Existing accounts need reconciliation"},"429":{"description":"Supabase rate limit"},"503":{"description":"Auth provider, configuration or storage unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token","new_phone"],"properties":{"token":{"type":"string","description":"Opaque proof from the previous step; bound to product, device and purpose, expires after 10 minutes."},"new_phone":{"type":"string","description":"The international number to move the account to. Must not already belong to an account."},"deviceId":{"type":"string","description":"Optional device identifier; if supplied, reuse it at every step."}}}}}},"security":[{"userBearer":[]}]}},"/api/v1/auth/phone/change/confirm":{"post":{"operationId":"postApiV1AuthPhoneChangeConfirm","summary":"Verify the new number's code; applies the change and returns the session","description":"Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.","tags":["Consumer Auth"],"parameters":[{"name":"X-User-Scope","in":"header","schema":{"type":"string","enum":["jek","hk_taxi_go"],"default":"jek"},"required":false,"description":"jek (default) or hk_taxi_go. Product membership; never driver/admin permissions."}],"responses":{"200":{"description":"Success: {code:200,message:'OK',data:{...}}. Session data includes scope='user' and user_scope."},"400":{"description":"Invalid request or conflicting scopes"},"401":{"description":"Invalid/expired credential or proof"},"403":{"description":"Phone verification or product membership required"},"409":{"description":"Existing accounts need reconciliation"},"429":{"description":"Supabase rate limit"},"503":{"description":"Auth provider, configuration or storage unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token","aut_code"],"properties":{"token":{"type":"string","description":"Opaque proof from the previous step; bound to product, device and purpose, expires after 10 minutes."},"aut_code":{"type":"string","description":"The digits from the SMS. Generated, checked and expired by Supabase."},"deviceId":{"type":"string","description":"Optional device identifier; if supplied, reuse it at every step."}}}}}},"security":[{"userBearer":[]}]}},"/api/v1/auth/account/delete/start":{"post":{"operationId":"postApiV1AuthAccountDeleteStart","summary":"Start deleting the account: send a code to the phone on it","description":"Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.","tags":["Consumer Auth"],"parameters":[{"name":"X-User-Scope","in":"header","schema":{"type":"string","enum":["jek","hk_taxi_go"],"default":"jek"},"required":false,"description":"jek (default) or hk_taxi_go. Product membership; never driver/admin permissions."}],"responses":{"200":{"description":"Success: {code:200,message:'OK',data:{...}}. Session data includes scope='user' and user_scope."},"400":{"description":"Invalid request or conflicting scopes"},"401":{"description":"Invalid/expired credential or proof"},"403":{"description":"Phone verification or product membership required"},"409":{"description":"Existing accounts need reconciliation"},"429":{"description":"Supabase rate limit"},"503":{"description":"Auth provider, configuration or storage unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"deviceId":{"type":"string","description":"Optional device identifier; if supplied, reuse it at every step."}}}}}},"security":[{"userBearer":[]}]}},"/api/v1/auth/account/delete/confirm":{"post":{"operationId":"postApiV1AuthAccountDeleteConfirm","summary":"Verify that code; schedules deletion in 30 days and signs out every device (signing in cancels it)","description":"Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.","tags":["Consumer Auth"],"parameters":[{"name":"X-User-Scope","in":"header","schema":{"type":"string","enum":["jek","hk_taxi_go"],"default":"jek"},"required":false,"description":"jek (default) or hk_taxi_go. Product membership; never driver/admin permissions."}],"responses":{"200":{"description":"Success: {code:200,message:'OK',data:{...}}. Session data includes scope='user' and user_scope."},"400":{"description":"Invalid request or conflicting scopes"},"401":{"description":"Invalid/expired credential or proof"},"403":{"description":"Phone verification or product membership required"},"409":{"description":"Existing accounts need reconciliation"},"429":{"description":"Supabase rate limit"},"503":{"description":"Auth provider, configuration or storage unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token","aut_code"],"properties":{"token":{"type":"string","description":"Opaque proof from the previous step; bound to product, device and purpose, expires after 10 minutes."},"aut_code":{"type":"string","description":"The digits from the SMS. Generated, checked and expired by Supabase."},"deviceId":{"type":"string","description":"Optional device identifier; if supplied, reuse it at every step."},"reason":{"type":"string","description":"Optional, ≤500 chars"}}}}}},"security":[{"userBearer":[]}]}},"/api/v1/auth/password/signin":{"post":{"operationId":"postApiV1AuthPasswordSignin","summary":"Alias for login","description":"Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.","tags":["Consumer Auth"],"parameters":[{"name":"X-User-Scope","in":"header","schema":{"type":"string","enum":["jek","hk_taxi_go"],"default":"jek"},"required":false,"description":"jek (default) or hk_taxi_go. Product membership; never driver/admin permissions."}],"responses":{"200":{"description":"Success: {code:200,message:'OK',data:{...}}. Session data includes scope='user' and user_scope."},"400":{"description":"Invalid request or conflicting scopes"},"401":{"description":"Invalid/expired credential or proof"},"403":{"description":"Phone verification or product membership required"},"409":{"description":"Existing accounts need reconciliation"},"429":{"description":"Supabase rate limit"},"503":{"description":"Auth provider, configuration or storage unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone","password"],"properties":{"phone":{"type":"string","description":"International phone, e.g. +852 91234567"},"password":{"type":"string","description":"New passwords require 8–128 characters and the Supabase password policy."}}}}}},"security":[]}},"/api/v1/auth/profile/complete":{"post":{"operationId":"postApiV1AuthProfileComplete","summary":"Complete a phone-verified account profile and set its password","description":"Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.","tags":["Consumer Auth"],"parameters":[{"name":"X-User-Scope","in":"header","schema":{"type":"string","enum":["jek","hk_taxi_go"],"default":"jek"},"required":false,"description":"jek (default) or hk_taxi_go. Product membership; never driver/admin permissions."}],"responses":{"200":{"description":"Success: {code:200,message:'OK',data:{...}}. Session data includes scope='user' and user_scope."},"400":{"description":"Invalid request or conflicting scopes"},"401":{"description":"Invalid/expired credential or proof"},"403":{"description":"Phone verification or product membership required"},"409":{"description":"Existing accounts need reconciliation"},"429":{"description":"Supabase rate limit"},"503":{"description":"Auth provider, configuration or storage unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["first_name","last_name","password"],"properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"password":{"type":"string","description":"New passwords require 8–128 characters and the Supabase password policy."}}}}}},"security":[{"userBearer":[]}]}},"/api/v1/auth/password/reset":{"post":{"operationId":"postApiV1AuthPasswordReset","summary":"Spend recovery proof and update Supabase password","description":"Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.","tags":["Consumer Auth"],"parameters":[{"name":"X-User-Scope","in":"header","schema":{"type":"string","enum":["jek","hk_taxi_go"],"default":"jek"},"required":false,"description":"jek (default) or hk_taxi_go. Product membership; never driver/admin permissions."}],"responses":{"200":{"description":"Success: {code:200,message:'OK',data:{...}}. Session data includes scope='user' and user_scope."},"400":{"description":"Invalid request or conflicting scopes"},"401":{"description":"Invalid/expired credential or proof"},"403":{"description":"Phone verification or product membership required"},"409":{"description":"Existing accounts need reconciliation"},"429":{"description":"Supabase rate limit"},"503":{"description":"Auth provider, configuration or storage unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token","password"],"properties":{"token":{"type":"string","description":"Opaque proof from the previous step; bound to product, device and purpose, expires after 10 minutes."},"deviceId":{"type":"string","description":"Optional device identifier; if supplied, reuse it at every step."},"password":{"type":"string","description":"New passwords require 8–128 characters and the Supabase password policy."}}}}}},"security":[]}},"/api/v1/auth/session/refresh":{"post":{"operationId":"postApiV1AuthSessionRefresh","summary":"Rotate the Supabase session","description":"Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.","tags":["Consumer Auth"],"parameters":[{"name":"X-User-Scope","in":"header","schema":{"type":"string","enum":["jek","hk_taxi_go"],"default":"jek"},"required":false,"description":"jek (default) or hk_taxi_go. Product membership; never driver/admin permissions."}],"responses":{"200":{"description":"Success: {code:200,message:'OK',data:{...}}. Session data includes scope='user' and user_scope."},"400":{"description":"Invalid request or conflicting scopes"},"401":{"description":"Invalid/expired credential or proof"},"403":{"description":"Phone verification or product membership required"},"409":{"description":"Existing accounts need reconciliation"},"429":{"description":"Supabase rate limit"},"503":{"description":"Auth provider, configuration or storage unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["refresh_token"],"properties":{"refresh_token":{"type":"string"}}}}}},"security":[]}},"/api/v1/auth/session/logout":{"post":{"operationId":"postApiV1AuthSessionLogout","summary":"Revoke the current Supabase refresh session","description":"Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.","tags":["Consumer Auth"],"parameters":[{"name":"X-User-Scope","in":"header","schema":{"type":"string","enum":["jek","hk_taxi_go"],"default":"jek"},"required":false,"description":"jek (default) or hk_taxi_go. Product membership; never driver/admin permissions."}],"responses":{"200":{"description":"Success: {code:200,message:'OK',data:{...}}. Session data includes scope='user' and user_scope."},"400":{"description":"Invalid request or conflicting scopes"},"401":{"description":"Invalid/expired credential or proof"},"403":{"description":"Phone verification or product membership required"},"409":{"description":"Existing accounts need reconciliation"},"429":{"description":"Supabase rate limit"},"503":{"description":"Auth provider, configuration or storage unavailable"}},"security":[{"userBearer":[]}]}},"/api/v1/auth/profile":{"get":{"operationId":"getApiV1AuthProfile","summary":"Read authenticated consumer profile","description":"Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.","tags":["Consumer Auth"],"parameters":[{"name":"X-User-Scope","in":"header","schema":{"type":"string","enum":["jek","hk_taxi_go"],"default":"jek"},"required":false,"description":"jek (default) or hk_taxi_go. Product membership; never driver/admin permissions."}],"responses":{"200":{"description":"Success: {code:200,message:'OK',data:{...}}. Session data includes scope='user' and user_scope."},"400":{"description":"Invalid request or conflicting scopes"},"401":{"description":"Invalid/expired credential or proof"},"403":{"description":"Phone verification or product membership required"},"409":{"description":"Existing accounts need reconciliation"},"429":{"description":"Supabase rate limit"},"503":{"description":"Auth provider, configuration or storage unavailable"}},"security":[{"userBearer":[]}]},"patch":{"operationId":"patchApiV1AuthProfile","summary":"Update the consumer's name and/or saved language","description":"Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.","tags":["Consumer Auth"],"parameters":[{"name":"X-User-Scope","in":"header","schema":{"type":"string","enum":["jek","hk_taxi_go"],"default":"jek"},"required":false,"description":"jek (default) or hk_taxi_go. Product membership; never driver/admin permissions."}],"responses":{"200":{"description":"Success: {code:200,message:'OK',data:{...}}. Session data includes scope='user' and user_scope."},"400":{"description":"Invalid request or conflicting scopes"},"401":{"description":"Invalid/expired credential or proof"},"403":{"description":"Phone verification or product membership required"},"409":{"description":"Existing accounts need reconciliation"},"429":{"description":"Supabase rate limit"},"503":{"description":"Auth provider, configuration or storage unavailable"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"first_name":{"type":"string","description":"With last_name; the pair or neither"},"last_name":{"type":"string","description":"With first_name; the pair or neither"},"preferred_lang":{"type":"string","description":"en | zh-HK | zh-CN | ja | ko (en-US, ja-JP, zh-Hant-HK… are normalised). SMS codes and ride pushes follow it. Returned on every profile and session response."}}}}}},"security":[{"userBearer":[]}]}},"/api/v1/auth/scopes":{"get":{"operationId":"getApiV1AuthScopes","summary":"Read the consumer's product memberships","description":"Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.","tags":["Consumer Auth"],"parameters":[{"name":"X-User-Scope","in":"header","schema":{"type":"string","enum":["jek","hk_taxi_go"],"default":"jek"},"required":false,"description":"jek (default) or hk_taxi_go. Product membership; never driver/admin permissions."}],"responses":{"200":{"description":"Success: {code:200,message:'OK',data:{...}}. Session data includes scope='user' and user_scope."},"400":{"description":"Invalid request or conflicting scopes"},"401":{"description":"Invalid/expired credential or proof"},"403":{"description":"Phone verification or product membership required"},"409":{"description":"Existing accounts need reconciliation"},"429":{"description":"Supabase rate limit"},"503":{"description":"Auth provider, configuration or storage unavailable"}},"security":[{"userBearer":[]}]}},"/api/v1/config/bootstrap":{"get":{"operationId":"getApiV1ConfigBootstrap","summary":"Client bootstrap configuration","description":"Public runtime config for web and native clients: API base, map keys scope, feature flags and channel branding.","tags":["Platform"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/wonder/qr-start":{"post":{"operationId":"postApiWonderQrStart","summary":"Start a Wonder QR sign-in session","description":"Returns a session id and QR payload to display. Poll /api/wonder/qr-poll until it resolves.","tags":["Platform"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/wonder/qr-poll":{"get":{"operationId":"getApiWonderQrPoll","summary":"Poll a Wonder QR sign-in session","tags":["Platform"],"parameters":[{"name":"id","in":"query","required":true,"description":"Session id from qr-start","schema":{"type":"string"}},{"name":"role","in":"query","required":false,"description":"admin | merchant | driver","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/agent/voice-extract":{"post":{"operationId":"postApiAgentVoiceExtract","summary":"Extract a ride request from a voice transcript","description":"AI helper used by the voice assistant to turn speech into structured pickup / dropoff / options. Multipart `audio` (≤8 MB), optional `origin` / `destination`. Signed-in passengers only (401 otherwise); at most 10 a minute per passenger (429); logged to AI usage.","tags":["Platform"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/geo/suggest":{"post":{"operationId":"postApiV1GeoSuggest","summary":"Smart place suggestions for the Pickup and Dropoff fields","description":"Server-owned STG Ride location primitive. With an empty `input` it recommends places before the rider types — saved Home/Work/custom places, repeated and recent trips, and real nearby points of interest, ranked by distance, recency, frequency and weekday/time-of-day (docs/25 §3). With a non-empty `input` it merges provider autocomplete with the rider's own places, keeping exact saved matches on top. Every row carries a stable `reason` code (current_location, nearby_pickup, nearby_poi, saved_home, saved_work, saved_place, recent_pickup, recent_destination, frequent_pickup, frequent_destination, repeated_route, commute_pattern, autocomplete), a `source`, `distance_m` and a QA `score`; `meta.ranking_version` names the ranking. The frontend still shows the live GPS row itself, removes what is already selected and trims to 10. The rider comes from the bearer; no user id is read from the body.","tags":["Geo"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"results":[{"place":{"placeId":"opaque","text":"IFC Mall","fullText":"8 Finance Street, Central","lat":22.28552,"lng":114.15769,"provider":"google"},"reason":"nearby_pickup","source":"nearby_poi","distance_m":120,"score":0.91}],"meta":{"ranking_version":"ride-places-v1","generated_at":"2026-08-28T01:20:00Z","has_more":true,"reasons":{"nearby_pickup":1}}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"Pickup (initial, default) or Dropoff (destination)."},"input":{"type":"string","description":"What the rider typed. Empty means 'recommend'."},"current_location":{"type":"object","description":"{ lat, lng } of the device. Top-level lat/lng is also accepted."},"pickup":{"type":"object","description":"The selected pickup place ({ lat, lng } or { placeId }) — required for useful Dropoff recommendations. `pickup_place_id` is also accepted."},"selected_place_ids":{"type":"string","description":"Place ids already chosen on the screen; excluded from the answer."},"limit":{"type":"number","description":"Candidate limit, default 20, capped at 50."},"timezone":{"type":"string","description":"IANA zone for weekday/time ranking (default Asia/Hong_Kong). Server time is authoritative."},"session_token":{"type":"string","description":"Provider autocomplete session token, echoed in meta."},"is_home_page":{"type":"boolean","description":"With empty input: put the current address first (reason current_location — the 'Depart from' label reads results[0]) and the recommendations after it."}}}}}},"security":[{"userBearer":[]}]}},"/api/v1/geo/place":{"post":{"operationId":"postApiV1GeoPlace","summary":"Resolve one place","description":"Server-owned STG Ride location primitive. The mobile client never calls the map or Wonder provider directly.","tags":["Geo"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/geo/reverse":{"post":{"operationId":"postApiV1GeoReverse","summary":"Reverse geocode coordinates","description":"Server-owned STG Ride location primitive. The mobile client never calls the map or Wonder provider directly.","tags":["Geo"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/geo/access-points":{"post":{"operationId":"postApiV1GeoAccessPoints","summary":"List pickup access points","description":"Server-owned STG Ride location primitive. The mobile client never calls the map or Wonder provider directly.","tags":["Geo"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/passenger/quotes":{"post":{"operationId":"postApiV1PassengerQuotes","summary":"Quote a trip","description":"Resolves Standard Ride places server-side, returns real Wonder quotes and persists the owned, expiring batch before responding.","tags":["Passenger"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/passenger/catalogs":{"get":{"operationId":"getApiV1PassengerCatalogs","summary":"Get ride cancellation and evaluation catalogs","description":"Authenticated passenger-trip operation used by the STG Standard Ride flow.","tags":["Passenger"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/passenger/nearby":{"post":{"operationId":"postApiV1PassengerNearby","summary":"List nearby taxis","description":"Authenticated passenger-trip operation used by the STG Standard Ride flow.","tags":["Passenger"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/passenger/serviceability":{"post":{"operationId":"postApiV1PassengerServiceability","summary":"Check pickup serviceability","description":"Authenticated passenger-trip operation used by the STG Standard Ride flow.","tags":["Passenger"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/passenger/trips/{id}/cancel-preview":{"get":{"operationId":"getApiV1PassengerTripsByIdCancelPreview","summary":"Preview trip cancellation","description":"Authenticated passenger-trip operation used by the STG Standard Ride flow.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/passenger/trips/{id}/location":{"post":{"operationId":"postApiV1PassengerTripsByIdLocation","summary":"Publish passenger location","description":"Authenticated passenger-trip operation used by the STG Standard Ride flow.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"delete":{"operationId":"deleteApiV1PassengerTripsByIdLocation","summary":"Stop sharing the passenger's location","description":"Deletes the trip's current passenger fix and clears it from the trip's tracking block, so the driver no longer sees it. Answers `{ ok: true, relayed_to_driver: false }`.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/passenger/trips/{id}/vehicle-classes":{"post":{"operationId":"postApiV1PassengerTripsByIdVehicleClasses","summary":"Add trip vehicle classes","description":"Authenticated passenger-trip operation used by the STG Standard Ride flow.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/passenger/trips/{id}/location-quote":{"post":{"operationId":"postApiV1PassengerTripsByIdLocationQuote","summary":"Quote a trip location change","description":"Authenticated passenger-trip operation used by the STG Standard Ride flow.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/passenger/trips/{id}/location-confirm":{"post":{"operationId":"postApiV1PassengerTripsByIdLocationConfirm","summary":"Confirm a trip location change","description":"Authenticated passenger-trip operation used by the STG Standard Ride flow.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/passenger/trips/{id}/evaluation":{"post":{"operationId":"postApiV1PassengerTripsByIdEvaluation","summary":"Evaluate a completed trip","description":"Authenticated passenger-trip operation used by the STG Standard Ride flow.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/passenger/trips/{id}/related-activities":{"get":{"operationId":"getApiV1PassengerTripsByIdRelatedActivities","summary":"List related trip activities","description":"Authenticated passenger-trip operation used by the STG Standard Ride flow.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/passenger/trips":{"post":{"operationId":"postApiV1PassengerTrips","summary":"Create a trip","description":"Accepts batch_id and selected_quote_ids only. Locations and prices are re-read from the caller's unexpired server-owned quote batch.","tags":["Passenger"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"get":{"operationId":"getApiV1PassengerTrips","summary":"List my trips","tags":["Passenger"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/passenger/trips/{id}":{"get":{"operationId":"getApiV1PassengerTripsById","summary":"Get a trip","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/passenger/trips/{id}/cancel":{"post":{"operationId":"postApiV1PassengerTripsByIdCancel","summary":"Cancel a trip","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/passenger/trips/{id}/pay":{"post":{"operationId":"postApiV1PassengerTripsByIdPay","summary":"Confirm trip payment and dispatch","description":"Records caller-supplied payment confirmation and then creates the Wonder taxi order. It does not charge a payment method.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/payments/charge":{"post":{"operationId":"postApiV1PaymentsCharge","summary":"Charge a payment method","tags":["Passenger"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/ride-orders":{"get":{"operationId":"getApiV1RideOrders","summary":"List ride orders","tags":["Passenger"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"post":{"operationId":"postApiV1RideOrders","summary":"Create a ride order","tags":["Passenger"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/ride-orders/{id}/cancel":{"post":{"operationId":"postApiV1RideOrdersByIdCancel","summary":"Cancel a ride order","description":"For a Wonder order id, focus=false previews cancellation, focus=true confirms it, and submit_reason_only=true submits post-cancel feedback. Native UUID orders use the migration dispatcher.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"focus":{"type":"boolean"},"submit_reason_only":{"type":"boolean"},"cancel_type":{"type":"string"},"cancel_remark":{"type":"string"}}}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/rides":{"post":{"operationId":"postApiV1MeRides","summary":"Request a ride (Make a Wish)","description":"Creates a ride request with optional wish text/audio, analysis metadata and tip. Send vehicle_class_ids to accept several classes at once and be matched by whichever driver turns up first: the selection is priced HERE and the passenger is charged the DEAREST of it, so the fare is covered whichever class arrives. The request's own `fare` is not consulted for a selection — a caller who named its own total would also get to decide which class counted as dearest. Send duration_min alongside it, or the reprice drops the per-minute component and lands under the quote you showed. Refuses a pickup whose service area is fulfilled by PARTNER capacity with 422 `PARTNER_FULFILMENT_REQUIRED`, carrying `fulfilment` and `fulfilment_area`: that market is served by a third party through Wonder, and this lane has no payment gateway to buy it with. Call /api/v1/ride/preflight first to learn which fulfilment applies.","tags":["Passenger"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pickup":{"type":"string"},"dropoff":{"type":"string"},"distance_km":{"type":"number"},"duration_min":{"type":"number","description":"Send it whenever per-minute rates apply, so the charge matches POST /api/v1/ride/quote."},"vehicle_class_ids":{"type":"string","description":"Classes this ride will accept, max 6. Priced here; the passenger is charged the dearest, and it becomes the ride's vehicle label. Widen later with POST /api/v1/me/rides/{id}/vehicle-classes."},"fare":{"type":"number","description":"What was displayed. Ignored when vehicle_class_ids is sent."},"order_type":{"type":"string"},"card_scheme":{"type":"string","description":"visa | mastercard | amex | unionpay | jcb — with `payment_method: vault-<card>`, so a card-scheme payment offer can apply (native apps only; see POST /api/v1/ride/price). A ride booked with an offer must be paid that way."},"quote":{"type":"object","description":"The signed quote from the wish analysis — what a wish is charged against."}},"required":["pickup","dropoff"]}}}},"security":[{"userBearer":[]}]},"get":{"operationId":"getApiV1MeRides","summary":"List the caller's rides (account surface)","description":"Rides and wishes together, newest first. History is paged by an opaque keyset cursor: echo `next_cursor` back as `?cursor=` for the next page, and stop when it comes back null. `limit` defaults to 50 and caps at 100. `?active=1` answers only the orders still in flight and is deliberately NOT paged. A `cursor` this endpoint did not issue is refused with 400 `invalid_cursor` rather than silently restarting at the newest row.","tags":["Rides"],"parameters":[{"name":"active","in":"query","required":false,"description":"1|true|yes — in-flight orders only, unpaged.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"1–100, default 50. History only.","schema":{"type":"number"}},{"name":"cursor","in":"query","required":false,"description":"Opaque; the previous page's next_cursor.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":[{"id":"…","order_type":"ride","status":"completed"}],"next_cursor":"MjAyNi0wOS0wMVQxMjowMDowMC4wMDBafGFiYw","has_more":true,"limit":50,"max_limit":100}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/da/wishes":{"get":{"operationId":"getApiV1DaWishes","summary":"List open wishes near the driver","description":"The driver's whole wish surface in one read: `data` is the open pool (no driver yet), `mine` is every wish the caller holds in any state, and `can_accept` says whether a claim from this driver would be allowed at all. Rows are sanitised for the driver — the passenger's `fare` and the `wish.pricing` pin are stripped — and only `mine` carries passenger contact details.","tags":["Driver Assistant"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/wishes/{id}/accept":{"post":{"operationId":"postApiV1DaWishesByIdAccept","summary":"Accept a wish","description":"Claims a wish, first driver wins via a conditional update on `driver_id`. Returns `{ data, served_vehicle_class, refunded? }` where `data` is the full claimed wish row with `status: \"accepted\"` — clients render from it rather than re-reading the feed. Refuses with 403 when the driver is not eligible to take work or their active vehicle serves no class the order accepts, and 409 \"Wish already taken\" when another driver got there first. Unlike the list endpoint, the row returned here is RAW, so a driver-facing relay must strip `fare` and `wish.pricing` itself.","tags":["Driver Assistant"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/public/explore-merchants":{"get":{"operationId":"getApiPublicExploreMerchants","summary":"Merchants for the Explore map","tags":["Public"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/public/merchant-detail":{"get":{"operationId":"getApiPublicMerchantDetail","summary":"Public merchant profile","tags":["Public"],"parameters":[{"name":"slug","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/public/social-summary":{"post":{"operationId":"postApiPublicSocialSummary","summary":"AI summary of a merchant's public reviews","tags":["Public"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/public/v1/dispatch/orders":{"post":{"operationId":"postApiPublicV1DispatchOrders","summary":"Create a dispatch order from a demand platform","description":"Token-authenticated integration endpoint. All channels funnel into the same supplier order queue.","tags":["Dispatch"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/public/v1/dispatch/orders/{id}/cancel":{"post":{"operationId":"postApiPublicV1DispatchOrdersByIdCancel","summary":"Cancel a dispatch order","tags":["Dispatch"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/v1/da/me":{"get":{"operationId":"getApiV1DaMe","summary":"Driver profile & onboarding state","description":"Returns the signed-in driver, their vehicles, documents and an onboarding checklist. The profile is provisioned automatically on first call.","tags":["Driver Assistant"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"driver":{"id":"…","display_name":"Chan Tai Man","status":"active","is_online":false},"onboarding":{"has_vehicle":true,"has_licence":true,"approved":true,"suspended":false,"status":"active","can_take_work":true}}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]},"patch":{"operationId":"patchApiV1DaMe","summary":"Update driver profile","tags":["Driver Assistant"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"display_name":{"type":"string"},"phone_e164":{"type":"string"}}}}}},"security":[{"driverBearer":[]}]}},"/api/v1/da/me/online":{"post":{"operationId":"postApiV1DaMeOnline","summary":"Go online / offline","description":"Only approved drivers with an active vehicle may go online.","tags":["Driver Assistant"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"is_online":{"type":"boolean"}},"required":["is_online"]}}}},"security":[{"driverBearer":[]}]}},"/api/v1/da/vehicles":{"get":{"operationId":"getApiV1DaVehicles","summary":"List the driver's vehicles","tags":["Driver Assistant"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]},"post":{"operationId":"postApiV1DaVehicles","summary":"Register a vehicle","tags":["Driver Assistant"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plate_number":{"type":"string"},"model_name":{"type":"string"},"color":{"type":"string"},"seats":{"type":"number"},"vehicle_type_code":{"type":"string","description":"Single-class spelling of vehicle_type_codes. Still accepted."},"vehicle_type_codes":{"type":"string","description":"Every class this vehicle is approved to serve, e.g. [\"Standard Taxi\",\"Premium Taxi\"]. On an order accepting several classes the driver is paid for the DEAREST of these the order also accepts, and cannot accept an order with none of them. A vehicle that declares nothing is unrestricted, exactly as before. vehicle_type_code is set to the first of the set. Max 8."}},"required":["plate_number"]}}}},"security":[{"driverBearer":[]}]}},"/api/v1/da/vehicles/{id}":{"patch":{"operationId":"patchApiV1DaVehiclesById","summary":"Update or activate a vehicle","description":"Send is_active=true to make this the vehicle used for new orders. Sending vehicle_type_codes REPLACES the approved class set rather than adding to it, so a class claimed in error can be taken back.","tags":["Driver Assistant"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"is_active":{"type":"boolean"},"plate_number":{"type":"string"},"model_name":{"type":"string"},"color":{"type":"string"},"seats":{"type":"number"},"vehicle_type_code":{"type":"string"},"vehicle_type_codes":{"type":"string"}}}}}},"security":[{"driverBearer":[]}]},"delete":{"operationId":"deleteApiV1DaVehiclesById","summary":"Remove a vehicle","tags":["Driver Assistant"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/documents/upload-url":{"post":{"operationId":"postApiV1DaDocumentsUploadUrl","summary":"Signed upload URL for a document","description":"Returns a short-lived URL; PUT the file to it, then register it with POST /api/v1/da/documents.","tags":["Driver Assistant"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"doc_type":{"type":"string","description":"driving_licence | vehicle_registration | insurance | id_card | other"},"file_name":{"type":"string"}},"required":["doc_type","file_name"]}}}},"security":[{"driverBearer":[]}]}},"/api/v1/da/documents":{"post":{"operationId":"postApiV1DaDocuments","summary":"Submit a document for review","tags":["Driver Assistant"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"doc_type":{"type":"string"},"storage_path":{"type":"string"},"document_number":{"type":"string"},"expires_on":{"type":"string"}},"required":["doc_type","storage_path"]}}}},"security":[{"driverBearer":[]}]},"get":{"operationId":"getApiV1DaDocuments","summary":"List submitted documents","tags":["Driver Assistant"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/offers":{"get":{"operationId":"getApiV1DaOffers","summary":"Pending order offers","description":"Live offers for the signed-in driver. Empty while offline or when onboarding is incomplete.","tags":["Driver Assistant"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/offers/{id}/accept":{"post":{"operationId":"postApiV1DaOffersByIdAccept","summary":"Accept an offer","description":"First accept wins; a losing caller receives 409 Order already taken.","tags":["Driver Assistant"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/offers/{id}/decline":{"post":{"operationId":"postApiV1DaOffersByIdDecline","summary":"Decline an offer","tags":["Driver Assistant"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}},"security":[{"driverBearer":[]}]}},"/api/v1/da/orders/active":{"get":{"operationId":"getApiV1DaOrdersActive","summary":"Current in-flight order","tags":["Driver Assistant"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/orders/{id}/status":{"post":{"operationId":"postApiV1DaOrdersByIdStatus","summary":"Advance the order state","description":"accepted → arrived → in_trip → completed (cancel allowed before in_trip). Completing an order writes the earnings row and mirrors the state to the rider platform.","tags":["Driver Assistant"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string"},"reason":{"type":"string"}},"required":["state"]}}}},"security":[{"driverBearer":[]}]}},"/api/v1/da/orders":{"get":{"operationId":"getApiV1DaOrders","summary":"Order history","tags":["Driver Assistant"],"parameters":[{"name":"state","in":"query","required":false,"schema":{"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/location":{"post":{"operationId":"postApiV1DaLocation","summary":"Location ping","description":"Updates the driver's live position and, when on a trip, the trail shown to the rider.","tags":["Driver Assistant"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"latitude":{"type":"number"},"longitude":{"type":"number"},"heading":{"type":"number"},"speed_kph":{"type":"number"},"accuracy_m":{"type":"number"}},"required":["latitude","longitude"]}}}},"security":[{"driverBearer":[]}]}},"/api/v1/da/push-tokens":{"post":{"operationId":"postApiV1DaPushTokens","summary":"Register the driver's device for JEK pushes","description":"Enrolls native APNs/FCM devices in Wonder Replyx. Requires the sealed x-da-session; app, account and environment are server-derived. No app secret is returned. Staging and production are isolated; alpha has no configured Replyx app. DELETE ?registration_id= retires the exact caller/session binding; revoked sessions cannot receive future notifications.","tags":["Driver Assistant"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","description":"replyx"},"device_id":{"type":"string"},"push_token":{"type":"string","description":"Native APNs or FCM token"},"platform":{"type":"string","description":"ios | android"}},"required":["provider","device_id","push_token","platform"]}}}},"security":[{"driverBearer":[]}]},"delete":{"operationId":"deleteApiV1DaPushTokens","summary":"Retire a push token","description":"Soft-deletes the caller's own row for the given Expo token, typically on sign-out.","tags":["Driver Assistant"],"parameters":[{"name":"expo_token","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"ok":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/earnings":{"get":{"operationId":"getApiV1DaEarnings","summary":"Earnings summary and line items","description":"Minor units. Lines carry `source`: `order` (partner orders), `wish`, `ride`, and `tip` — each collected, unrefunded passenger tip as its own line, 100% to the driver, the same figure settlement pays. Tips count in `today_net` / `week_net` but not in `trips_today`. Days and weeks are Hong Kong's. With `from` (and `to`, default now) the read is a window: every line earned in it, unpaged (cap 2000, `meta.truncated`).","tags":["Driver Assistant"],"parameters":[{"name":"from","in":"query","required":false,"description":"Window start; makes the read unpaged","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"Window end, exclusive (default now)","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/next-payout":{"get":{"operationId":"getApiV1DaNextPayout","summary":"What tonight's settlement run is expected to pay the driver","description":"Read-only forecast that mirrors the nightly settlement run (00:00–00:59 HKT): `expected_minor` (accrued, payable legs the run will batch plus open batches not under review, less open clawbacks; per business in `businesses`), `held` (with a reason: `receipt_review`, `passenger_payment`, `partner_unpaid`, `under_review`, `payout_failed`, `account_issue`, `checking`), and `sending_minor` (transfers Wonder has not answered). `status` is `settling` during the run's hour, else `scheduled`; `run_at` is that run's start. Scoped to the caller's environment (alpha + production together). Subject to the run's final checks — the paying account's balance and Wonder's answer are only known then.","tags":["Driver Assistant"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/public/v1/health":{"get":{"operationId":"getApiPublicV1Health","summary":"Health probe","tags":["Platform"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}},"security":[]}},"/api/public/v1/merchants":{"get":{"operationId":"getApiPublicV1Merchants","summary":"List merchants","description":"Search & filter public merchant directory.","tags":["Merchants"],"parameters":[{"name":"q","in":"query","schema":{"type":"string"},"required":false,"description":"Free-text search"},{"name":"cuisine","in":"query","schema":{"type":"string"},"required":false},{"name":"limit","in":"query","schema":{"type":"integer","maximum":200,"default":50},"required":false,"description":"1–200, default 50"}],"responses":{"200":{"description":"Merchant list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Merchant"}}}}}}}},"security":[]}},"/api/public/v1/merchants/{slug}":{"get":{"operationId":"getApiPublicV1MerchantsBySlug","summary":"Merchant detail","tags":["Merchants"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Merchant","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Merchant"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[]}},"/api/public/v1/vouchers":{"get":{"operationId":"getApiPublicV1Vouchers","summary":"List vouchers","description":"Published merchant vouchers, soonest-ending first (≤200). `?merchant_id` narrows to one merchant's own vouchers and the ones linked to it. `starts_at` / `ends_at` are the voucher's validity window. To hold one, claim it: POST /api/v1/me/vouchers/claim.","tags":["Promotions"],"parameters":[{"name":"merchant_id","in":"query","schema":{"type":"string"},"required":false}],"responses":{"200":{"description":"Voucher list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Voucher"}}}}}}}},"security":[]}},"/api/public/v1/promotions":{"get":{"operationId":"getApiPublicV1Promotions","summary":"Active promotions","description":"Published vouchers running now: started, and not ended (`ends_at` null means open-ended). Soonest-ending first, ≤100.","tags":["Promotions"],"parameters":[],"responses":{"200":{"description":"Active vouchers","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Voucher"}}}}}}}},"security":[]}},"/api/public/v1/ride/vehicle-types":{"get":{"operationId":"getApiPublicV1RideVehicleTypes","summary":"Available vehicle types","description":"The rate card, already in the order a passenger should read it: Standard, Express, Meter, 85% Meter, Premium, 6-seater, Wheelchair, Extra Luggage, then anything else by name. Render the array as it arrives. A client that must re-sort may only sort by `sort_order` — the operator's own ordering from /admin/ride/vehicle-types, which this response already honours — never by name or price, which is a different running order for the app.","tags":["Ride"],"parameters":[],"responses":{"200":{"description":"Vehicle types, in display order","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/VehicleType"}}}}}}}},"security":[]}},"/api/v1/ride/price":{"post":{"operationId":"postApiV1RidePrice","summary":"What paying this way would cost (coupon + payment offer)","description":"The legacy price_calculator, from JEK's own rules: the dearest fare of the selection, less the coupon (the booking's own test), less the payment offer for `payment_method` / `card_scheme`, plus `tip` (never discounted). The fare is priced from exactly one basis: `quote_ref` (a signed /api/v1/ride/quote answer — verified like the booking verifies it and re-priced from the card; 409 `QUOTE_STALE` / `QUOTE_INVALID` exactly where the booking would refuse it), `ride_id` (one of the caller's own rides — its booked `fare`, with any coupon it already spent; another passenger's ride is 404), or `vehicle_class_ids` + `distance_km`. Returns `{currency, basis, fare, coupon, payment_offer, tip, amount_due, lines[], estimate: true}`. A preview — nothing is spent; the booking decides again. Payment offers are only offered to callers that declare `x-jek-env` (the native apps), because only their pay routes can hold the method; a ride booked with an offer is refused by /pay, /pay/wallet and /pay/native-wallet with 409 PAYMENT_OFFER_METHOD_MISMATCH when paid another way.","tags":["Ride"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"quote_ref":{"type":"string","description":"Signed quote from POST /api/v1/ride/quote. Not with ride_id."},"ride_id":{"type":"string","description":"One of the caller's own rides. Not with quote_ref."},"vehicle_class_ids":{"type":"string","description":"Required without quote_ref / ride_id; with quote_ref, narrows the quoted classes"},"distance_km":{"type":"number","description":"Required without quote_ref / ride_id"},"duration_min":{"type":"number"},"tip":{"type":"number","description":"Added after every discount"},"coupon_code":{"type":"string"},"payment_method":{"type":"string","description":"vault-<card> | card | applepay | googlepay | a wallet id"},"card_scheme":{"type":"string","description":"visa | mastercard | amex | unionpay | jcb"}}}}}},"security":[{"userBearer":[]}]}},"/api/v1/ride/quote":{"post":{"operationId":"postApiV1RideQuote","summary":"Estimate ride fare","description":"Prices one vehicle type, or a whole selection. Send vehicle_class_ids to price several at once: the response adds `authorize`, the dearest of them, which is what the passenger pre-authorises so that whichever driver accepts, the fare is already covered. The selection is priced in one call on purpose — quoting each class separately would let the client decide which counted as dearest. A quote takes up to 24 ids — the whole rate card, so a price list is one call, no batching — while a booking accepts at most 6; the response echoes that as vehicle_class_limit. A class can have a MINIMUM FARE — 85% Meter Taxi is not offered below HKD 90, because a discounted short trip is a job no driver takes. On a trip that prices under it the class is dropped from `quotes` and listed in `withheld` with the floor it missed, so a price list drawn from `quotes` loses the row by itself. 400 BELOW_CLASS_MINIMUM when nothing clears its floor, or when vehicle_type_id named such a class; POST /api/v1/me/rides refuses the same class with the same code rather than dropping it, so a stale screen cannot book one. A multi-class quote also carries `coupon` — the best usable coupon on the dearest fare (largest discount, priced by the same test the booking runs), marked `estimate: true` because the booking prices it on the fare it actually authorises — and `coupon_quotes`, the price list with that coupon's effect per class. `authorize`, `quotes` and `quote_ref` stay undiscounted; to use the coupon, send its code as `coupon_code` to POST /api/v1/me/rides. `coupon: false` skips the lookup. JEK (docs/71 W1): a multi-class quote also carries `kash {balance, redeemable_max, earn_estimate}` — the passenger's JEK Kash, the most this booking could redeem (capped by the rules; 0 for the 85% meter taxi) and what the dearest class would earn — or null when Kash is off or the caller is not in the JEK app. An estimate; redeem with `kash_amount` on POST /api/v1/me/rides.","tags":["Ride"],"parameters":[],"responses":{"200":{"description":"Quote","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"oneOf":[{"$ref":"#/components/schemas/RideQuote"},{"$ref":"#/components/schemas/RideSelectionQuote"}]}}}}}},"400":{"description":"distance_km missing, no selector, mixed currencies, or more than 24 class ids (the error names the limit)"},"404":{"description":"Unknown vehicle type or class id"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["distance_km"],"description":"Exactly one of vehicle_type_id or vehicle_class_ids.","properties":{"vehicle_type_id":{"type":"string","format":"uuid","description":"One class. Omit when sending vehicle_class_ids."},"vehicle_class_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":24,"description":"Several classes, priced together. Max 24 per quote; a booking accepts at most 6."},"distance_km":{"type":"number"},"duration_min":{"type":"number"}}}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/rides/{id}/vehicle-classes":{"post":{"operationId":"postApiV1MeRidesByIdVehicleClasses","summary":"Accept more vehicle classes while waiting","description":"Widens what an unmatched ride will accept. Only the DIFFERENCE is charged — the passenger already authorised the previous dearest class, so a cheaper addition costs nothing and a dearer one costs the gap. Widening only: classes are never removed, because that could strand a driver already on the way. 409 once a driver has taken it.","tags":["Ride"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{},"added":["…"],"charged":32,"authorized_total":152}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicle_class_ids":{"type":"string"}},"required":["vehicle_class_ids"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/rides/{id}/boost":{"post":{"operationId":"postApiV1MeRidesByIdBoost","summary":"Add money to an unmatched order","description":"Raises the fare on an order no driver has taken. Wishes and ordinary rides both. Refused once a driver is attached.","tags":["Ride"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number"}},"required":["amount"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/rides":{"get":{"operationId":"getApiV1Rides","summary":"Signed-in user's ride history","tags":["Ride"],"parameters":[],"responses":{"200":{"description":"Rides","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}}}}}}}},"security":[{"userBearer":[]}]}},"/api/v1/me":{"get":{"operationId":"getApiV1Me","summary":"Current user + profile","tags":["Account"],"parameters":[],"responses":{"200":{"description":"Me","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"profile":{"$ref":"#/components/schemas/Profile"}}}}}}}}},"security":[{"userBearer":[]}]}},"/api/v1/merchant/me":{"get":{"operationId":"getApiV1MerchantMe","summary":"Signed-in merchant record","tags":["Merchant Dashboard"],"parameters":[],"responses":{"200":{"description":"Merchant"}},"security":[{"merchantBearer":[]}]}},"/api/v1/merchant/vouchers":{"get":{"operationId":"getApiV1MerchantVouchers","summary":"Vouchers owned by signed-in merchant","tags":["Merchant Dashboard"],"parameters":[],"responses":{"200":{"description":"Vouchers"}},"security":[{"merchantBearer":[]}]},"post":{"operationId":"postApiV1MerchantVouchers","summary":"Create voucher","tags":["Merchant Dashboard"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"merchantBearer":[]}]}},"/api/public/v1/merchants/{slug}/socials":{"get":{"operationId":"getApiPublicV1MerchantsBySlugSocials","summary":"Merchant social profiles","tags":["Merchants"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/public/v1/chains/{id}":{"get":{"operationId":"getApiPublicV1ChainsById","summary":"Chain detail + member merchants","tags":["Merchants"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/public/v1/maps-config":{"get":{"operationId":"getApiPublicV1MapsConfig","summary":"Public Google Maps browser key + tracking ID","tags":["Platform"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/public/v1/openapi":{"get":{"operationId":"getApiPublicV1Openapi","summary":"OpenAPI 3.1 spec (JSON)","tags":["Platform"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/v1/me/activity":{"get":{"operationId":"getApiV1MeActivity","summary":"Recent transactions, rides, rewards","tags":["Account"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"delete":{"operationId":"deleteApiV1MeActivity","summary":"Remove rides from the caller's ride history","description":"Hides rides from the caller's own lists by stamping `passenger_hidden_at`; the ride row is kept, because it is also the driver's earnings record and the operator's audit trail. Name rides with `ride_id`, `ride_ids` or `all: true` (there is no default; `all` hides only finished rides). A named in-flight ride is refused with 409 and nothing in the batch is hidden; a ride that is not the caller's is 404 `RIDE_NOT_FOUND`. Answers `{ deleted, hidden, ids, refused }`; 503 `HISTORY_HIDE_UNAVAILABLE` on a database without the column.","tags":["Account"],"parameters":[{"name":"ride_id","in":"query","required":false,"description":"Alternative to the body for clients that cannot send a body on DELETE","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"ride_id":{"type":"string","description":"One ride to hide"},"ride_ids":{"type":"string","description":"Several rides to hide; validated as a whole before anything is written"},"all":{"type":"boolean","description":"true hides every finished ride (completed / cancelled / expired)"}}}}}},"security":[{"userBearer":[]}]}},"/api/v1/merchant/onboard":{"post":{"operationId":"postApiV1MerchantOnboard","summary":"Claim / register a merchant profile","tags":["Merchant Dashboard"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/merchant/vouchers/{id}":{"patch":{"operationId":"patchApiV1MerchantVouchersById","summary":"Update voucher","tags":["Merchant Dashboard"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"merchantBearer":[]}]},"delete":{"operationId":"deleteApiV1MerchantVouchersById","summary":"Delete voucher","tags":["Merchant Dashboard"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"merchantBearer":[]}]}},"/api/v1/me/contacts":{"post":{"operationId":"postApiV1MeContacts","summary":"Bulk upload contacts from a JEK user's phone","description":"Accepts a batch of contacts (name + phone(s) + optional emails), normalizes each phone to E.164 using the provided default_country (e.g. \"852\"), and upserts them into jek_user_contacts scoped to the caller. Safe to call repeatedly — duplicates are merged by (user_id, phone_e164).","tags":["Contacts"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"inserted":123,"total":456}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contacts":{"type":"string"},"default_country":{"type":"string","description":"E.g. \"852\" for HK, \"853\" for Macau"},"source":{"type":"string","description":"\"phone\" | \"upload\" | free-form"}},"required":["contacts"]}}}},"security":[{"userBearer":[]}]},"get":{"operationId":"getApiV1MeContacts","summary":"List uploaded contacts with on-JEK match","description":"Returns the caller's uploaded contacts. Each contact carries an on_jek flag computed by matching phone_e164 against the JEK user directory server-side (via SECURITY DEFINER — no direct DB read from the client).","tags":["Contacts"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"total":456,"on_jek_count":87,"contacts":[{"id":"…","display_name":"Ada","phone":"+85268880042","emails":[],"source":"phone","on_jek":true,"uploaded_at":"…"}]}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"delete":{"operationId":"deleteApiV1MeContacts","summary":"Clear all uploaded contacts (soft-delete)","tags":["Contacts"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/referral":{"get":{"operationId":"getApiV1MeReferral","summary":"List the caller's invite codes (auto-creates a default)","description":"Returns every active referral code the user owns plus the default one, each with invite.jek.app URL and WhatsApp/SMS share links. First call for a user lazily allocates a random 8-char default code (collision-safe).","tags":["Contacts"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"default":{"id":"…","code":"K4TR9M2P","is_default":true,"label":"Default","visit_count":0,"signup_count":0,"invite_url":"https://invite.jek.app/?ref=K4TR9M2P"},"codes":[{"id":"…","code":"K4TR9M2P","is_default":true,"label":"Default"}],"code":"K4TR9M2P","invite_url":"https://invite.jek.app/?ref=K4TR9M2P"}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"post":{"operationId":"postApiV1MeReferral","summary":"Create an additional invite code (campaign / channel)","description":"Allocates a new random code owned by the caller. Useful for influencers or marketing campaigns that need to attribute installs per channel. Set make_default=true to promote it to the primary code.","tags":["Contacts"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","description":"Human label, e.g. 'Instagram'."},"campaign":{"type":"string"},"make_default":{"type":"boolean"}}}}}},"security":[{"userBearer":[]}]},"patch":{"operationId":"patchApiV1MeReferral","summary":"Promote a code to default, or soft-delete it","tags":["Contacts"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"action":{"type":"string"}},"required":["id","action"]}}}},"security":[{"userBearer":[]}]}},"/api/public/referral-lookup":{"get":{"operationId":"getApiPublicReferralLookup","summary":"Validate a referral code (public)","description":"Called by invite.jek.app to confirm an inbound ?ref=CODE is real before showing it to the visitor and setting the attribution cookie. Never returns the owner's identity.","tags":["Contacts"],"parameters":[{"name":"code","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"valid":true,"code":"K4TR9M2P","label":"Default","campaign":null}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/public/referral-visit":{"post":{"operationId":"postApiPublicReferralVisit","summary":"Track a visit to invite.jek.app for attribution","description":"Called by the invite.jek.app landing page whenever it loads with a valid ?ref=CODE. Increments the code's visit_count and records platform (ios/android/web), source, referrer and user-agent.","tags":["Contacts"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"platform":{"type":"string"},"source":{"type":"string"},"referrer":{"type":"string"}},"required":["code"]}}}},"security":[]}},"/api/v1/me/messaging/conversations":{"get":{"operationId":"getApiV1MeMessagingConversations","summary":"List the caller's conversations (inbox)","description":"Returns every conversation the user is a member of, ordered by last_message_at. Each entry carries last_message_preview, unread_count, member list, and type (dm/group/agent/support).","tags":["Messaging"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"post":{"operationId":"postApiV1MeMessagingConversations","summary":"Start a DM, group, or JEK Assistant thread","description":"Provide type='agent' for the auto-created JEK Assistant thread (idempotent — returns the existing one), user_id for a 1:1 DM with a JEK user, phone for a DM by phone number (creates the counterparty stub if needed), or type='group' with member_ids for a new group chat. JEK (docs/71 C1a): a DM to someone who has not saved you as a contact (and has no accepted DM with you) starts as a MESSAGE REQUEST (`request_status: requested`) the recipient accepts or declines with PATCH /api/v1/me/messaging/conversations/{id}; a blocked pair is refused (403 CANNOT_MESSAGE). Groups can only include people you can already chat with.","tags":["Messaging"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"user_id":{"type":"string"},"phone":{"type":"string"},"title":{"type":"string"},"member_ids":{"type":"string"}}}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/messaging/conversations/{id}":{"get":{"operationId":"getApiV1MeMessagingConversationsById","summary":"Fetch conversation detail + message page","description":"Returns the conversation, its members, and the most recent `limit` messages (default 50). Pass `before` (ISO timestamp) for pagination to older messages.","tags":["Messaging"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"string"}},{"name":"before","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"patch":{"operationId":"patchApiV1MeMessagingConversationsById","summary":"Mark read, or answer a message request","description":"No body (or `{}`): marks the conversation read. `{request: \"accept\" | \"decline\"}` (docs/71 C1a): the RECIPIENT of a message request answers it → `{ok, request_status}`. Until accepted, the requester may send one text message only (403 REQUEST_PENDING); a declined request refuses further messages (403 REQUEST_DECLINED).","tags":["Messaging"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"request":{"type":"string"}}}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/messaging/conversations/{id}/messages":{"post":{"operationId":"postApiV1MeMessagingConversationsByIdMessages","summary":"Send a message (text, image, file, voice)","description":"Set kind='text' (default) for plain text. For attachments upload via POST /api/v1/me/messaging/attachments first, then send kind='image'|'file'|'voice' with the returned path in attachments. Mentioning @jek in a non-agent conversation triggers a JEK Assistant reply from the fan-out job. JEK gifts (docs/71 C2): kind='voucher' with `metadata.coupon_code` (or the app's `attachments[0].code`) shares a code — nothing moves, the server snapshots it into `metadata.voucher` (`unverified:true` when unknown); with `metadata.user_voucher_id` it TRANSFERS an owned voucher to the other person. kind='kash' with `metadata.kash.amount` or `attachments[0].amount` (HK$, optional `metadata.request_id`) gifts JEK Kash, written back into both. Value gifts need an accepted one-to-one chat: 403 GIFT_NEEDS_ACCEPTED_CHAT / NOT_YOUR_VOUCHER / KASH_OFF, 409 VOUCHER_NOT_TRANSFERABLE / KASH_INSUFFICIENT / KASH_GIFT_LIMIT. End-to-end encrypted chats (docs/71 C1b, the conversation's `e2e: true`): text and media are refused here (400 E2E_REQUIRED) — send them encrypted with POST …/e2e-messages; voucher, kash and trip still go through this route.","tags":["Messaging"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string"},"kind":{"type":"string"},"reply_to_id":{"type":"string"},"attachments":{"type":"string"},"metadata":{"type":"object"}},"required":["body"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/messaging/conversations/{id}/typing":{"post":{"operationId":"postApiV1MeMessagingConversationsByIdTyping","summary":"Broadcast a typing indicator (3s TTL)","description":"Fires a lightweight realtime event other members receive within ~200ms. Client should debounce — call at most once every 3 seconds while the user is actively typing.","tags":["Messaging"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/messaging/attachments":{"post":{"operationId":"postApiV1MeMessagingAttachments","summary":"Request a signed upload URL for a chat attachment","description":"Returns a one-shot signed URL you can PUT the raw file to directly (never rehashed through the Worker). Returns the storage path to include in the subsequent POST /messages call. Bucket is private — read access is signed on demand via GET /attachments?path=...","tags":["Messaging"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"bucket":"chat-attachments","path":"<conv>/<user>/1729-abc-photo.jpg","upload_url":"https://…storage/v1/…?token=…","token":"…","read_url_expires_in":3600}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"conversation_id":{"type":"string"},"filename":{"type":"string"}},"required":["conversation_id","filename"]}}}},"security":[{"userBearer":[]}]},"get":{"operationId":"getApiV1MeMessagingAttachments","summary":"Sign a read URL for an existing attachment path","tags":["Messaging"],"parameters":[{"name":"path","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/messaging/candidates":{"get":{"operationId":"getApiV1MeMessagingCandidates","summary":"List uploaded contacts who are already on JEK","description":"Cross-references the caller's uploaded contacts with jek_account_users to power the New Chat picker. Returns [{ user_id, name, phone }].","tags":["Messaging"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/public/v1/app-config":{"get":{"operationId":"getApiPublicV1AppConfig","summary":"Must this app update, may it, and is the service in maintenance (public)","description":"Called at startup, before sign-in. `update`: `required` below min_version (or at it with a build below min_build), `optional` below latest_version, else `none`. `maintenance.active` when switched on or inside its window; `upcoming` when a window starts within 7 days. Fails open: no config, an unconfigured platform or a malformed version answers `update:\"none\"` and no maintenance. Unknown `app`/`platform` is 400. Cached 60 s.","tags":["Account"],"parameters":[{"name":"app","in":"query","required":false,"description":"Default jek","schema":{"type":"string"}},{"name":"platform","in":"query","required":true,"schema":{"type":"string"}},{"name":"version","in":"query","required":false,"description":"The app's version, e.g. 2.0.5","schema":{"type":"string"}},{"name":"build","in":"query","required":false,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"update":"optional","min_version":"2.0.3","latest_version":"2.0.6","store_url":"https://apps.apple.com/app/…","maintenance":{"active":false,"upcoming":false,"starts_at":null,"ends_at":null,"message":{}}}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/public/v1/push-config":{"get":{"operationId":"getApiPublicV1PushConfig","summary":"VAPID public key + service worker path (public)","description":"Browsers call this to obtain the VAPID applicationServerKey before subscribing to Web Push. Also returns the service worker path (/sw.js).","tags":["Push"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"vapid_public_key":"BFA…","service_worker":"/sw.js"}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/v1/me/push-tokens":{"post":{"operationId":"postApiV1MePushTokens","summary":"Register a Web Push subscription or Expo push token","description":"For web, pass { platform: 'web', endpoint, p256dh, auth } from PushSubscription.toJSON(). For native, pass { platform: 'ios' | 'android', expo_token } from expo-notifications' getExpoPushTokenAsync(). Upsert is de-duped by endpoint / expo_token so it's safe to call on every app start.","tags":["Push"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string"},"endpoint":{"type":"string"},"p256dh":{"type":"string"},"auth":{"type":"string"},"expo_token":{"type":"string"}}}}}},"security":[{"userBearer":[]}]},"delete":{"operationId":"deleteApiV1MePushTokens","summary":"Unregister a push token (on sign-out or permission revoke)","tags":["Push"],"parameters":[{"name":"endpoint","in":"query","required":false,"schema":{"type":"string"}},{"name":"expo_token","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/helper/generate-pdf":{"post":{"operationId":"postApiHelperGeneratePdf","summary":"Generate a JEK PDF for the caller's Wonder ride","description":"Accepts { order_id, locale? }. Requires a JEK bearer, JEK scope, X-JEK-Env and the caller's reconciled Wonder customer session. Reads the order server-side, renders in JEK and returns { url, expiresIn: 600 } from private jek-receipts storage. Caller-supplied fileData, template, folder and financial figures are refused.","tags":["JEK Receipts"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/saved-places":{"get":{"operationId":"getApiV1MeSavedPlaces","summary":"List the caller's saved places","description":"Home, Work and custom places, in the rider's display order. `meta.max_places` is the ceiling. Each place carries the normalized `{ placeId, text, fullText, lat, lng, provider }` that /api/v1/geo/place answers with, so it can be booked without a second resolve.","tags":["Saved Places"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":[{"id":"uuid","type":"home","label":"Home","place":{"placeId":"opaque","text":"One Victoria","fullText":"21 Shing Fung Road, Kai Tak","lat":22.3302,"lng":114.1992,"provider":"google"},"pickup_note":"Meet at the main entrance","sort_order":0,"version":3,"created_at":"2026-08-28T01:20:00Z","updated_at":"2026-08-28T01:25:00Z"}],"meta":{"total":1,"max_places":20}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"post":{"operationId":"postApiV1MeSavedPlaces","summary":"Save a Home, Work or custom place","description":"The place is resolved and normalized server-side from `placeId` (or accepted as a dropped pin when `place` carries lat, lng and a name); raw display text alone is refused with 400 `invalid_place`, and an id the provider cannot resolve with 422 `unresolvable_place`. One Home and one Work per rider: a second is 409 `home_already_exists` / `work_already_exists`. `pickup_note` is private until the rider books from this place.","tags":["Saved Places"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"Default custom."},"label":{"type":"string","description":"Required for custom (max 60); defaults to Home / Work otherwise."},"placeId":{"type":"string","description":"A place id from /api/v1/geo/suggest or /api/v1/geo/place."},"place":{"type":"object","description":"Alternative to placeId: { lat, lng, text } for a map pin."},"pickup_note":{"type":"string","description":"Max 200 characters."}}}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/saved-places/{id}":{"get":{"operationId":"getApiV1MeSavedPlacesById","summary":"Read one saved place","tags":["Saved Places"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"patch":{"operationId":"patchApiV1MeSavedPlacesById","summary":"Edit a saved place","description":"Edit label, pickup_note (null clears), type, sort_order or the place itself (placeId / place). Send the `version` you last read: a stale one is 409 `version_conflict` and nothing is written. The response carries the new version.","tags":["Saved Places"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"number","description":"Optimistic-concurrency token from the last read."},"label":{"type":"string"},"pickup_note":{"type":"string"},"type":{"type":"string"},"placeId":{"type":"string"}}}}}},"security":[{"userBearer":[]}]},"delete":{"operationId":"deleteApiV1MeSavedPlacesById","summary":"Delete a saved place","description":"Soft delete, idempotent: a repeated delete answers the same `{ data: { id, deleted: true } }`. The place leaves future recommendations; historical trips are untouched.","tags":["Saved Places"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/saved-places/reorder":{"post":{"operationId":"postApiV1MeSavedPlacesReorder","summary":"Persist the display order","description":"Body `{ ids: [...] }` in the order to show. Places left out keep their relative order after the named ones. Answers the full list.","tags":["Saved Places"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"string"}},"required":["ids"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/emergency-contacts":{"get":{"operationId":"getApiV1MeEmergencyContacts","summary":"List the caller's emergency contacts","description":"`meta` carries `max_contacts` (configurable, default 5), `supported_channels` (today `sms`) and `verification_delivery`: `simulated` on the staging fulfilment env (X-JEK-Env: staging; no message is sent and the platform's fixed test code confirms) or `unavailable` where no SMS provider exists yet.","tags":["Emergency Contacts"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":[{"id":"uuid","name":"Alex Chan","phone":"+85291234567","relationship":"family","is_primary":true,"verification_status":"verified","notification_channels":["sms"],"share_trip_by_default":false,"version":2,"created_at":"2026-08-28T01:20:00Z","updated_at":"2026-08-28T01:25:00Z"}],"meta":{"total":1,"max_contacts":5,"supported_channels":["sms"],"verification_delivery":"simulated"}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"post":{"operationId":"postApiV1MeEmergencyContacts","summary":"Add an emergency contact","description":"The phone is normalized to E.164 (a bare local number is read as +852; send `default_country` to change that). Refused: an invalid number (400 `invalid_phone`), the rider's own number (400 `invalid_phone`), a number already saved (409 `duplicate_contact`), and one past the ceiling (409 `contact_limit_reached`). New contacts are `pending` until verified; nothing automated reaches them before that.","tags":["Emergency Contacts"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string","description":"E.164 preferred."},"relationship":{"type":"string"},"notification_channels":{"type":"string","description":"Only `sms` is accepted."},"share_trip_by_default":{"type":"boolean"}},"required":["name","phone"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/emergency-contacts/{id}":{"get":{"operationId":"getApiV1MeEmergencyContactsById","summary":"Read one emergency contact","tags":["Emergency Contacts"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"patch":{"operationId":"patchApiV1MeEmergencyContactsById","summary":"Edit contact details or preferences","description":"Conditional on `version` (409 `version_conflict` when stale). Changing `phone` resets `verification_status` to `pending` — the consent belonged to the old number.","tags":["Emergency Contacts"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"number"},"name":{"type":"string"},"phone":{"type":"string"},"relationship":{"type":"string"},"notification_channels":{"type":"string"},"share_trip_by_default":{"type":"boolean"}}}}}},"security":[{"userBearer":[]}]},"delete":{"operationId":"deleteApiV1MeEmergencyContactsById","summary":"Delete an emergency contact","description":"Soft delete, idempotent. The contact stops receiving anything immediately; if it was the primary, nobody is promoted in its place.","tags":["Emergency Contacts"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/emergency-contacts/{id}/verification":{"post":{"operationId":"postApiV1MeEmergencyContactsByIdVerification","summary":"Send the verification / consent challenge","description":"Issues a 6-digit code valid for 10 minutes, at most once a minute per contact (429 `rate_limited`). 409 `already_verified` for a verified contact. 503 `notification_provider_unavailable` where no delivery exists (alpha/production today); on staging the send is simulated and `meta.delivery` says so.","tags":["Emergency Contacts"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/emergency-contacts/{id}/verification/confirm":{"post":{"operationId":"postApiV1MeEmergencyContactsByIdVerificationConfirm","summary":"Confirm the verification code","description":"200 with `meta.outcome` verified; 400 `invalid_code` (with `attempts_remaining`, 5 per code); 409 `verification_not_started`; 410 `verification_expired` when the code lapsed or the attempts ran out.","tags":["Emergency Contacts"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"}},"required":["code"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/emergency-contacts/{id}/set-primary":{"post":{"operationId":"postApiV1MeEmergencyContactsByIdSetPrimary","summary":"Make this the primary contact","description":"Zero or one primary per rider; the previous primary steps down. Idempotent.","tags":["Emergency Contacts"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/profile-image":{"get":{"operationId":"getApiV1MeProfileImage","summary":"The caller's profile image","description":"`data.profile_image` is null when the caller has none in this app. The `url` is a signed, short-lived link into a private bucket — render it, do not store it; `expires_in` is its life in seconds, and re-reading this endpoint (or GET /api/v1/me, which carries the same object) mints a fresh one.","tags":["Profile"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"profile_image":{"url":"https://…/storage/v1/object/sign/profile-images/…","expires_in":3600,"content_type":"image/jpeg","byte_size":84213,"created_at":"2026-09-18T02:10:00Z","updated_at":"2026-09-18T04:30:00Z"}}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"post":{"operationId":"postApiV1MeProfileImage","summary":"Upload a profile image, or replace the current one","description":"Send `{ image }` as a data URL or bare base64, or a multipart body with an `image` part — the same pair the licence scan takes, so a client already doing one needs nothing new. This is BOTH the upload and the edit: there is one current image per rider per app, so a second POST replaces the first and the old object is deleted. 201 when the rider had none, 200 when one was replaced (`data.replaced` says the same thing). The format is read off the bytes, never off the declared content type: JPEG, PNG and WebP are stored, and HEIC — what an iPhone hands over by default — is refused 415 `image_format_unsupported` with `detected` and `accepted`, because nothing but iOS can display it and this server has no way to transcode. Over 5 MB decoded is 413 `image_too_large` carrying `max_bytes`; bytes that are not an image at all are 400 `invalid_image`; no image in the body is 400 `image_required`.","tags":["Profile"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"The photo: a data: URL or bare base64 in a JSON body, or the `image` part of a multipart/form-data body."}},"required":["image"]}}}},"security":[{"userBearer":[]}]},"delete":{"operationId":"deleteApiV1MeProfileImage","summary":"Remove the current profile image","description":"The row and the stored object both go. Idempotent: a rider with no image answers 200 with `removed: false` rather than 404, so a retry over a flaky connection never has to tell the two apart. Only this app's image is removed — the same account's picture in the other app is untouched.","tags":["Profile"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"profile_image":null,"removed":true}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/street-hail/resolve":{"post":{"operationId":"postApiV1MeStreetHailResolve","summary":"What a scanned taxi QR is","description":"Body `{qr_content}` — a wonder.taxi sticker or offline meter QR. Answers `{kind: online_meter | offline_meter | virtual_meter, sticker_code, taxi {plate, brand}, meter_order {state, fare, amount_due, currency} | null, settles: jek | wonder, needs_driver_check}`. Never the driver's name or Wonder business. 400 INVALID_CODE, 409 WRONG_ENVIRONMENT / TRIP_FINISHED / NO_DRIVER_ON_METER, 404 TAXI_NOT_FOUND / TRIP_NOT_FOUND.","tags":["Passenger"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"qr_content":{"type":"string"}},"required":["qr_content"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/street-hail/verify-driver":{"post":{"operationId":"postApiV1MeStreetHailVerifyDriver","summary":"Confirm the driver of a virtual meter","description":"Body `{sticker_code, answer}` — the last word of the driver's English name, or the last character of a Chinese one; `letter` (the legacy app's name, used by docs/68) is accepted for `answer`. Checked on the server. Answers `{verified, proof, attempts_left}`; the proof is valid 10 minutes for this passenger and this taxi. 429 after five wrong answers in 10 minutes. Also served at /api/v1/me/street-hail/virtual-meter/verify-driver.","tags":["Passenger"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sticker_code":{"type":"string"},"answer":{"type":"string","description":"Or `letter`"}},"required":["sticker_code","answer"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/street-hail/virtual-meter/verify-driver":{"post":{"operationId":"postApiV1MeStreetHailVirtualMeterVerifyDriver","summary":"Confirm the driver of a virtual meter (alias)","description":"Alias of POST /api/v1/me/street-hail/verify-driver at the path docs/68 G3 named — same handler, same body (`answer` or `letter`), same answers.","tags":["Passenger"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sticker_code":{"type":"string"},"letter":{"type":"string","description":"Or `answer`"}},"required":["sticker_code","letter"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/street-hail/orders":{"post":{"operationId":"postApiV1MeStreetHailOrders","summary":"Make a street-hail trip payable","description":"Body `{qr_content, fare?, tips?, proof?}` (fare/tips/proof for a virtual meter; tip ≤ fare). Re-resolves the QR, then creates — or for a trip this passenger already scanned, returns — a ride of `order_type: street_hail` and answers `{ride_id, settles, amount_due, currency, pay}`. Pay with `POST /api/v1/me/rides/{id}/pay` (`mode: settle`), /pay/wallet or /pay/native-wallet; tip afterwards with /tip. 409 TRIP_TAKEN when another passenger is paying for it; 403 DRIVER_NOT_VERIFIED; 502 METER_ORDER_FAILED.","tags":["Passenger"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"qr_content":{"type":"string"},"fare":{"type":"number"},"tips":{"type":"number"},"proof":{"type":"string"}},"required":["qr_content"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/street-hail/orders/{id}/price":{"post":{"operationId":"postApiV1MeStreetHailOrdersByIdPrice","summary":"What paying a street-hail trip this way costs","description":"Body `{payment_method, card_scheme?}` (`card`, `vault-<id>`, `applepay`, `googlepay` or a wallet id). Answers `{settles, currency, fare, tips, discounts[], amount_due, source, locked}`. A JEK-settled trip gets JEK's payment offer for the method (never on the tip), RECORDED on the ride until a payment order exists (then `locked: true`); the pay routes charge it and 409 PAYMENT_OFFER_METHOD_MISMATCH for another method — call again to switch. A Wonder-settled trip answers Wonder's `price_calculator` (`source: wonder`), or the meter amount when OMS does not answer (`source: meter`), and records nothing. Needs `x-jek-env`. 404 NOT_FOUND; 400 INVALID_PAYMENT_METHOD.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"payment_method":{"type":"string"},"card_scheme":{"type":"string"}},"required":["payment_method"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/kash":{"get":{"operationId":"getApiV1MeKash","summary":"Your JEK Kash balance and history","description":"JEK only (403 JEK_ONLY otherwise), explicit x-jek-env, fresh eKYC and recovered-ledger gate (409 JEK_EKYC_REQUIRED / CARD_RECONCILIATION_PENDING / LEGACY_KASH_BALANCE_API_REQUIRED). `{balance, currency:'HKD', balances[{currency, balance}], entries_currency, entries[{id, kind, currency, amount, balance_after, ref_type, ref_id, reason, created_at}], next_cursor}`, newest first; `?limit` 1–200 (50), `?before` = the previous `next_cursor`. Kash is a rebate on JEK Card spend kept PER CURRENCY (a JPY purchase earns Kash JPY) and pays only for spends in its own currency (docs/84). `balances` is the caller's JEK Card program (x-jek-env); `balance`/`entries` stay the HKD Kash every ride and gift uses, and `?currency=JPY` pages that currency instead. Kinds: earn, redeem, gift_out, gift_in, reverse, adjust, migrate (card rebates are `earn`/`reverse` with `ref_type: card_transaction`). Never topped up, never cash.","tags":["Passenger"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"number"}},{"name":"before","in":"query","required":false,"schema":{"type":"string"}},{"name":"currency","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/kash/rules":{"get":{"operationId":"getApiV1MeKashRules","summary":"How JEK Kash is earned and spent","description":"JEK only. `{enabled, classes[{vehicle_type_id, code, name, earn_pct, redeem_allowed}], card_earn_pct, card_earn_pct_by_currency, ride_earn_enabled, ride_redeem_enabled, ride_redeem_cap_pct, gifts_enabled, gift_max_per_message, gift_daily_max, spent_via:['jek_card'], redeemable_on, top_up:false, cash_out:false}`. Kash is earned on JEK Card spend (1% by default, in the spend's currency) and spent through the JEK Card (docs/84); ride rebates, ride-booking redemption (`kash_amount` on `POST /api/v1/me/rides`, OFF by default) and chat gifts are each an operator switch, answered 0 when off. The 85% meter taxi earns 0 and refuses Kash.","tags":["Passenger"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/kash/gifts":{"post":{"operationId":"postApiV1MeKashGifts","summary":"Send JEK Kash to another JEK user","description":"JEK only (403 JEK_ONLY). `{to_user_id | to_phone, amount (HKD, to the cent), request_id}` → 201 `{entry_id, to_user_id, amount, currency:'HKD', balance, replayed}`. `request_id` is the idempotency key: a retry answers 200 with the first gift (`replayed: true`) and moves nothing. Same rules as a Kash gift in chat: Kash on (403 KASH_OFF), at most `gift_max_per_message` per gift and `gift_daily_max` per Hong Kong day (409 KASH_GIFT_LIMIT), never to yourself (400 KASH_GIFT_SELF), never an overdraft (409 KASH_INSUFFICIENT). The recipient must be a JEK member (404 RECIPIENT_NOT_FOUND); a block either way is 403 CANNOT_GIFT. Both sides see it in `GET /api/v1/me/kash` (`gift_out` / `gift_in`, `ref_type: kash_gift`).","tags":["Passenger"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to_user_id":{"type":"string"},"to_phone":{"type":"string"},"amount":{"type":"number"},"request_id":{"type":"string"}},"required":["amount","request_id"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/kash/transfers":{"post":{"operationId":"postApiV1MeKashTransfers","summary":"Send Kash to another JEK customer through Wonder","description":"Explicit X-JEK-Env and JEK bearer. {to_user_id, currency, amount (positive decimal string), remark (empty allowed), ref_id (globally unique)}. Server resolves verified parties and calls POST /svc/ts/api/v1/openapi/platform_transfers with type:c2c. 201/200 accepted creation; 202 uncertain/in flight; 409 rejected or reference conflict. The same ref never sends twice.","tags":["Passenger"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"get":{"operationId":"getApiV1MeKashTransfers","summary":"List your C2C transfers or read a stored receipt","description":"Explicit X-JEK-Env and JEK bearer. List with ?type=c2c&sender_user_id=<JEK account id> or receiver_user_id (at least one, one must be the caller). Server maps to Wonder users.id; offset defaults 0, limit defaults 10 (1–100). Returns data.{platform_transfers,offset,limit,has_more}. ?ref_id= alone retains the stored creation receipt; no automatic resend.","tags":["Passenger"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/explore/places":{"get":{"operationId":"getApiV1ExplorePlaces","summary":"JEK merchants and Apple / Google Maps places near a point","description":"No sign-in. `?lat&lng&radius_m (100–5000)&category (eat|cafes|bars|shops|go-out)&q&jek_only=1&limit (≤100)&offset`. Items `{id (m:<merchant>|a:<Apple place>|g:<Google place>), kind: jek|apple|google, name, address, lat, lng, distance_m, category, rating, rating_count, price_level, open_now, photo, capabilities{book, reserve, preorder, vouchers, kash}, enrichment?, provider_attribution?}` — for a non-JEK place every capability but `book` is false; `book` = JEK can drive the passenger there (a coordinate inside Hong Kong). `provider_attribution` (\"Apple Maps\" on Apple data) must be shown. Nearest first; a venue listed by several sources appears once (merchant, else Apple, else Google). From the database; an unsearched area is searched with Apple Maps (Hong Kong only) under the day's Apple call cap — `apple_budget_exhausted` when that cap stopped it. Explore's Google calls are off by default (docs/80); `google_budget_exhausted` is today's Google cap from the day's counter, false while Google is off.","tags":["Merchants"],"parameters":[{"name":"lat","in":"query","required":false,"schema":{"type":"number"}},{"name":"lng","in":"query","required":false,"schema":{"type":"number"}},{"name":"radius_m","in":"query","required":false,"schema":{"type":"number"}},{"name":"category","in":"query","required":false,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"schema":{"type":"string"}},{"name":"jek_only","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"limit","in":"query","required":false,"schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/v1/explore/places/{id}":{"get":{"operationId":"getApiV1ExplorePlacesById","summary":"One Explore place in full (JEK merchant + Apple place + cached Google details)","description":"No sign-in. `id` from the list (`m:` / `a:` / `g:`). `merchant`, `google` (cached hours, reviews with authors, photos with attributions — Google requires both shown — attributes, Google Maps link), `apple` (the Apple Maps place), `enrichment` (hours / photos / address / summary / website / phone, each `{value, source: website|google|unverified, at}`), `enrichment_status`, `provider_attribution` (\"Apple Maps\" must be shown with Apple data) and `capabilities{book, reserve, preorder, vouchers, kash}`. With Explore's Google off (the default, docs/80) nothing is refreshed on view and expired Google photo URIs are left out; a copy past its refresh period says `stale: true`. With Google on, a stale copy is refreshed first (≤ ~3 s, under budget); `google_budget_exhausted` when today's cap is spent.","tags":["Merchants"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/v1/explore/top-picks":{"get":{"operationId":"getApiV1ExploreTopPicks","summary":"Explore top picks near a point","description":"No sign-in. `?lat&lng&category&limit (≤30)`. JEK merchants first, then by rating weighted by rating count (Apple places carry no rating). Items as in `/api/v1/explore/places` (kinds jek|apple|google, with `capabilities.book`). Database only, no Apple or Google call; `google_budget_exhausted` is today's Google budget state from the day's counter, false while Explore's Google is off.","tags":["Merchants"],"parameters":[{"name":"lat","in":"query","required":false,"schema":{"type":"number"}},{"name":"lng","in":"query","required":false,"schema":{"type":"number"}},{"name":"category","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/public/v1/explore/search":{"get":{"operationId":"getApiPublicV1ExploreSearch","summary":"Explore search: JEK merchants + Apple Maps + cached places","description":"No sign-in (docs/80). `?q&lat&lng&radius (metres, 100–5000, default 2000)&category (eat|cafes|bars|shops|go-out)&limit (≤100, default 30)`. JEK merchants and cached Apple / Google places; with `q` and Apple enabled, also a live Apple Maps search (Hong Kong only, under the day's Apple call cap), stored and merged. A venue found by several sources appears once (merchant, else Apple, else Google). Answers `{data: {items, apple_budget_exhausted, sources: (jek|apple|google)[]}}`; items as in `/api/v1/explore/places` — `a:` ids for Apple, `provider_attribution: \"Apple Maps\"` must be shown, a non-JEK place offers only `capabilities.book`. Never calls Google.","tags":["Merchants"],"parameters":[{"name":"q","in":"query","required":false,"description":"Text query; triggers the live Apple search","schema":{"type":"string"}},{"name":"lat","in":"query","required":false,"schema":{"type":"number"}},{"name":"lng","in":"query","required":false,"schema":{"type":"number"}},{"name":"radius","in":"query","required":false,"description":"Metres, 100–5000, default 2000","schema":{"type":"number"}},{"name":"category","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"1–100, default 30","schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/public/v1/explore/places/{id}":{"get":{"operationId":"getApiPublicV1ExplorePlacesById","summary":"One Explore place in full, with its enrichment","description":"No sign-in (docs/80). `id` is `m:<merchant>`, `g:<Google place>` or `a:<Apple place>`, as the search returns it. The same body as `/api/v1/explore/places/{id}`: `merchant`, `google`, `apple`, `enrichment` (each field `{value, source: website|google|unverified, at}` — label `unverified` values as such), `enrichment_status`, `provider_attribution`, `capabilities`, `stale`. Database only: a place not enriched yet is enriched by the cron, never while the viewer waits.","tags":["Merchants"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/v1/me/explore/device-places":{"post":{"operationId":"postApiV1MeExploreDevicePlaces","summary":"Report places the app's on-device Apple Maps search found","description":"JEK only, signed in (docs/82). `{places: [{name, lat, lng, address?, phone?, url?, category?, apple_id?}]}`, 1–25 items (else 400). An item without a 1–200 char name or a Hong Kong point is dropped, not refused; a url that is not http(s) or is over 500 chars, or an `apple_id` not matching `^[A-Za-z0-9._-]{4,120}$`, drops only that field. `apple_id` is MapKit's `MKMapItem.identifier` (iOS 18+), stored as `apple:<id>`. An `apple_id` counts only within 75 m of the stored place it names (otherwise it is dropped). A place a JEK merchant already is (same name within 75 m) is skipped; a stored Apple place (from a search or a device report, owned by no merchant) of the same key and name, or the same name within 75 m, only has its empty website / phone / address / category filled; a merchant's or a Google place is never filled; anything else becomes a new place shown in Explore to everyone and enriched by the cron after every other place. Daily caps per user and for all users together (`explore.sources.device_reports.per_user_daily_cap` / `global_daily_cap`, HKT day, claimed atomically; a place already reported is free). Answers `{data: {accepted, merged, skipped, capped}}`; `accepted: 0` when the admin switch is off; 429 RATE_LIMITED with `Retry-After`.","tags":["Passenger"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"places":{"type":"array","description":"1–25 DevicePlace items"}},"required":["places"]}}}},"security":[{"userBearer":[]}]}},"/mcp":{"post":{"operationId":"postMcp","summary":"The JEK MCP server (streamable HTTP)","description":"An MCP server acting as ONE signed-in JEK passenger (docs/73). JSON-RPC over POST, stateless, JSON responses: `initialize`, `tools/list`, `tools/call`. Bearer = an access token from POST /oauth/token. Without a valid token: 401 with `WWW-Authenticate: Bearer resource_metadata=\"https://api.jek.app/.well-known/oauth-protected-resource\"`, which is how a client discovers the sign-in. 17 tools — read: ride_quote, list_rides, ride_status, kash_balance, list_vouchers, find_places, place_details, list_conversations; hand-off (nothing booked or paid): prepare_booking, prepare_tip; pending (confirm_action): send_message, share_trip, cancel_ride; app-only confirmation: send_kash, gift_voucher; confirm_action, cancel_action. GET (a server-notification stream this server never uses) and DELETE (a no-op session end) are answered for protocol compatibility only.","tags":["JEK AI (MCP)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/.well-known/oauth-protected-resource":{"get":{"operationId":"getWellKnownOauthProtectedResource","summary":"MCP resource metadata (RFC 9728)","description":"`{resource: \"https://api.jek.app/mcp\", authorization_servers, scopes_supported: [\"jek\"], bearer_methods_supported}`. Also served at `/.well-known/oauth-protected-resource/mcp`.","tags":["JEK AI (MCP)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/.well-known/oauth-protected-resource/mcp":{"get":{"operationId":"getWellKnownOauthProtectedResourceMcp","summary":"MCP resource metadata, path-suffixed form","description":"The same document as /.well-known/oauth-protected-resource, at the location MCP clients try first for /mcp.","tags":["JEK AI (MCP)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/.well-known/oauth-authorization-server":{"get":{"operationId":"getWellKnownOauthAuthorizationServer","summary":"OAuth server metadata (RFC 8414)","description":"Endpoints for MCP sign-in: authorization_endpoint `/oauth/authorize` (a page: JEK phone + SMS code, then consent; existing JEK accounts only), token_endpoint, registration_endpoint, revocation_endpoint. PKCE S256 only; public clients only (`token_endpoint_auth_method: none`).","tags":["JEK AI (MCP)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/oauth/register":{"post":{"operationId":"postOauthRegister","summary":"Register an MCP client (RFC 7591)","description":"`{client_name?, redirect_uris: [...]}` → 201 `{client_id, client_name, redirect_uris, token_endpoint_auth_method: \"none\", grant_types, response_types}`. Redirect URIs: https, or http on localhost / 127.0.0.1 / [::1]; no fragment; 1–5 of them. No secret is issued. Rate-limited per IP (429 slow_down).","tags":["JEK AI (MCP)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"redirect_uris":{"type":"string"},"client_name":{"type":"string"}},"required":["redirect_uris"]}}}},"security":[]}},"/oauth/token":{"post":{"operationId":"postOauthToken","summary":"Trade a code or refresh token for an MCP access token","description":"Form-encoded (or JSON). `grant_type=authorization_code` with `code`, `client_id`, `redirect_uri`, `code_verifier` (PKCE S256); the code is single-use and lives 60 s. `grant_type=refresh_token` with `refresh_token`, `client_id`; refresh tokens rotate on every use and a replayed one revokes the whole sign-in. Answers `{access_token (1 h), token_type: \"Bearer\", expires_in, refresh_token (30 d), scope: \"jek\"}`. Errors per RFC 6749: 400 invalid_grant / invalid_request / unsupported_grant_type.","tags":["JEK AI (MCP)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"grant_type":{"type":"string"}},"required":["grant_type"]}}}},"security":[]}},"/oauth/revoke":{"post":{"operationId":"postOauthRevoke","summary":"Revoke an MCP sign-in (RFC 7009)","description":"`token=<access or refresh token>`. Ends every token of that sign-in. Always 200, known token or not.","tags":["JEK AI (MCP)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"}},"required":["token"]}}}},"security":[]}},"/api/oauth/app":{"get":{"operationId":"getApiOauthApp","summary":"Which app is asking to connect","description":"For the /oauth/authorize page. `?client_id&redirect_uri` → `{client_id, client_name}`; 400 BAD_CLIENT / BAD_REDIRECT when the app is unknown or did not register that redirect. The OAuth endpoints themselves (/.well-known/*, /oauth/register, /oauth/token, /oauth/revoke) are described in docs/73.","tags":["JEK AI (MCP)"],"parameters":[{"name":"client_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"redirect_uri","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/oauth/approve":{"post":{"operationId":"postApiOauthApprove","summary":"Let an MCP app act for you","description":"Called by /oauth/authorize with the fresh JEK session. `{client_id, redirect_uri, code_challenge, code_challenge_method:'S256', state?}` → `{redirect_to}` carrying a single-use, 60-second `code`. JEK passengers only (403 NOT_JEK_USER); 400 BAD_PKCE / BAD_CLIENT / BAD_REDIRECT.","tags":["JEK AI (MCP)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/ai/connections":{"get":{"operationId":"getApiV1MeAiConnections","summary":"Apps connected to your JEK account","description":"JEK only. `{data:[{grant_id, client_id, client_name, connected_at, last_used_at}]}`, one per live sign-in.","tags":["JEK AI (MCP)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/ai/connections/{id}":{"delete":{"operationId":"deleteApiV1MeAiConnectionsById","summary":"Disconnect an app","description":"JEK only. `{id}` = grant_id. Its tokens stop working at once. 404 when the connection is not yours.","tags":["JEK AI (MCP)"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/ai/actions":{"get":{"operationId":"getApiV1MeAiActions","summary":"What JEK AI prepared for you","description":"JEK only. `?status=pending|confirmed|executed|failed|expired|cancelled`. `{data:[{id, tool, kind: pending|handoff, summary, confirm_via: client|app|null, status, expires_at, args, result, app_url}]}`, newest first (≤50). A pending action past `expires_at` reads as expired. Kash and voucher gifts (`confirm_via: app`) run only when confirmed here in the app.","tags":["JEK AI (MCP)"],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/ai/actions/{id}":{"get":{"operationId":"getApiV1MeAiActionsById","summary":"One AI action or draft","description":"JEK only. What the app opens for `jek://ai/draft/{id}`. A `book_ride` hand-off carries `args.route`, `args.quote` (with `quote_ref`) and the choices (classes, coupon / `user_voucher_id`, `kash_amount`, `scheduled_at`) to prefill booking; the app books through `POST /api/v1/me/rides` as usual.","tags":["JEK AI (MCP)"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/ai/actions/{id}/confirm":{"post":{"operationId":"postApiV1MeAiActionsByIdConfirm","summary":"Confirm an AI action in the app","description":"JEK only. Runs a pending action once (message, trip share, free cancel, Kash gift, voucher gift) through the same code the REST routes use, and answers the action with `status: executed|failed` and `result`. For a hand-off (booking, tip, paid cancel) it only marks the draft done — call it after the app has booked or paid. 404 NOT_FOUND, 409 NOT_PENDING / EXPIRED.","tags":["JEK AI (MCP)"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/ai/actions/{id}/cancel":{"post":{"operationId":"postApiV1MeAiActionsByIdCancel","summary":"Decline an AI action","description":"JEK only. Drops a pending action or draft. 409 NOT_PENDING when it already ran or ended.","tags":["JEK AI (MCP)"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/ai/chat":{"post":{"operationId":"postApiV1MeAiChat","summary":"Talk to JEK AI in the app","description":"JEK only. `{messages:[{role:'user'|'assistant', content}], lang?, context?:{hasActiveTrip?}}` — the last 20 turns, the last one the passenger's. Answers the app's `AiChatResponse` `{reply, intent?, pending_action?, conversation_id}`. `intent {type: newTrip|updatePickup|updateDropoff, pickupQuery?, dropoffQuery?}` hands a booking to the app's booking screen. `pending_action {action_id, summary, status: needs_confirmation|needs_app_confirmation|handoff, expires_at}` is confirmed with `POST /api/v1/me/ai/actions/{id}/confirm`. The model reads rides, Kash, vouchers, chats and Explore through the same tools as /mcp. Refusals carry a showable `reply`: 429 AI_DAILY_LIMIT (per passenger per Hong Kong day) / AI_BUSY, 402 AI_CREDITS, 503 AI_OFF / AI_UNAVAILABLE.","tags":["JEK AI (MCP)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"string"},"lang":{"type":"string"},"context":{"type":"string"}},"required":["messages"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/vouchers":{"get":{"operationId":"getApiV1MeVouchers","summary":"Vouchers you hold","description":"JEK only. Claimed merchant vouchers, granted ride coupons and gifts. `?status=held|used|expired|transferred|all` (held). Each `{id, kind: merchant_voucher|ride_coupon, source: claim|grant|gift, status, redeem_code (merchant vouchers, shown at the counter), snapshot, expires_at, used_at}`. Book a ride coupon with `user_voucher_id` on `POST /api/v1/me/rides`; give one in chat with kind='voucher' + `metadata.user_voucher_id`.","tags":["Passenger"],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/vouchers/claim":{"post":{"operationId":"postApiV1MeVouchersClaim","summary":"Claim a merchant voucher","description":"JEK only. `{voucher_id}`. Once per person per voucher: 201 on the claim, 200 with the same instance when already claimed. 404 NOT_FOUND, 409 NOT_AVAILABLE / NOT_STARTED / EXPIRED / SOLD_OUT.","tags":["Passenger"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"voucher_id":{"type":"string"}},"required":["voucher_id"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/vouchers/claimable":{"get":{"operationId":"getApiV1VouchersClaimable","summary":"Merchant vouchers that can be claimed now","description":"No sign-in. Published, started, not ended, with quantity left (`remaining`, null = unlimited). `?merchant_id&limit` (≤200).","tags":["Passenger"],"parameters":[{"name":"merchant_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/v1/merchant/vouchers/redeem":{"post":{"operationId":"postApiV1MerchantVouchersRedeem","summary":"Mark a customer's voucher used at the counter","description":"`{redeem_code}` (8 characters). Only this merchant's (or its chain's) vouchers; any other code reads 404. Used once: 409 USED with `used_at` on a second scan.","tags":["Merchant"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"redeem_code":{"type":"string"}},"required":["redeem_code"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/messaging/blocks":{"get":{"operationId":"getApiV1MeMessagingBlocks","summary":"People you've blocked in chat","description":"Per app. `{data:[{user_id, created_at}]}`.","tags":["Messaging"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"post":{"operationId":"postApiV1MeMessagingBlocks","summary":"Block someone in chat","description":"Body `{user_id}`. Stops new threads and messages both ways; the other person is told only \"You can't message this person\" (403 CANNOT_MESSAGE).","tags":["Messaging"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string"}},"required":["user_id"]}}}},"security":[{"userBearer":[]}]},"delete":{"operationId":"deleteApiV1MeMessagingBlocks","summary":"Unblock someone","description":"Body `{user_id}`.","tags":["Messaging"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string"}},"required":["user_id"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/messaging/reports":{"post":{"operationId":"postApiV1MeMessagingReports","summary":"Report a conversation","description":"Body `{conversation_id, reason: spam|harassment|scam|inappropriate|other, message_ids?, reported_user_id?, note?, forwarded?}`. The caller must be a member of the thread in this app. End-to-end encrypted chats (docs/76): `forwarded: [{message_id, plaintext, franking_key}]` (≤20) is what the reporter decrypted; it is stored only if every item passes the franking check (the key opens the sender's commitment, and the server's tag binds it to this chat, sender and time), otherwise 400 FORWARD_NOT_VERIFIED and nothing is stored. With no `reported_user_id`, forwards from one person report that person. `reported_user_id`, when given: with forwards it must be one of the verified senders (400 REPORTED_USER_MISMATCH); without, it must be a current or past member of the thread (400 REPORTED_USER_NOT_IN_CHAT); never the reporter (400 REPORTED_USER_SELF). Forwarded ids are kept first within the 50 message ids stored.","tags":["Messaging"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"conversation_id":{"type":"string"},"reason":{"type":"string"},"message_ids":{"type":"array"},"reported_user_id":{"type":"string"},"note":{"type":"string"},"forwarded":{"type":"string"}},"required":["conversation_id","reason"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/messaging/conversations/{id}/e2e-messages":{"post":{"operationId":"postApiV1MeMessagingConversationsByIdE2eMessages","summary":"Send an end-to-end encrypted message","description":"JEK app only; header `x-e2e-device-secret` of the sending device. Body `{sender_device_id, envelopes: [{recipient_device_id, type: prekey|message|sender_key_distribution, ciphertext (base64, ≤64 KiB)}], franking_commitment (32-byte base64 HMAC-SHA256), client_id?}`. The envelopes must cover EXACTLY every active device of every member except the sending one (your own other devices included); otherwise 409 DEVICES_CHANGED `{missing, extra, devices}` — refresh those bundles, re-encrypt, resend. 409 NO_RECIPIENT_DEVICES `{users}` when a member has no device at all. Writes one message (kind `e2e`, body null, `metadata.franking`) and one envelope per device; 201 `{message, envelopes, replayed}`. A repeated client_id returns the first message (200, `replayed: true`), enforced by a unique index so concurrent retries also get one message. The message and its envelopes are written in one transaction, so a replay always points at a delivered message; 409 RETRY only before migration 20261002120000 (the first attempt failed while the retry waited) — send again. 409 NOT_E2E when the chat is not encrypted; 403 DEVICE_NOT_AUTHORIZED; 503 E2E_UNAVAILABLE until migrated and CHAT_FRANKING_SECRET is set.","tags":["Encrypted chat"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sender_device_id":{"type":"string"},"envelopes":{"type":"string"},"franking_commitment":{"type":"string"},"client_id":{"type":"string"}},"required":["sender_device_id","envelopes","franking_commitment"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/e2e/devices":{"get":{"operationId":"getApiV1MeE2eDevices","summary":"My encrypted-chat devices","description":"The caller's active devices: `{id, device_no, name, platform, is_primary, linked_by_device, registration_id, identity_key, signed_prekey, created_at, last_seen_at}`. Public keys only. JEK app only.","tags":["Encrypted chat"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"post":{"operationId":"postApiV1MeE2eDevices","summary":"Register the account's first device (the phone)","description":"Body `{platform: ios|android|web, registration_id (1-16380), identity_key, signed_prekey: {key_id, public_key, signature}, prekeys?: [{key_id, public_key}] (≤100), name?}`; keys are libsignal-serialised base64 (33-byte public keys, 64-byte signatures). → 201 `{device, device_secret, prekeys_remaining}`; `device_secret` is shown once and goes in `x-e2e-device-secret` on every device-scoped call. The first device is the primary; with one already registered, 409 LINK_REQUIRED `{recovery_available: true}` — link further devices by QR, or replace a lost phone through /api/v1/me/e2e/recovery/start. Registering can switch the caller's chats to encrypted (every member now has a device).","tags":["Encrypted chat"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string"},"registration_id":{"type":"number"},"identity_key":{"type":"string"},"signed_prekey":{"type":"string"},"prekeys":{"type":"string"},"name":{"type":"string"}},"required":["platform","registration_id","identity_key","signed_prekey"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/e2e/devices/{id}":{"delete":{"operationId":"deleteApiV1MeE2eDevicesById","summary":"Revoke a device","description":"Revokes one of the caller's devices. A linked device needs only the session; the PRIMARY needs its own `x-e2e-device-secret` (403 DEVICE_NOT_AUTHORIZED otherwise) and takes every device on the account with it. Pre-keys and undelivered envelopes are deleted. → `{revoked: [ids]}`.","tags":["Encrypted chat"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/e2e/devices/{id}/prekeys":{"get":{"operationId":"getApiV1MeE2eDevicesByIdPrekeys","summary":"One-time pre-keys left","description":"`{prekeys_remaining}` for the device; top up when it runs low. Header `x-e2e-device-secret`.","tags":["Encrypted chat"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"post":{"operationId":"postApiV1MeE2eDevicesByIdPrekeys","summary":"Upload pre-keys / rotate the signed pre-key","description":"Body `{prekeys?: [{key_id, public_key}] (≤100 per call, ≤500 held), signed_prekey?: {key_id, public_key, signature}}`. Header `x-e2e-device-secret`. → `{prekeys_remaining}`.","tags":["Encrypted chat"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/e2e/devices/{id}/envelopes":{"get":{"operationId":"getApiV1MeE2eDevicesByIdEnvelopes","summary":"Fetch this device's encrypted messages","description":"Waiting envelopes, oldest first: `{envelopes: [{id, message_id, conversation_id, sender_user_id, sender_device_id, type, ciphertext, created_at}], more}`. `?limit` (≤200). No cursor: acknowledge what you stored, then fetch again while `more` (acknowledged envelopes are deleted). Header `x-e2e-device-secret`. Envelopes nobody fetches are deleted after 30 days.","tags":["Encrypted chat"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/e2e/devices/{id}/envelopes/ack":{"post":{"operationId":"postApiV1MeE2eDevicesByIdEnvelopesAck","summary":"Acknowledge envelopes","description":"`{ids: [...]}` (≤500) of envelopes this device has decrypted and stored; they are deleted at once. Header `x-e2e-device-secret`. → `{acked}`.","tags":["Encrypted chat"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"string"}},"required":["ids"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/e2e/users/{userId}/bundles":{"get":{"operationId":"getApiV1MeE2eUsersByUserIdBundles","summary":"Key bundles to start sessions with someone","description":"`{user_id, devices: [{device_id, device_no, registration_id, identity_key, signed_prekey, prekey}]}` for every active device of `userId` — someone the caller shares an accepted JEK dm or a group with, or the caller (for their own other devices). Each `prekey` is claimed for this caller only, and null once the device has run out. With only a PENDING message request between them, `prekey` is always null and nothing is claimed. 403 NOT_A_CONTACT for anyone else, a declined request or across a block; 429 SLOW_DOWN (60 a minute).","tags":["Encrypted chat"],"parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/e2e/link/start":{"post":{"operationId":"postApiV1MeE2eLinkStart","summary":"Ask to link a new device (show a QR)","description":"From the NEW device (web, tablet), signed in to the same account. Body: its public bundle, as for POST /api/v1/me/e2e/devices. → 201 `{id, code, device_secret, expires_at}` (5 minutes): show `code` as a QR, keep `device_secret`, poll GET /api/v1/me/e2e/link/{id}. 409 NO_PRIMARY_DEVICE until the phone is registered; 429 TOO_MANY_LINKS.","tags":["Encrypted chat"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/e2e/link/approve":{"post":{"operationId":"postApiV1MeE2eLinkApprove","summary":"Approve a scanned link code (phone)","description":"From the PRIMARY device: `{code, device_id}` with the phone's `x-e2e-device-secret`. → 201 `{device}`. 403 NOT_PRIMARY / DEVICE_NOT_AUTHORIZED, 404 LINK_NOT_FOUND, 410 LINK_EXPIRED.","tags":["Encrypted chat"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"device_id":{"type":"string"}},"required":["code","device_id"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/e2e/link/reject":{"post":{"operationId":"postApiV1MeE2eLinkReject","summary":"Reject a scanned link code (phone)","description":"From the PRIMARY device: `{code, device_id}` with the phone's `x-e2e-device-secret`. → `{status: \"rejected\"}`.","tags":["Encrypted chat"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"device_id":{"type":"string"}},"required":["code","device_id"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/e2e/link/{id}":{"get":{"operationId":"getApiV1MeE2eLinkById","summary":"Poll a link request (new device)","description":"With the `x-e2e-device-secret` /link/start returned: `{id, status: pending|approved|rejected|expired, expires_at, device}`; `device` is set once approved, and the secret works from then on.","tags":["Encrypted chat"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/e2e/recovery/start":{"post":{"operationId":"postApiV1MeE2eRecoveryStart","summary":"Lost phone: send the recovery SMS code","description":"Step 1 of moving encrypted chat to a new phone. Sends a code to the number ON the account (SMS purpose `e2e_recovery`). Body `{deviceId?, lang?, captchaToken?}` → `{token, expires_in}`. 409 NOTHING_TO_RECOVER when the account has no device (register directly), 409 RECOVERY_PENDING when one is running, 429 SLOW_DOWN after 3 an hour. JEK app only.","tags":["Encrypted chat"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"deviceId":{"type":"string"},"lang":{"type":"string"},"captchaToken":{"type":"string"}}}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/e2e/recovery/confirm":{"post":{"operationId":"postApiV1MeE2eRecoveryConfirm","summary":"Lost phone: spend the code, open the recovery","description":"Body `{token, aut_code, deviceId?}` (deviceId as sent to /start). → 201 `{recovery: {id, status, requested_at, eligible_at, expires_at, stale_skip, decided_at}, recovery_secret}`; `recovery_secret` is shown once and goes in `x-e2e-recovery-secret` at /recovery/complete. `eligible_at` is 24 hours on — or now when every active device has been unseen for 30+ days (`stale_skip`). The old devices stay active meanwhile and any of them can cancel. Unless the wait was skipped, every device on the account gets a vague security push (data.type `e2e_security`: open the app and read GET /recovery), and one reminder about 6 hours before eligible_at; completion pushes once more. 401 AUTH_FAILED (wrong code, nothing spent), 401 FLOW_ALREADY_USED (replayed), 409 RECOVERY_PENDING, 429 SLOW_DOWN after 5 an hour.","tags":["Encrypted chat"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"aut_code":{"type":"string"},"deviceId":{"type":"string"}},"required":["token","aut_code"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/e2e/recovery":{"get":{"operationId":"getApiV1MeE2eRecovery","summary":"Lost phone: the latest recovery","description":"`{recovery}` (the latest, any status: pending|cancelled|completed|expired) or `{recovery: null}`. The old phone checks it on open and offers to cancel a pending one; the new phone reads `eligible_at`.","tags":["Encrypted chat"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"delete":{"operationId":"deleteApiV1MeE2eRecovery","summary":"Lost phone: cancel a recovery (from an old device)","description":"Needs `x-e2e-device-secret` of ANY of the account's active devices; the session alone is 403 DEVICE_NOT_AUTHORIZED. → `{status: \"cancelled\", recovery}`, or `{status: \"none\"}` when nothing is pending.","tags":["Encrypted chat"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/e2e/recovery/complete":{"post":{"operationId":"postApiV1MeE2eRecoveryComplete","summary":"Lost phone: register the new phone","description":"From the new phone once `eligible_at` has passed, with header `x-e2e-recovery-secret` (the `recovery_secret` /recovery/confirm returned; 403 RECOVERY_NOT_AUTHORIZED without it — the session alone cannot finish). Body: its public bundle, as for POST /api/v1/me/e2e/devices. Revokes every old device (their pre-keys and undelivered envelopes go with them), registers this one as the primary, and posts a \"security code changed\" system notice (metadata `e2e_identity_changed`) in each of the caller's encrypted chats, broadcast with an `e2e_devices` event. → 201 `{device, device_secret, prekeys_remaining, revoked, notified_conversations, recovery}`; `device_secret` is shown once. 409 RECOVERY_WAITING `{eligible_at}`, 404 NO_RECOVERY, 410 RECOVERY_EXPIRED (7 days after eligible).","tags":["Encrypted chat"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string"},"registration_id":{"type":"number"},"identity_key":{"type":"string"},"signed_prekey":{"type":"string"},"prekeys":{"type":"string"},"name":{"type":"string"}},"required":["platform","registration_id","identity_key","signed_prekey"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/realtime":{"get":{"operationId":"getApiV1MeRealtime","summary":"How to subscribe to live updates for your own orders","description":"Every ride/trip transition is broadcast on Supabase Realtime as a nudge; re-read the order's `/events` with your cursor when one arrives and keep polling as the fallback. Channels are PRIVATE: call `realtime.setAuth(<your access_token>)` and subscribe to `order:ride:{id}` / `order:trip:{id}` with `config: { private: true }` — only the order's owner is admitted. Returns the project URL and the (public) anon key. 503 when realtime is not configured.","tags":["Passenger"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"url":"https://<project>.supabase.co","anon_key":"…","private":true,"topic_format":{"ride":"order:ride:{id}","trip":"order:trip:{id}"}}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/account/deletion":{"get":{"operationId":"getApiV1MeAccountDeletion","summary":"The caller's pending account deletion","description":"`{status:\"none\"}`, or `{status:\"scheduled\", requested_at, scheduled_for}` for this app (`x-user-scope`). A deletion runs 30 days after it is confirmed; until then signing in cancels it (the sign-in response then carries `account_deletion_cancelled: true`). On `scheduled_for` the app's personal data — saved places, safety contacts, synced contacts, push tokens, referral code, profile image, saved cards — is removed; rides, payments and receipts are kept for accounting. When no other app remains on the identity, its name and phone are wiped and the number can sign up again as a new account.","tags":["Profile"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"status":"scheduled","requested_at":"2026-09-28T02:00:00Z","scheduled_for":"2026-10-28T02:00:00Z"}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"delete":{"operationId":"deleteApiV1MeAccountDeletion","summary":"Cancel a pending account deletion","description":"Cancels this app's pending request. Idempotent: nothing pending answers 200 `{status:\"none\"}`, not 404.","tags":["Profile"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"status":"cancelled"}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/ride/rating-reasons":{"get":{"operationId":"getApiV1RideRatingReasons","summary":"Rating reason catalog (managed, versioned)","description":"The reason chips a finished Lane 1 trip offers, with a `catalog_version` derived from the catalog's content so a client can cache against it. Each entry carries `code`, `label_key` (a translation key the client resolves — the server never sends an English label, which would be wrong in three of the four shipped locales), an operator `label` override or null, and `sentiment`. Managed in `system_configs['ride.rating']` beside the rating windows; POST /api/v1/me/rides/{id}/rating validates against this same list, so an added reason is stored rather than dropped.","tags":["Ride"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/ride/preflight":{"post":{"operationId":"postApiV1RidePreflight","summary":"May this trip be booked? (Lane 1 serviceability)","description":"The authoritative Lane 1 answer Standard Ride and JEK Wish both run before opening a quote/request screen. 200 = serviceable, with the summed route (`distance_m`, `duration_min`, stitched `points`). 422 `OUT_OF_SERVICE_AREA` = definitively unsupported — a waypoint outside every configured service area, or a leg the router says has no road; refuse, do not retry. 503 `ROUTING_UNAVAILABLE` = temporary, offer Retry (never shown as \"unavailable here\"). 401 `AUTH_REQUIRED`. Service areas come from `system_configs['ride.service_area']`, shared with /api/v1/passenger/serviceability. `dropoff` is optional: with a pickup alone this answers the area question only, which is what a landing screen needs. No supply probe — that would sign with Wonder DA, which Lane 1 exists to avoid. Also returns `fulfilment` (`jek` = our own fleet, `partner` = third-party capacity through Wonder for a market where JEK has no fleet) and `fulfilment_area`. THE CLIENT READS THIS, IT NEVER DECIDES IT: a JEK passenger books through the same surface wherever they are standing, and the server picks the supplier from each area's `fulfilment`, maintained at /admin/ride/service-areas. The PICKUP decides — a Hong Kong pickup bound for Shenzhen is still `jek`. On `partner` our own service areas stop constraining the other waypoints (they describe where OUR fleet drives), though an undrivable leg still refuses. `fulfilment` is null on a 422 whose pickup nobody serves.","tags":["Ride"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"order_type":{"type":"string","description":"ride | wish (default ride)"},"pickup":{"type":"object","description":"{ lat, lng, label? }"},"dropoff":{"type":"object","description":"{ lat, lng, label? }; omit for a pickup-only area check"},"stops":{"type":"array","description":"Ordered intermediate waypoints, at most 4"}},"required":["pickup"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/ride/availability":{"post":{"operationId":"postApiV1RideAvailability","summary":"Live supply and pickup ETA (Lane 1)","description":"Is there a car for this pickup, which classes can serve it, and how long until one arrives — the third pre-booking question, beside /ride/preflight (may we drive here) and /ride/quote (what does it cost). Counts `da_drivers` that are online, approved, carrying a fix newer than 150s, inside the radius and not already on a job; a driver whose vehicle declares no dispatch class is UNRESTRICTED and counts for every class, exactly as the accept path reads it. Deliberately NOT /passenger/serviceability's probe, which signs with Wonder DA and counts street taxis that cannot take a jek_rides order. `supply.status`: `ok` (measured, cars) | `none` (measured, none) | `unavailable` (OUR outage — show a retry, never \"no cars\") | `not_applicable` (this area's `fulfilment` is partner/fleet, so our own fleet is not the answer). `eta` is the road route to the NEAREST car, falling back to the same straight-line estimate the live ride's `remaining_route` uses and labelled `source: estimate`; each class routes its own nearest eligible car, with parallel four-second timeouts and one call per distinct driver. Classes sharing a car share its ETA. A failed route falls back from that car's own coordinates with eta_source: estimate and eta_confidence: low. Never answers 5xx for an outage. This reports supply, it does NOT authorise a booking — /ride/preflight stays the coverage authority. Cached 10s on the rounded request.","tags":["Ride"],"parameters":[],"responses":{"200":{"description":"Availability","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RideAvailability"}}}}}},"400":{"description":"invalid_coordinates or too_many_classes"},"401":{"description":"AUTH_REQUIRED"},"429":{"description":"rate_limited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["pickup"],"properties":{"pickup":{"type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"}},"required":["lat","lng"]},"vehicle_class_ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":24},"radius_m":{"type":"integer","description":"Clamped to the configured bounds."}}}}}},"security":[{"userBearer":[]}]}},"/api/v1/ride/nearby":{"post":{"operationId":"postApiV1RideNearby","summary":"Nearby cars on the map (Lane 1)","description":"The pins the where-to map draws before anything is assigned: JEK's OWN drivers around a point, from the same `da_drivers` probe /ride/availability counts (online, approved, fix newer than 150s, inside the radius, not on a job) — with no routing call, so a map may poll it every 12s. Deliberately NOT /passenger/nearby, which proxies Wonder DA's taxis/nearby with partner credentials: that is the lane a JEK rider is handed down OUTSIDE Hong Kong, and it returns street taxis that cannot take a jek_rides order. `vehicles[]` is nearest first, capped at `limits.max_vehicles` (supply.count stays the true number); each `id` is a pseudonym that is stable across polls and rotates daily — never a driver id. `supply.status` as on /ride/availability: `ok` | `none` (measured, empty street) | `unavailable` (OUR outage — not an empty street, not cached) | `not_applicable` (this area's fulfilment is partner/fleet; somebody else's cars serve it). Never 5xx for an outage. Reports supply, does not authorise a booking. Cached 10s on the rounded request.","tags":["Ride"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"supply":{"status":"ok","count":3,"nearest_m":140,"radius_m":2500,"fix_max_age_s":150},"vehicles":[{"id":"9f2c1e7a4b3d5c60","lat":22.283,"lng":114.159,"distance_m":140,"fix_age_s":12},{"id":"0b7d4e2f9a1c3e58","lat":22.29,"lng":114.165,"distance_m":1100,"fix_age_s":40}],"area":{"code":"hk","name":"Hong Kong"},"fulfilment":"jek","config_version":"default-2026-08-28","cached":false,"limits":{"max_radius_m":20000,"max_vehicles":50}}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pickup":{"type":"object","description":"{ lat, lng }; `location` is accepted as an alias"},"radius_m":{"type":"number","description":"200–20000; defaults to the service-area config's supply_radius_m."}},"required":["pickup"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/ride/directions":{"post":{"operationId":"postApiV1RideDirections","summary":"Route geometry, distance & duration","description":"Server-side Google Directions proxy. Returns an encoded polyline plus distance (metres) and duration (seconds) for a pickup → destination pair. Used by the booking wizard so the browser never needs a Maps key.","tags":["Ride"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"object","description":"{ lat, lng } or address string"},"destination":{"type":"object","description":"{ lat, lng } or address string"}},"required":["origin","destination"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/ride/wish-analysis":{"post":{"operationId":"postApiV1RideWishAnalysis","summary":"Analyse a passenger 'wish' request","description":"Runs the free-text (or transcribed voice) wish through the analysis model with the route context. Returns feasibility, whether it is really a plain ride, clarification questions, estimated extra time/cost and a suggested tip range.","tags":["Ride"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"rideOnly":false,"feasible":true,"clarifications":["Which pharmacy branch should the driver use?"],"extra_minutes":18,"extra_cost":96,"suggested_tips":[20,50,100]}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"wish":{"type":"string"},"pickup":{"type":"string"},"destination":{"type":"string"},"distance_km":{"type":"number"},"base_fare":{"type":"number"}},"required":["wish"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/rides/{id}/cancel":{"post":{"operationId":"postApiV1MeRidesByIdCancel","summary":"Cancel the caller's own ride or wish order","description":"Marks the caller's own order cancelled and records the reason in the wish metadata. Returns 409 if the order is already completed/cancelled, if a driver has already accepted it (code WISH_ALREADY_CLAIMED), or if the status changed concurrently (code WISH_CHANGED). No refund transaction is written.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Free-text cancel reason (max 200 chars)"}}}}}},"security":[{"userBearer":[]}]}},"/api/v1/da/wishes/{id}/status":{"post":{"operationId":"postApiV1DaWishesByIdStatus","summary":"Advance a wish order's status","description":"Driver-side state transition for a wish the caller holds: accepted → arrived → in_trip → completed, with cancelled available until the trip starts. The body field is `state`, NOT `status`. Returns `{ data }` — the full updated wish row, which is what the driver app renders from rather than re-reading the feed. Refuses a disallowed move with 409 `{ error, allowed: [...] }` naming the transitions it would have accepted, 409 \"Wish changed concurrently\" if the status moved under the caller, and 404 for a wish the caller does not hold.","tags":["Driver Assistant"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","description":"Target state: arrived | in_trip | completed | cancelled"},"reason":{"type":"string","description":"Free-text cancel reason (max 200 chars), recorded when state is `cancelled`"}},"required":["state"]}}}},"security":[{"driverBearer":[]}]}},"/api/v1/ride/wish-quote":{"post":{"operationId":"postApiV1RideWishQuote","summary":"Re-price an already-analysed wish","description":"Recomputes a signed fare quote when the vehicle class or route changes after /api/v1/ride/wish-analysis, without re-running the language model. Wish facts sent by the client are clamped server-side, so a cheaper wish cannot be forced.","tags":["Ride"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicleTypeId":{"type":"string"},"distanceKm":{"type":"number"},"durationMin":{"type":"number"},"analysis":{"type":"object","description":"Analysis payload returned by /api/v1/ride/wish-analysis"}},"required":["vehicleTypeId","distanceKm"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/rides/{id}/driver-location":{"get":{"operationId":"getApiV1MeRidesByIdDriverLocation","summary":"Last known driver location for an order","description":"Rider-facing read of the assigned driver's most recent GPS ping. Poll while the order is accepted / in progress.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/da/wishes/{id}":{"get":{"operationId":"getApiV1DaWishesById","summary":"Wish order detail for the assigned driver","tags":["Driver Assistant"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/wishes/{id}/expense":{"get":{"operationId":"getApiV1DaWishesByIdExpense","summary":"List expense claims filed against a wish","tags":["Driver Assistant"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]},"post":{"operationId":"postApiV1DaWishesByIdExpense","summary":"File an expense claim for reimbursement","description":"Submits an out-of-pocket expense (amount, note, uploaded receipt path) for the wish the driver is running.","tags":["Driver Assistant"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number"},"receiptPath":{"type":"string","description":"Storage path returned by the upload-url endpoint"},"note":{"type":"string"}},"required":["amount"]}}}},"security":[{"driverBearer":[]}]}},"/api/v1/da/wishes/{id}/expense/upload-url":{"post":{"operationId":"postApiV1DaWishesByIdExpenseUploadUrl","summary":"Signed upload URL for an expense receipt","description":"Returns a short-lived signed URL into the driver-documents bucket for the receipt image.","tags":["Driver Assistant"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/supplier/quotes":{"post":{"operationId":"postApiV1SupplierQuotes","summary":"Fare quotes for a demand platform","description":"The quote counterpart to POST /api/v1/supplier/orders. Authenticates with the shared X-Internal-Token (a partner is a platform, not a signed-in rider) and answers in the caller's registered dialect — Wonder callers get {code,message,data:{quotes,batch_id}}, native callers get {data:{quotes,batch_id}}. Priced from the same rate card the booking uses; batch_id ties a later booking back to the fares it was offered. Quotes are honoured for 10 minutes. Distance/duration echo what the caller sent — this path does not geocode or route. The classes offered are the globally enabled ones NARROWED by this partner's allow list at /admin/ride/partners: a partner with no list is offered everything, one that is not sold a named class is answered unknown_class, and a list that leaves nothing answers 403 no_partner_classes (not 503 no_card, which means the rate card itself is empty).","tags":["Supply platform"],"parameters":[{"name":"x-internal-token","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicle_type_codes":{"type":"string","description":"Classes to price, in dispatch vocabulary"},"from":{"type":"object","description":"{ lat, lng, text? }"},"to":{"type":"object","description":"{ lat, lng, text? }"},"distance_km":{"type":"number"}},"required":["vehicle_type_codes","from","to"]}}}},"security":[]}},"/api/v1/me/rides/{id}":{"get":{"operationId":"getApiV1MeRidesById","summary":"Full detail of one of the caller's rides","description":"The single read the trip screen polls. Scoped by id AND user_id — a ride belonging to someone else answers 404, never 403, so ids cannot be probed. The payload is additive: each feature (driver, cancellation, receipt, events, coupons…) contributes one sibling key, while `fare` stays a bare number for compatibility with older app builds.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/rides/{id}/cancel-preview":{"get":{"operationId":"getApiV1MeRidesByIdCancelPreview","summary":"Preview cancelling this ride","description":"Answers 'what would happen if I cancelled right now' — whether it is allowed and what it would cost — using the same stored policy and evaluator as POST /cancel, so the preview cannot disagree with the charge. Writes nothing.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/rides/{id}/contact":{"get":{"operationId":"getApiV1MeRidesByIdContact","summary":"Masked contact channels to the assigned driver","description":"How the passenger reaches the driver without either side learning the other's number: a pooled virtual number held for this ride, plus an in-app chat conversation. Offered only while the ride is live; an empty number pool returns 200 with available:false rather than ever exposing the driver's real mobile.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"post":{"operationId":"postApiV1MeRidesByIdContact","summary":"Open a masked contact channel","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","description":"phone | chat"}},"required":["channel"]}}}},"security":[{"userBearer":[]}]},"delete":{"operationId":"deleteApiV1MeRidesByIdContact","summary":"Release the ride's masked contact channel","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/rides/{id}/destination":{"post":{"operationId":"postApiV1MeRidesByIdDestination","summary":"Change where a ride is going","description":"Re-rides the pricing server-side: the request names where to, never a fare. Only the difference between the old and new route's class price moves — boosts, surcharges and tips on top stay on top — and after a driver has claimed the ride the fare can only go up.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"destination":{"type":"object","description":"{ lat, lng, text? }"}},"required":["destination"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/rides/{id}/driver":{"get":{"operationId":"getApiV1MeRidesByIdDriver","summary":"Live identity of the assigned driver","description":"Name, plate and rating of the driver working this ride, while they are working it. Gated exactly like /driver-location: caller's own ride only (404 otherwise), and the response goes dark when the trip ends. The permanent record stays on GET /api/v1/me/rides/{id}'s driver block.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/rides/{id}/events":{"get":{"operationId":"getApiV1MeRidesByIdEvents","summary":"Incremental event feed for a ride","description":"Cursor-keyed replay of what has changed since the client last asked. The realtime nudge is a Supabase Realtime broadcast on `realtime.topic` (`order:ride:{id}`), published on every lifecycle transition; subscribe to it and call this with the cursor when it fires, or poll at `poll_after_ms` without it. Not SSE/websockets: the deployment is a Cloudflare Worker with no long-lived connections. Events carry `at` (when the row says it happened) beside `observed_at`. Also folds in `driver_location`, `remaining_route` (driver → pickup/drop-off, provider route or a labelled straight-line estimate), `timestamps`, and `actions` — including `can_cancel` from the same cancellation policy the detail and cancel endpoints use, and `can_end_trip`.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from the previous response","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/rides/{id}/end":{"post":{"operationId":"postApiV1MeRidesByIdEnd","summary":"End a Wish / ride early (passenger)","description":"Only while `in_trip` — the same predicate the detail publishes as `actions.can_end_trip`. Idempotent: a repeat answers the same success with `already: true`. Writes `status=completed`, `completed_at` and `wish.earlyEnd`; the driver's trip count is bumped exactly as their own completion would (never on a test job) and both parties are notified. No money moves (Module A). 409 `not_in_trip` / `already_finished` / `RIDE_CHANGED`.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","description":"Max 200 chars"}}}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/rides/{id}/share":{"get":{"operationId":"getApiV1MeRidesByIdShare","summary":"List the rider's trip-sharing links for a ride","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"post":{"operationId":"postApiV1MeRidesByIdShare","summary":"Create a secure trip-sharing link","description":"Mints a 256-bit token (returned once, stored hashed) and a public URL (`GET /api/public/v1/trip-shares/{token}`) that serves a minimised live view: phase, short pickup/drop-off labels, driver first name + plate + vehicle, the car's last position while the trip is active, lifecycle times. Never the rider's name/phone, the driver's phone, the fare or addresses beyond the labels. Default TTL 4h (`ttl_ms`, 10 min – 24 h), at most 5 live links per order, revocable. 409 `order_finished` / `too_many_links`.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"ttl_ms":{"type":"number"}}}}}},"security":[{"userBearer":[]}]},"delete":{"operationId":"deleteApiV1MeRidesByIdShare","summary":"Revoke trip-sharing links","description":"Every live link on the ride, or one by `?id=`.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"query","required":false,"description":"A single share id","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/public/v1/trip-shares/{token}":{"get":{"operationId":"getApiPublicV1TripSharesByToken","summary":"Open a shared trip link (public)","description":"Unauthenticated: the token is the credential. Serves a small HTML page to browsers (auto-refreshes while the trip is active) and the JSON `SharedTripView` to `Accept: application/json` / `?format=json`. Invalid, expired and revoked tokens all answer the same 404. Rate-limited per token.","tags":["Passenger"],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/v1/me/rides/{id}/sos":{"post":{"operationId":"postApiV1MeRidesByIdSos","summary":"Trigger an SOS and notify emergency contacts","description":"Idempotent on `Idempotency-Key` (header or `idempotency_key` body): the same key returns the same event and sends nothing again; without one, presses within a minute collapse. Records the event, mints a share link, and sends one SMS to each VERIFIED emergency contact (optionally narrowed by `contact_ids`) through the configured SMS provider. Every attempt is a `notifications[]` row with a delivery status: `sent`/`failed` with the provider reference, `simulated` on staging without a provider, `skipped:notification_provider_unavailable` elsewhere without one, `skipped:contact_unverified`. 201 on create, 200 on a repeat.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"},"note":{"type":"string"},"contact_ids":{"type":"string"}}}}}},"security":[{"userBearer":[]}]},"get":{"operationId":"getApiV1MeRidesByIdSos","summary":"SOS events on a ride with delivery audit","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"delete":{"operationId":"deleteApiV1MeRidesByIdSos","summary":"Mark an SOS resolved","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"event_id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/rides/{id}/live-activity":{"post":{"operationId":"postApiV1MeRidesByIdLiveActivity","summary":"Register an iOS Live Activity for a ride","description":"Trip-scoped: the ActivityKit push token is bound to this ride only (unique per ride + token; a repeat re-registers). Updates are pushed on every lifecycle transition and an `end` on completion/cancellation/expiry, through APNs when `APNS_*` is configured — `meta.configured: false` means the registration is kept and nothing is faked. 409 `order_finished`.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"push_token":{"type":"string"},"activity_id":{"type":"string"},"platform":{"type":"string","description":"Default ios"}},"required":["push_token"]}}}},"security":[{"userBearer":[]}]},"get":{"operationId":"getApiV1MeRidesByIdLiveActivity","summary":"The caller's Live Activity registrations on a ride","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"delete":{"operationId":"deleteApiV1MeRidesByIdLiveActivity","summary":"End a ride's Live Activities","description":"All of them, or one by `?push_token=`. Sends ActivityKit `end` when APNs is configured.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"push_token","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/da/wishes/{id}/messages":{"get":{"operationId":"getApiV1DaWishesByIdMessages","summary":"Read the passenger chat thread for a held order (driver)","description":"The driver's side of the thread `POST /api/v1/me/rides/{id}/contact {channel:'chat'}` opens. Only for an order this driver holds (`driver_id`); `can_post` reflects the same liveness gate the passenger side applies. `viewer_id` is the caller's own messaging id — compare it with a message's `sender_id` to tell their messages from the passenger's; a client has no other way to learn what JEK calls it.","tags":["Driver Assistant"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"number"}},{"name":"before","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]},"post":{"operationId":"postApiV1DaWishesByIdMessages","summary":"Reply to the passenger (driver)","description":"Sends into the ride's thread, creating it if the passenger has not opened it yet. Only while the driver holds a live order — 409 `RIDE_NOT_LIVE` otherwise. The passenger is pushed the message like any other.","tags":["Driver Assistant"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","description":"Max 4000"}},"required":["body"]}}}},"security":[{"driverBearer":[]}]}},"/api/v1/passenger/trips/{id}/events":{"get":{"operationId":"getApiV1PassengerTripsByIdEvents","summary":"Resumable event feed for a Standard Ride","description":"A position in the trip's audit log (`jek_passenger_trip_events`): `?cursor=` is the last event the client saw, the answer is every passenger-visible event after it in log order, and the new cursor is the last one returned. `?refresh=1` first polls Wonder DA (the detail's refresh leg) so one call both advances the trip and reads what moved. The realtime nudge is the broadcast topic `order:trip:{id}`. Payloads are never spread — each event carries `{id,type,source,from,to,at,detail}`.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"refresh","in":"query","required":false,"description":"`1` to poll upstream first","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/passenger/trips/{id}/end":{"post":{"operationId":"postApiV1PassengerTripsByIdEnd","summary":"End a Standard Ride early (passenger)","description":"Only while `in_progress` — the predicate the detail publishes as `capabilities.allow_early_end_trip`. Idempotent (`already: true` on a repeat). Completes the trip on JEK's side (`status`, `completed_at`, `early_end`) and records `trip.ended_early`; Wonder DA has no passenger-side end, so `upstream.ended` is false and `supply_status` keeps following the supplier's order without ever reopening the trip. 409 `trip_not_in_progress` / `trip_changed`.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string"}}}}}},"security":[{"userBearer":[]}]}},"/api/v1/passenger/trips/{id}/chat":{"post":{"operationId":"postApiV1PassengerTripsByIdChat","summary":"Open a chat thread with the driver of a Standard Ride","description":"The Wonder driver must first resolve to a Driver Pro profile (matched by Wonder id or phone; the outcome is remembered on the trip and is what `capabilities.allow_chat` / `allow_chat_reason` report). Opens the same thread model the Wish lane uses, so `/api/v1/me/messaging/*` and the driver's `/api/v1/da/wishes/{id}/messages` serve it. 409 `driver_not_on_jek` / `TRIP_NO_DRIVER` / `TRIP_NOT_LIVE`. `GET` reads the state without opening.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/passenger/trips/{id}/cancel-reasons":{"get":{"operationId":"getApiV1PassengerTripsByIdCancelReasons","summary":"The managed cancellation-reason catalog for this trip's stage","description":"The same server-owned catalog the Wish lane uses (`system_configs['ride.cancellation']`), filtered to the trip's stage, with `catalog_version`. `POST …/cancel` accepts `reason_code` (or the legacy numeric `reason_id`); only catalog codes are stored as codes, anything else becomes a note. `GET /api/v1/passenger/catalogs` returns the whole catalog with the same version.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/passenger/trips/{id}/share":{"post":{"operationId":"postApiV1PassengerTripsByIdShare","summary":"Create a trip-sharing link for a Standard Ride","description":"Same contract as `POST /api/v1/me/rides/{id}/share`; `GET` lists, `DELETE` revokes (`?id=` for one).","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"ttl_ms":{"type":"number"}}}}}},"security":[{"userBearer":[]}]},"delete":{"operationId":"deleteApiV1PassengerTripsByIdShare","summary":"Revoke trip share links","description":"Revokes one share link when `id` is given, otherwise every share link the caller issued for this trip.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"query","required":false,"description":"The share link to revoke. Omit to revoke all.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/passenger/trips/{id}/sos":{"post":{"operationId":"postApiV1PassengerTripsByIdSos","summary":"Trigger an SOS on a Standard Ride","description":"Same contract as `POST /api/v1/me/rides/{id}/sos`; `GET` lists events with delivery audit, `DELETE ?event_id=` resolves.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"},"note":{"type":"string"},"contact_ids":{"type":"string"}}}}}},"security":[{"userBearer":[]}]},"delete":{"operationId":"deleteApiV1PassengerTripsByIdSos","summary":"Resolve an open SOS","description":"Marks the caller's open SOS event resolved. 404 when no open SOS has that id.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"event_id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/passenger/trips/{id}/live-activity":{"post":{"operationId":"postApiV1PassengerTripsByIdLiveActivity","summary":"Register an iOS Live Activity for a Standard Ride","description":"Same contract as `POST /api/v1/me/rides/{id}/live-activity`, plus the token is bound upstream (Wonder DA `bind_apn_token`, best-effort, `upstream_bound`) once the supplier order exists so Wonder's own updates reach the same activity. `GET` lists, `DELETE ?push_token=` ends.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"push_token":{"type":"string"},"activity_id":{"type":"string"}},"required":["push_token"]}}}},"security":[{"userBearer":[]}]},"delete":{"operationId":"deleteApiV1PassengerTripsByIdLiveActivity","summary":"End the trip's Live Activity","description":"Ends the iOS Live Activity for this trip, on the device named by `push_token` or on all of the caller's devices. The final phase follows the trip status when it is terminal, otherwise `cancelled`.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"push_token","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/rides/{id}/location":{"post":{"operationId":"postApiV1MeRidesByIdLocation","summary":"Publish the passenger's live position","description":"The mirror of /api/v1/da/location: the passenger shares their fix with the assigned driver, only while a driver is coming. Treated as a home address — caller's own ride only, live window enforced, DELETE stops sharing immediately.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"}},"required":["lat","lng"]}}}},"security":[{"userBearer":[]}]},"get":{"operationId":"getApiV1MeRidesByIdLocation","summary":"Read the passenger's shared position / visibility","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"delete":{"operationId":"deleteApiV1MeRidesByIdLocation","summary":"Stop sharing the passenger's position","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/rides/{id}/rating":{"get":{"operationId":"getApiV1MeRidesByIdRating","summary":"Read the rating given for a trip","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"post":{"operationId":"postApiV1MeRidesByIdRating","summary":"Rate a completed trip","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rating":{"type":"number","description":"1–5"},"comment":{"type":"string"}},"required":["rating"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/rides/{id}/related-activities":{"get":{"operationId":"getApiV1MeRidesByIdRelatedActivities","summary":"Recorded payments for the caller's owned ride or wish","description":"JEK session and explicit X-JEK-Env required. Reads Supabase payment legs matched by user_id, exact metadata.ride_id and metadata.payment_env, after checking parent ride ownership, app scope and exact environment. No Wonder customer login or upstream history call. Returns { data: { ride_id, activities: [{ id, ride_id, purpose, amount, currency, status, occurred_at }] } }. Unavailable storage returns 503; no recorded payments returns an empty list. Private, no-store.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/rides/{id}/receipt":{"get":{"operationId":"getApiV1MeRidesByIdReceipt","summary":"Itemised receipt for a ride","description":"An itemised account of what the ride cost and what was actually charged, assembled from the transaction rows and the sealed pricing pin stored at booking. It reports; it does not re-price — editing the rate card later cannot rewrite an issued receipt. `format=html` returns the same receipt as a self-contained printable page (text/html, private, no-store) for the app to show, share, or print to PDF on the device; its language is `lang`, else the account's saved language, else English.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"Default json","schema":{"type":"string"}},{"name":"lang","in":"query","required":false,"description":"HTML only","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/rides/{id}/tip":{"get":{"operationId":"getApiV1MeRidesByIdTip","summary":"Read the tip left on a trip","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"post":{"operationId":"postApiV1MeRidesByIdTip","summary":"Tip the driver after the trip","description":"Adds money for the driver once the trip is finished — the mirror image of /boost, which is only legal while the ride is still waiting. Same ownership check and payment ledger as boost.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","description":"Tip in major currency units (> 0)"}},"required":["amount"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/rides/{id}/payment-order":{"post":{"operationId":"postApiV1MeRidesByIdPaymentOrder","summary":"Open the ride's Wonder payment order (in-app SDK)","description":"Creates ONE Wonder payment order for the ride and returns its `number` plus the `client_secret` the in-app Wonder Payment SDK renders its payment sheet against — no card data, token or 3DS step touches this server. The fare is one `Charge` line and each voucher is a NEGATIVE `Charge` line beside it, so the passenger owes the discounted total and the order itself records why; `jek_rides.fare` is untouched because it is the driver's payout basis. Call it when the passenger is about to pay, not at booking: the client_secret expires in about two hours and Wonder offers no way to mint a second one for an existing order, so a repeat call answers with the order but `client_secret_available: false`. Idempotent by construction — the order is keyed at Wonder on the ride id, and Wonder refuses a duplicate reference, so one ride can never have two orders. 409 FREE_RIDE when a voucher covers the whole fare. Card payment is open on EVERY declared environment — dev and staging hit gateway-stg where no real money moves, while alpha and production share one payment appId and both bill Jek Limited's real merchant record, so alpha is not a rehearsal. Only two things close it: `JEK_RIDE_PAYMENT_ORDERS_ENABLED=0` as an emergency stop, and an environment that has not declared itself, which cannot name the gateway it would bill.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"get":{"operationId":"getApiV1MeRidesByIdPaymentOrder","summary":"Was the ride paid for? (and record it)","description":"Reads the merchant's own order back from Wonder and, when it reports the money arrived, records the fare leg in jek_payment_charges. THE ORDER IS THE AUTHORITY: a client saying the payment sheet succeeded is a claim, `correspondence_state` on Jek Limited's order is a fact. Safe to poll — the charge row is keyed on the ride and leg, so one payment is recorded once however many times this is called. Answers `{data: null}` when no order has been opened.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/coupons":{"get":{"operationId":"getApiV1MeCoupons","summary":"List the caller's ride coupons","description":"With no `status`: this app's live coupons, the caller's exhausted ones included with `usable:false` (unchanged). `status=usable` drops the exhausted ones; `status=expired` lists coupons that lapsed in the last 90 days; `status=used` lists the caller's spends newest first, each with `ride_id`, `used_at`, `amount_off`, `fare_before` and `passenger_pays` as charged. Every item carries `state`: usable | used_up | expired | not_started | inactive. Unknown `status` is 400.","tags":["Passenger"],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"post":{"operationId":"postApiV1MeCoupons","summary":"Price a coupon against a specific trip","description":"Server-side 'HK$230, less HK$40 = HK$190' for the booking screen: prices the selection from the rate card (the same priceSelection the quote and booking routes use) and applies the coupon rule. The request never carries a fare, so the discount cannot be chosen by the client.","tags":["Passenger"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"coupon_id":{"type":"string"},"vehicleTypeId":{"type":"string"},"distanceKm":{"type":"number"}},"required":["coupon_id","vehicleTypeId","distanceKm"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/coupons/{code}":{"get":{"operationId":"getApiV1MeCouponsByCode","summary":"One coupon with its full rules and the caller's state","description":"Any state — usable, used_up, expired, not_started, inactive — with discount type/value, cap, minimum fare, eligible classes, validity window, terms keys and the caller's usage. Searched in this app's catalogue only; an unknown code (or the other brand's) is 404 `coupon_not_found`.","tags":["Passenger"],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/geo/route":{"post":{"operationId":"postApiV1GeoRoute","summary":"Route polyline, distance and ETA between two points","description":"Driving route used to render the booking map and feed distance into fare quotes.","tags":["Geo"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pickup":{"type":"object","description":"{ lat, lng }"},"dropoff":{"type":"object","description":"{ lat, lng }"}},"required":["pickup","dropoff"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/passenger/trips/{id}/{action}":{"post":{"operationId":"postApiV1PassengerTripsByIdByAction","summary":"Trip lifecycle action (driver and passenger)","description":"Multiplexed state-machine action endpoint. Passenger actions and driver actions (arrived, start, end) share the route; the caller's role decides which transitions are allowed.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"action","in":"path","required":true,"description":"e.g. arrived | start | end | rate","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/passenger/transactions":{"get":{"operationId":"getApiV1PassengerTransactions","summary":"Retired passenger history; use JEK self service","tags":["Passenger"],"parameters":[],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/da/vehicle-catalogue":{"get":{"operationId":"getApiV1DaVehicleCatalogue","summary":"Vehicle catalogue for driver registration","description":"Makes / models / classes a driver can bind to their vehicle; the same catalogue M1OS servicing uses.","tags":["Driver Assistant"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/wonder/auth/me":{"post":{"operationId":"postApiWonderAuthMe","summary":"Legacy JEK auth: POST /wonder/auth/me","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/auth/otp/send":{"post":{"operationId":"postApiWonderAuthOtpSend","summary":"Retired: HTTP 410 WONDER_ACCOUNT_SECURITY_RETIRED; use /api/v1/auth/otp/send","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/auth/otp/verify":{"post":{"operationId":"postApiWonderAuthOtpVerify","summary":"Retired: HTTP 410 WONDER_ACCOUNT_SECURITY_RETIRED; use /api/v1/auth/otp/verify","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/auth/pin/status":{"post":{"operationId":"postApiWonderAuthPinStatus","summary":"Retired: HTTP 410 WONDER_ACCOUNT_SECURITY_RETIRED; use JEK password/OTP and device biometrics","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/auth/pin/verify-old":{"post":{"operationId":"postApiWonderAuthPinVerifyOld","summary":"Retired: HTTP 410 WONDER_ACCOUNT_SECURITY_RETIRED; use JEK password/OTP and device biometrics","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/auth/pin/set-new":{"post":{"operationId":"postApiWonderAuthPinSetNew","summary":"Retired: HTTP 410 WONDER_ACCOUNT_SECURITY_RETIRED; use JEK password/OTP and device biometrics","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/auth/pin/forgot-reset":{"post":{"operationId":"postApiWonderAuthPinForgotReset","summary":"Retired: HTTP 410 WONDER_ACCOUNT_SECURITY_RETIRED; use JEK password/OTP and device biometrics","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/account/kyc-status":{"get":{"operationId":"getApiWonderAccountKycStatus","summary":"Legacy JEK account: GET /wonder/account/kyc-status","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/jumio/signup-token":{"post":{"operationId":"postApiWonderJumioSignupToken","summary":"Retired: HTTP 410 WONDER_KYC_PROXY_RETIRED","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/jumio/signin-token":{"post":{"operationId":"postApiWonderJumioSigninToken","summary":"Retired: HTTP 410 WONDER_KYC_PROXY_RETIRED","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/jumio/result":{"post":{"operationId":"postApiWonderJumioResult","summary":"Retired: HTTP 410 WONDER_KYC_PROXY_RETIRED","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/jumio/bind":{"post":{"operationId":"postApiWonderJumioBind","summary":"Retired: HTTP 410 WONDER_KYC_PROXY_RETIRED","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/jumio/event":{"post":{"operationId":"postApiWonderJumioEvent","summary":"Retired: HTTP 410 WONDER_KYC_PROXY_RETIRED","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/taxi/universal-transactions":{"post":{"operationId":"postApiWonderTaxiUniversalTransactions","summary":"Retired Wonder ride transaction feed","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/taxi/related-activities":{"post":{"operationId":"postApiWonderTaxiRelatedActivities","summary":"Retired Wonder ride related activities","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards":{"get":{"operationId":"getApiWonderWalletCards","summary":"GET /wonder/wallet/cards Signed READ-ONLY card list.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/address":{"post":{"operationId":"postApiWonderWalletCardsAddress","summary":"POST /wonder/wallet/cards/address Create a delivery address for the authenticated user's card.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/{cardId}/address/{addressId}":{"put":{"operationId":"putApiWonderWalletCardsByCardIdAddressByAddressId","summary":"PUT /wonder/wallet/cards/:cardId/address/:addressId Update an existing delivery address for the authenticated user's card.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"cardId","in":"path","required":true,"schema":{"type":"string"}},{"name":"addressId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/terminate-reasons":{"get":{"operationId":"getApiWonderWalletCardsTerminateReasons","summary":"GET /wonder/wallet/cards/terminate-reasons READ-ONLY list of card termination reason options.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/material":{"get":{"operationId":"getApiWonderWalletCardsMaterial","summary":"GET /wonder/wallet/cards/material Signed READ-ONLY card material type list for physical card application.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/fee-rules/{currency}":{"get":{"operationId":"getApiWonderWalletCardsFeeRulesByCurrency","summary":"GET /wonder/wallet/cards/fee-rules/:currency Public READ-ONLY card fee rules for a currency.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"currency","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/{cardId}":{"get":{"operationId":"getApiWonderWalletCardsByCardId","summary":"GET /wonder/wallet/cards/:cardId Signed READ-ONLY card detail.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"cardId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/ledger-balance":{"get":{"operationId":"getApiWonderWalletLedgerBalance","summary":"GET /wonder/wallet/ledger-balance Signed READ-ONLY ledger balance.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/fund-sources":{"get":{"operationId":"getApiWonderWalletFundSources","summary":"GET /wonder/wallet/fund-sources Signed READ-ONLY fund sources.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/fund-sources/sort":{"put":{"operationId":"putApiWonderWalletFundSourcesSort","summary":"PUT /wonder/wallet/fund-sources/sort Mirrors Flutter wallet.api.dart userFundSourcesSort(): PUT /svc/ts/api/v2/b2c/user_fund_sources/sort Bo","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/digital-wallet/currencies":{"get":{"operationId":"getApiWonderWalletDigitalWalletCurrencies","summary":"GET /wonder/wallet/digital-wallet/currencies Signed READ-ONLY list of supported digital wallet currencies (USDT etc).","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/digital-wallet/networks/{currency}":{"get":{"operationId":"getApiWonderWalletDigitalWalletNetworksByCurrency","summary":"GET /wonder/wallet/digital-wallet/networks/:currency Signed READ-ONLY list of blockchain networks for a digital currency.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"currency","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/digital-wallet/wallet":{"post":{"operationId":"postApiWonderWalletDigitalWalletWallet","summary":"POST /wonder/wallet/digital-wallet/wallet Signed READ-ONLY retrieval of the authenticated user's existing digital wallet address for a speci","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/txn/list":{"get":{"operationId":"getApiWonderWalletTxnList","summary":"Currency activity history via POST /svc/ts/api/v2/activities, scoped to the authenticated Kash account and billing currency.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/txn/card/{id}":{"get":{"operationId":"getApiWonderWalletTxnCardById","summary":"GET /wonder/wallet/txn/card/:id Signed READ-ONLY card transaction detail.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/txn/payin/{id}":{"get":{"operationId":"getApiWonderWalletTxnPayinById","summary":"GET /wonder/wallet/txn/payin/:id Signed READ-ONLY payin (top-up) request detail.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/txn/payout/{id}":{"get":{"operationId":"getApiWonderWalletTxnPayoutById","summary":"GET /wonder/wallet/txn/payout/:id Signed READ-ONLY payout (send) request detail.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/txn/fund-source/{id}":{"get":{"operationId":"getApiWonderWalletTxnFundSourceById","summary":"GET /wonder/wallet/txn/fund-source/:id Signed READ-ONLY fund-source transaction detail.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/txn/related/{type}/{id}":{"get":{"operationId":"getApiWonderWalletTxnRelatedByTypeById","summary":"GET /wonder/wallet/txn/related/:type/:id Signed READ-ONLY related activities for a transaction.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/rebate-schemes":{"get":{"operationId":"getApiWonderWalletRebateSchemes","summary":"Read Wonder's public rebate scheme catalog for the declared app environment.","description":"Requires a JEK login and product membership. Returns {schemes, activeIds}. The server reads /svc/ts/public/api/v1/rebate_schemes without forwarding user or business credentials; card KYC, a reconciled holder and a business grant are not prerequisites for this metadata.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"X-JEK-Env","in":"header","required":true,"description":"staging, alpha or production; alpha uses the production card program.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/{cardId}/physical-deliver":{"get":{"operationId":"getApiWonderWalletCardsByCardIdPhysicalDeliver","summary":"GET /wonder/wallet/cards/:cardId/physical-deliver Signed READ-ONLY physical card delivery status for a given card.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"cardId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/{cardId}/verification-blacklists":{"get":{"operationId":"getApiWonderWalletCardsByCardIdVerificationBlacklists","summary":"GET /wonder/wallet/cards/:cardId/verification-blacklists Signed READ-ONLY verification blacklist check for a card.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"cardId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/virtual":{"post":{"operationId":"postApiWonderWalletCardsVirtual","summary":"Create a virtual JEK Card on the selected network.","description":"Body `{issuer_brand?: JCB|UnionPay, settlement_currency?: HKD|USD}`. The legacy `channel` field is also accepted; conflicting network fields are rejected and omitted networks remain JCB. Wonder GET /svc/ts/api/v2/card_issuers and the admin application/no-KYC gates determine availability. Creates through POST /svc/ts/api/v1/openapi/cards with card.issuer_brand; retains the existing identity, limits and single-live-card checks.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/emv-qr":{"post":{"operationId":"postApiWonderWalletEmvQr","summary":"Retired: HTTP 410 QR_LEGACY_RETIRED","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/check-atc":{"post":{"operationId":"postApiWonderWalletCheckAtc","summary":"Retired: HTTP 410 QR_LEGACY_RETIRED","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/txn/card-by-auth/{authId}":{"get":{"operationId":"getApiWonderWalletTxnCardByAuthByAuthId","summary":"GET /wonder/wallet/txn/card-by-auth/:authId Signed READ-ONLY card transaction lookup by Wonder auth_id.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"authId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/order/valuation":{"post":{"operationId":"postApiWonderWalletCardsOrderValuation","summary":"POST /wonder/wallet/cards/order/valuation Estimate the cost of a physical card order (material fee + promotions).","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/physical":{"post":{"operationId":"postApiWonderWalletCardsPhysical","summary":"POST /wonder/wallet/cards/physical Create a physical card order (apply / replace / lost-reissue).","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/free-pay":{"post":{"operationId":"postApiWonderWalletCardsFreePay","summary":"POST /wonder/wallet/cards/free-pay Zero-amount payment for a physical card order when the total is 0.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/paid-pay":{"post":{"operationId":"postApiWonderWalletCardsPaidPay","summary":"POST /wonder/wallet/cards/paid-pay Vault-card SALE payment for a physical card order when the valuation total is greater than zero.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/verification-token":{"post":{"operationId":"postApiWonderWalletCardsVerificationToken","summary":"POST /wonder/wallet/cards/verification-token Creates a Wonder verification token for a card-status write action (unlock, terminate).","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/spend-limit-otp/send":{"post":{"operationId":"postApiWonderWalletCardsSpendLimitOtpSend","summary":"POST /wonder/wallet/cards/spend-limit-otp/send Step 2 of the 5-step spend-limit OTP flow.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/spend-limit-otp/verify":{"post":{"operationId":"postApiWonderWalletCardsSpendLimitOtpVerify","summary":"POST /wonder/wallet/cards/spend-limit-otp/verify Step 4 of the 5-step spend-limit OTP flow.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/{cardId}/status":{"put":{"operationId":"putApiWonderWalletCardsByCardIdStatus","summary":"PUT /wonder/wallet/cards/:cardId/status Changes a JEK card's status: \"locked\", \"active\" (unlock), or \"terminated\".","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"cardId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/{cardId}/edit":{"put":{"operationId":"putApiWonderWalletCardsByCardIdEdit","summary":"PUT /wonder/wallet/cards/:cardId/edit Updates Transaction and Daily spend limits for a JEK card after OTP verification.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"cardId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/v1/hce/issue_token":{"post":{"operationId":"postApiWonderV1HceIssueToken","summary":"Pass through to /svc/ts/api/v1/hce/issue_token. Only top-level appUserId uses the authenticated account's bound Wonder ID. Other request bytes, response bodies and provider HTTP status are preserved. JEK session/environment authorization and server-held Wonder authentication apply.","tags":["Wonder Treasury HCE and QR proxy"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/v1/hce/change_token_state":{"post":{"operationId":"postApiWonderV1HceChangeTokenState","summary":"Pass through to /svc/ts/api/v1/hce/change_token_state. Only top-level appUserId uses the authenticated account's bound Wonder ID. Other request bytes, response bodies and provider HTTP status are preserved. JEK session/environment authorization and server-held Wonder authentication apply.","tags":["Wonder Treasury HCE and QR proxy"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/v1/hce/replenish_luk":{"post":{"operationId":"postApiWonderV1HceReplenishLuk","summary":"Pass through to /svc/ts/api/v1/hce/replenish_luk. Only top-level appUserId uses the authenticated account's bound Wonder ID. Other request bytes, response bodies and provider HTTP status are preserved. JEK session/environment authorization and server-held Wonder authentication apply.","tags":["Wonder Treasury HCE and QR proxy"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/v1/hce/report_transaction":{"post":{"operationId":"postApiWonderV1HceReportTransaction","summary":"Pass through to /svc/ts/api/v1/hce/report_transaction. Only top-level appUserId uses the authenticated account's bound Wonder ID. Other request bytes, response bodies and provider HTTP status are preserved. JEK session/environment authorization and server-held Wonder authentication apply.","tags":["Wonder Treasury HCE and QR proxy"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/v1/hce/update_token_metadata":{"post":{"operationId":"postApiWonderV1HceUpdateTokenMetadata","summary":"Pass through to /svc/ts/api/v1/hce/update_token_metadata. Only top-level appUserId uses the authenticated account's bound Wonder ID. Other request bytes, response bodies and provider HTTP status are preserved. JEK session/environment authorization and server-held Wonder authentication apply.","tags":["Wonder Treasury HCE and QR proxy"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/v1/hce/list_tokens":{"post":{"operationId":"postApiWonderV1HceListTokens","summary":"Pass through to /svc/ts/api/v1/hce/list_tokens. Only top-level appUserId uses the authenticated account's bound Wonder ID. Other request bytes, response bodies and provider HTTP status are preserved. JEK session/environment authorization and server-held Wonder authentication apply.","tags":["Wonder Treasury HCE and QR proxy"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/v1/qr/inquire_merchant_qr":{"post":{"operationId":"postApiWonderV1QrInquireMerchantQr","summary":"Pass through to /svc/ts/api/v1/qr/inquire_merchant_qr. Only top-level appUserId uses the authenticated account's bound Wonder ID. Other request bytes, response bodies and provider HTTP status are preserved. JEK session/environment authorization and server-held Wonder authentication apply.","tags":["Wonder Treasury HCE and QR proxy"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/v1/qr/pay_merchant_qr":{"post":{"operationId":"postApiWonderV1QrPayMerchantQr","summary":"Pass through to /svc/ts/api/v1/qr/pay_merchant_qr. Only top-level appUserId uses the authenticated account's bound Wonder ID. Other request bytes, response bodies and provider HTTP status are preserved. JEK session/environment authorization and server-held Wonder authentication apply.","tags":["Wonder Treasury HCE and QR proxy"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/v1/qr/generate_consumer_qr":{"post":{"operationId":"postApiWonderV1QrGenerateConsumerQr","summary":"Pass through to /svc/ts/api/v1/qr/generate_consumer_qr. Only top-level appUserId uses the authenticated account's bound Wonder ID. Other request bytes, response bodies and provider HTTP status are preserved. JEK session/environment authorization and server-held Wonder authentication apply.","tags":["Wonder Treasury HCE and QR proxy"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/v1/qr/inquire_consumer_qr_cvm":{"post":{"operationId":"postApiWonderV1QrInquireConsumerQrCvm","summary":"Pass through to /svc/ts/api/v1/qr/inquire_consumer_qr_cvm. Only top-level appUserId uses the authenticated account's bound Wonder ID. Other request bytes, response bodies and provider HTTP status are preserved. JEK session/environment authorization and server-held Wonder authentication apply.","tags":["Wonder Treasury HCE and QR proxy"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/v1/qr/submit_consumer_qr_cvm":{"post":{"operationId":"postApiWonderV1QrSubmitConsumerQrCvm","summary":"Pass through to /svc/ts/api/v1/qr/submit_consumer_qr_cvm. Only top-level appUserId uses the authenticated account's bound Wonder ID. Other request bytes, response bodies and provider HTTP status are preserved. JEK session/environment authorization and server-held Wonder authentication apply.","tags":["Wonder Treasury HCE and QR proxy"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/v1/qr/inquire_transaction":{"post":{"operationId":"postApiWonderV1QrInquireTransaction","summary":"Pass through to /svc/ts/api/v1/qr/inquire_transaction. Only top-level appUserId uses the authenticated account's bound Wonder ID. Other request bytes, response bodies and provider HTTP status are preserved. JEK session/environment authorization and server-held Wonder authentication apply.","tags":["Wonder Treasury HCE and QR proxy"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/v1/qr/list_transactions":{"post":{"operationId":"postApiWonderV1QrListTransactions","summary":"Pass through to /svc/ts/api/v1/qr/list_transactions. Only top-level appUserId uses the authenticated account's bound Wonder ID. Other request bytes, response bodies and provider HTTP status are preserved. JEK session/environment authorization and server-held Wonder authentication apply.","tags":["Wonder Treasury HCE and QR proxy"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/pci-card-reveal":{"post":{"operationId":"postApiWonderWalletCardsPciCardReveal","summary":"POST /wonder/wallet/cards/pci-card-reveal Reveals the full PAN, expiry, CVV, and cardholder name for a JEK Card using the Wonder PCI session","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/physical/not-received":{"post":{"operationId":"postApiWonderWalletCardsPhysicalNotReceived","summary":"POST /wonder/wallet/cards/physical/not-received Reports that a physical card has not been received.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/physical/code-check":{"post":{"operationId":"postApiWonderWalletCardsPhysicalCodeCheck","summary":"POST /wonder/wallet/cards/physical/code-check Validates a physical card activation code before PIN setup.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/pci-session":{"post":{"operationId":"postApiWonderWalletCardsPciSession","summary":"Retired: HTTP 410 WONDER_RAW_PCI_RETIRED","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/pci-card-with-session":{"post":{"operationId":"postApiWonderWalletCardsPciCardWithSession","summary":"Retired: HTTP 410 WONDER_RAW_PCI_RETIRED","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/pci-pin-with-session":{"post":{"operationId":"postApiWonderWalletCardsPciPinWithSession","summary":"POST /wonder/wallet/cards/pci-pin-with-session Sets a card PIN (new card activation or ATM PIN change).","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/pci-pin-verify-with-session":{"post":{"operationId":"postApiWonderWalletCardsPciPinVerifyWithSession","summary":"POST /wonder/wallet/cards/pci-pin-verify-with-session Verifies the current card PIN (ATM PIN change step 1).","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/send/user-search":{"get":{"operationId":"getApiWonderWalletSendUserSearch","summary":"GET /wonder/wallet/send/user-search Signed search for a transfer recipient by phone number, email, or display name.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/send/fee-lookup":{"post":{"operationId":"postApiWonderWalletSendFeeLookup","summary":"POST /wonder/wallet/send/fee-lookup Calculates the transfer fee for a given currency + amount before the user commits.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/send/fx-quote":{"post":{"operationId":"postApiWonderWalletSendFxQuote","summary":"POST /wonder/wallet/send/fx-quote Requests an FX quote for a cross-currency payout.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/send/otp":{"post":{"operationId":"postApiWonderWalletSendOtp","summary":"Retired: HTTP 410 RAW_PAYOUT_OTP_RETIRED before provider/session dependencies","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/send/payout/{requestId}/status":{"post":{"operationId":"postApiWonderWalletSendPayoutByRequestIdStatus","summary":"POST /wonder/wallet/send/payout/:requestId/status Polls the status of a submitted payout request.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/digital-wallet/create":{"post":{"operationId":"postApiWonderWalletDigitalWalletCreate","summary":"POST /wonder/wallet/digital-wallet/create Creates a new digital wallet address for the authenticated user for a given chain + asset.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/digital-wallet/check/{id}":{"post":{"operationId":"postApiWonderWalletDigitalWalletCheckById","summary":"POST /wonder/wallet/digital-wallet/check/:id Polls a pending digital wallet creation until it reaches \"Active\" status.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/statement/first-create-time":{"post":{"operationId":"postApiWonderStatementFirstCreateTime","summary":"POST /wonder/statement/first-create-time Fetches the date of the user's first Wonder card creation via a signed Taxi Gateway call.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/statement/preview":{"post":{"operationId":"postApiWonderStatementPreview","summary":"POST /wonder/statement/preview Starts async PDF generation for a calendar month via an UNSIGNED Galaxy Gateway call.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/statement/check":{"post":{"operationId":"postApiWonderStatementCheck","summary":"POST /wonder/statement/check Polls the Galaxy Gateway for the status of an async PDF generation task.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/wonder-link":{"get":{"operationId":"getApiV1MeWonderLink","summary":"Fresh eKYC and Card/Kash recovery progress","description":"JEK only; explicit x-jek-env. Owned fresh-policy KYC/status/identity_stored and reconciliation state/card_state/kash_state/error_code. Old approvals never count. New financial business, no document attributes or user tokens returned. docs/86.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"post":{"operationId":"postApiV1MeWonderLink","summary":"Recover your financial identity after fresh eKYC","description":"Requires fresh current-policy Jumio approval and encrypted identity first. Leased job: canonical verified phone lookup, compare legacy document before immutable binding, or create a new user from verified extraction. Returns retry/action_required progress for provider/missing-contract failures. Reuses known owned cards; never creates a card or credits a balance. User sessions deferred. docs/86.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/payees/{id}/transactions":{"get":{"operationId":"getApiWonderWalletPayeesByIdTransactions","summary":"The caller's wallet payouts to one payee","description":"Separate wallet provider contract. Requires the JEK session and caller's reconciled wallet session. Requests only Payout rows and checks the returned payee id; does not supply ride or wish history.","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"offset","in":"query","required":false,"schema":{"type":"number"}},{"name":"limit","in":"query","required":false,"schema":{"type":"number"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/transactions":{"get":{"operationId":"getApiWonderWalletTransactions","summary":"Retired shared Wonder transaction history","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/action-otp/send":{"post":{"operationId":"postApiWonderWalletCardsActionOtpSend","summary":"POST /wonder/wallet/cards/action-otp/send { action, verification_token } → POST /user/b2c/otp/send { action, phone, verification_token } → {","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/action-otp/verify":{"post":{"operationId":"postApiWonderWalletCardsActionOtpVerify","summary":"POST /wonder/wallet/cards/action-otp/verify { action, aut_code, verification_token, token?","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/payees":{"get":{"operationId":"getApiWonderWalletPayees","summary":"GET /wonder/wallet/payees?offset&limit&phone&email → GET /svc/ts/api/v1/user/payees → { payees }","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/payees/recent":{"get":{"operationId":"getApiWonderWalletPayeesRecent","summary":"GET /wonder/wallet/payees/recent → GET /svc/ts/api/v1/user/payees/recent → { payees }","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/payees/{id}":{"get":{"operationId":"getApiWonderWalletPayeesById","summary":"GET /wonder/wallet/payees/:id → { payee }","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"put":{"operationId":"putApiWonderWalletPayeesById","summary":"PUT /wonder/wallet/payees/:id { nickname } → PUT /svc/ts/api/v1/user/payees/{id} → { ok }","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"delete":{"operationId":"deleteApiWonderWalletPayeesById","summary":"DELETE /wonder/wallet/payees/:id → DELETE /svc/ts/api/v1/user/payees/{id} → { ok }","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/order/promotion-check":{"post":{"operationId":"postApiWonderWalletCardsOrderPromotionCheck","summary":"POST /wonder/wallet/cards/order/promotion-check { promotion_code } → { isAvailable }","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/app-config":{"get":{"operationId":"getApiWonderWalletAppConfig","summary":"Retired: returns HTTP 410 LEGACY_METADATA_RETIRED; current apps use bundled vehicle names and artwork","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/taxi-orders/{id}/receipt":{"post":{"operationId":"postApiWonderWalletTaxiOrdersIdReceipt","summary":"Compatibility alias: JEK-generated PDF from the caller's verified Wonder order → { url, expiresIn }; no Wonder PDF helper","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/taxi-evaluation-options":{"get":{"operationId":"getApiWonderWalletTaxiEvaluationOptions","summary":"Retired: HTTP 410 WONDER_RIDE_PROXY_RETIRED","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/taxi-orders/{id}/evaluation":{"post":{"operationId":"postApiWonderWalletTaxiOrdersIdEvaluation","summary":"Retired: HTTP 410 WONDER_RIDE_PROXY_RETIRED","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/txn/receive/{id}":{"get":{"operationId":"getApiWonderWalletTxnReceiveId","summary":"GET /wonder/wallet/txn/receive/:id → v1 digital_wallet transaction { txn } (legacy ReceiveDetail)","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/txn/send/{id}":{"get":{"operationId":"getApiWonderWalletTxnSendId","summary":"GET /wonder/wallet/txn/send/:id → v1 payout_request { txn } (legacy SendDetail)","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/taxi-orders/{id}/payment":{"get":{"operationId":"getApiWonderWalletTaxiOrdersByIdPayment","summary":"Retired: HTTP 410 WONDER_RIDE_PROXY_RETIRED","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"post":{"operationId":"postApiWonderWalletTaxiOrdersByIdPayment","summary":"Retired: HTTP 410 WONDER_RIDE_PROXY_RETIRED","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/taxi-orders/{id}":{"get":{"operationId":"getApiWonderWalletTaxiOrdersId","summary":"Retired: HTTP 410 WONDER_RIDE_PROXY_RETIRED","tags":["JEK Wallet (legacy Wonder)"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/advertise":{"get":{"operationId":"getApiWonderWalletAdvertise","summary":"Retired: returns HTTP 410 LEGACY_METADATA_RETIRED; link-card advertising removed","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/fund-sources/ledger-currency":{"put":{"operationId":"putApiWonderWalletFundSourcesLedgerCurrency","summary":"PUT /wonder/wallet/fund-sources/ledger-currency { currency } → { fundingSources }","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/auth/biology":{"post":{"operationId":"postApiWonderAuthBiology","summary":"Retired: HTTP 410 WONDER_ACCOUNT_SECURITY_RETIRED; use JEK password/OTP and device biometrics","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"get":{"operationId":"getApiWonderAuthBiology","summary":"Retired: HTTP 410 WONDER_ACCOUNT_SECURITY_RETIRED; use JEK password/OTP and device biometrics","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/fund-sources/payment-methods":{"get":{"operationId":"getApiWonderWalletFundSourcesPaymentMethods","summary":"GET /wonder/wallet/fund-sources/payment-methods → business Bearer + saved X-P-Business-ID → openapi/payment_methods reduced to brands both cit and mit allow → { paymentMethods }; provider diagnostics are surfaced","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/fund-sources/cards":{"post":{"operationId":"postApiWonderWalletFundSourcesCards","summary":"POST /wonder/wallet/fund-sources/cards {} → business Bearer customer by JEK reference → hosted create-only wallet link; returns an encrypted verification handle; no PAN/CVV input","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/fund-sources/cards/verify":{"post":{"operationId":"postApiWonderWalletFundSourcesCardsVerify","summary":"POST /wonder/wallet/fund-sources/cards/verify { verifyUuid } → owned new token check/readback and Treasury funding membership → { verified, state }; no customer session","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/fund-sources/remove":{"post":{"operationId":"postApiWonderWalletFundSourcesRemove","summary":"POST /wonder/wallet/fund-sources/remove { id } → owned source token matched to JEK customer's vault → business Bearer DELETE /svc/payment/api/v1/openapi/customers/{uuid}/payment_tokens { token } → readback before { ok }","tags":["JEK Wallet (legacy Wonder)"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/standard-rides/quotes":{"post":{"operationId":"postApiV1StandardRidesQuotes","summary":"Quote a Standard Ride","description":"JEK bearer and the caller's Wonder session are required. JSON body: pickup, dropoff and optional stops; returns batchId, quotes and optional route.","tags":["Standard Ride compatibility"],"parameters":[{"name":"X-JEK-Env","in":"header","required":true,"schema":{"type":"string"}}],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/standard-rides/nearby":{"post":{"operationId":"postApiV1StandardRidesNearby","summary":"Find nearby taxis for a Standard Ride","description":"JEK bearer and the caller's Wonder session are required. JSON body: lat, lng, radius?; returns env and taxis.","tags":["Standard Ride compatibility"],"parameters":[{"name":"X-JEK-Env","in":"header","required":true,"schema":{"type":"string"}}],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/standard-rides/pickup-serviceability":{"post":{"operationId":"postApiV1StandardRidesPickupServiceability","summary":"Check Standard Ride pickup serviceability","description":"JEK bearer and the caller's Wonder session are required. JSON body: lat and lng; returns whether this pickup can be quoted.","tags":["Standard Ride compatibility"],"parameters":[{"name":"X-JEK-Env","in":"header","required":true,"schema":{"type":"string"}}],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/standard-rides/orders":{"post":{"operationId":"postApiV1StandardRidesOrders","summary":"Book a quoted Standard Ride","description":"JEK bearer and the caller's Wonder session are required. JSON body: batchId, selectedQuoteIds, accessPointId?; returns order.","tags":["Standard Ride compatibility"],"parameters":[{"name":"X-JEK-Env","in":"header","required":true,"schema":{"type":"string"}}],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/standard-rides/live-activity/token":{"post":{"operationId":"postApiV1StandardRidesLiveActivityToken","summary":"Bind a Standard Ride live-activity push token","description":"JEK bearer and the caller's Wonder session are required. JSON body: orderId and pushToken; returns bound.","tags":["Standard Ride compatibility"],"parameters":[{"name":"X-JEK-Env","in":"header","required":true,"schema":{"type":"string"}}],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/standard-rides/order-list":{"post":{"operationId":"postApiV1StandardRidesOrderList","summary":"List the caller's Standard Rides","description":"JEK bearer and the caller's Wonder session are required. JSON body: offset?, limit? and order filters; returns orders.","tags":["Standard Ride compatibility"],"parameters":[{"name":"X-JEK-Env","in":"header","required":true,"schema":{"type":"string"}}],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/standard-rides/order-detail":{"post":{"operationId":"postApiV1StandardRidesOrderDetail","summary":"Read a Standard Ride","description":"JEK bearer and the caller's Wonder session are required. JSON body: orderId and liveDetail?; returns order.","tags":["Standard Ride compatibility"],"parameters":[{"name":"X-JEK-Env","in":"header","required":true,"schema":{"type":"string"}}],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/standard-rides/locations-quote":{"post":{"operationId":"postApiV1StandardRidesLocationsQuote","summary":"Quote a Standard Ride destination change","description":"JEK bearer and the caller's Wonder session are required. JSON body: orderId, destination and additionalStops?; returns quote.","tags":["Standard Ride compatibility"],"parameters":[{"name":"X-JEK-Env","in":"header","required":true,"schema":{"type":"string"}}],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/standard-rides/locations-confirm":{"post":{"operationId":"postApiV1StandardRidesLocationsConfirm","summary":"Confirm a Standard Ride destination change","description":"JEK bearer and the caller's Wonder session are required. JSON body: orderId and quoteId; returns status and optional quote.","tags":["Standard Ride compatibility"],"parameters":[{"name":"X-JEK-Env","in":"header","required":true,"schema":{"type":"string"}}],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/standard-rides/status":{"post":{"operationId":"postApiV1StandardRidesStatus","summary":"Read Standard Ride status","description":"JEK bearer and the caller's Wonder session are required. JSON body: orderId; returns the current status.","tags":["Standard Ride compatibility"],"parameters":[{"name":"X-JEK-Env","in":"header","required":true,"schema":{"type":"string"}}],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/standard-rides/ride":{"post":{"operationId":"postApiV1StandardRidesRide","summary":"Read Standard Ride live driver information","description":"JEK bearer and the caller's Wonder session are required. JSON body: orderId; returns the current ride.","tags":["Standard Ride compatibility"],"parameters":[{"name":"X-JEK-Env","in":"header","required":true,"schema":{"type":"string"}}],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/standard-rides/router":{"post":{"operationId":"postApiV1StandardRidesRouter","summary":"Read Standard Ride routing information","description":"JEK bearer and the caller's Wonder session are required. JSON body: orderId; returns routing data.","tags":["Standard Ride compatibility"],"parameters":[{"name":"X-JEK-Env","in":"header","required":true,"schema":{"type":"string"}}],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/standard-rides/evaluation-options":{"post":{"operationId":"postApiV1StandardRidesEvaluationOptions","summary":"List Standard Ride evaluation options","description":"JEK bearer and the caller's Wonder session are required. JSON body: Returns options.","tags":["Standard Ride compatibility"],"parameters":[{"name":"X-JEK-Env","in":"header","required":true,"schema":{"type":"string"}}],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/standard-rides/evaluate":{"post":{"operationId":"postApiV1StandardRidesEvaluate","summary":"Evaluate a Standard Ride","description":"JEK bearer and the caller's Wonder session are required. JSON body: orderId, stars, optionIds?, remark?, driverId?; returns ok.","tags":["Standard Ride compatibility"],"parameters":[{"name":"X-JEK-Env","in":"header","required":true,"schema":{"type":"string"}}],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/standard-rides/update-order":{"post":{"operationId":"postApiV1StandardRidesUpdateOrder","summary":"Update a Standard Ride's selected quotes","description":"JEK bearer and the caller's Wonder session are required. JSON body: orderId, batchId and selectedQuoteIds; returns ok.","tags":["Standard Ride compatibility"],"parameters":[{"name":"X-JEK-Env","in":"header","required":true,"schema":{"type":"string"}}],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/standard-rides/universal-transactions":{"post":{"operationId":"postApiV1StandardRidesUniversalTransactions","summary":"Retired shared Wonder ride history","description":"Returns 410 WONDER_HISTORY_RETIRED. Use owned JEK ride history and related activities with the JEK session and explicit X-JEK-Env. The bridge retirement policy marks this operation deprecated.","tags":["Standard Ride compatibility"],"parameters":[],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/standard-rides/related-activities":{"post":{"operationId":"postApiV1StandardRidesRelatedActivities","summary":"Retired shared Wonder ride history","description":"Returns 410 WONDER_HISTORY_RETIRED. Use owned JEK ride history and related activities with the JEK session and explicit X-JEK-Env. The bridge retirement policy marks this operation deprecated.","tags":["Standard Ride compatibility"],"parameters":[],"deprecated":true,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/address-autocomplete":{"post":{"operationId":"postApiWonderWalletAddressAutocomplete","summary":"Search delivery addresses","description":"JSON { input, session_token, lat?, lng? }. Returns autocomplete suggestions for card delivery.","tags":["JEK Wallet"],"parameters":[{"name":"X-JEK-Env","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/address-place":{"post":{"operationId":"postApiWonderWalletAddressPlace","summary":"Resolve a delivery address suggestion","description":"JSON { place_id, session_token }. Returns the selected place.","tags":["JEK Wallet"],"parameters":[{"name":"X-JEK-Env","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/card-transactions":{"get":{"operationId":"getApiWonderWalletCardTransactions","summary":"List transactions for an owned card","description":"Query card_id? (owned card selector), offset? (default 0) and limit? (1–100, default 50). Returns transactions with card, currency, amount, fee and merchant fields.","tags":["JEK Wallet"],"parameters":[{"name":"X-JEK-Env","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/digital-wallet/transactions":{"get":{"operationId":"getApiWonderWalletDigitalWalletTransactions","summary":"List inbound deposits for an owned digital wallet","description":"Query walletId (UUID), offset? (default 0), limit? (1–100, default 30), and optional startAt/endAt date range. Returns transactions and hasMore after verifying wallet ownership.","tags":["JEK Wallet"],"parameters":[{"name":"X-JEK-Env","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/physical/verification/start":{"post":{"operationId":"postApiWonderWalletCardsPhysicalVerificationStart","summary":"Start identity verification for physical-card activation","description":"JSON { referenceId }. Requires the caller's own live card. Returns sdkToken, dataCenter, expiresAt and a session-bound activation ticket.","tags":["JEK Wallet"],"parameters":[{"name":"X-JEK-Env","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/wonder/wallet/cards/physical/verification/confirm":{"post":{"operationId":"postApiWonderWalletCardsPhysicalVerificationConfirm","summary":"Confirm identity verification for physical-card activation","description":"JSON { referenceId, ticket }. Checks the authoritative owned workflow; returns an approved activation ticket only after approval. A completed SDK capture alone is insufficient.","tags":["JEK Wallet"],"parameters":[{"name":"X-JEK-Env","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/da/jobs/realtime":{"get":{"operationId":"getApiV1DaJobsRealtime","summary":"Get connection parameters for private driver job updates","description":"Requires the driver's environment-bound session. Returns the public realtime URL/key and authorized environment and driver topics. Subscribe using the existing driver bearer; no passenger or order data is returned by this endpoint.","tags":["Driver Assistant"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/me/card/3ds":{"get":{"operationId":"getApiV1MeCard3ds","summary":"List the caller's card purchase verifications or read one by ID","description":"Requires JEK membership and an explicit supported card program. Returns only the caller's challenges. Responses are private and not cached.","tags":["JEK Card"],"parameters":[{"name":"X-JEK-Env","in":"header","required":true,"description":"staging or production; alpha is unsupported.","schema":{"type":"string"}},{"name":"id","in":"query","required":false,"description":"Read one owned challenge by UUID.","schema":{"type":"string"}},{"name":"before","in":"query","required":false,"description":"Pagination cursor when listing challenges.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"post":{"operationId":"postApiV1MeCard3ds","summary":"Approve or reject an owned card purchase verification","description":"Requires JEK membership and an explicit supported card program. JSON body contains only id and action; maximum body size is 1 KiB. Responses are private and not cached.","tags":["JEK Card"],"parameters":[{"name":"X-JEK-Env","in":"header","required":true,"description":"staging or production; alpha is unsupported.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Owned challenge UUID."},"action":{"type":"string","description":"approve or reject."}},"required":["id","action"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/ride-booking-requests/resolve":{"post":{"operationId":"postApiV1MeRideBookingRequestsResolve","summary":"Resolve an uncertain ride booking by its original booking key","description":"Returns status found with ride_id, or not_created after durably closing the absent key so a delayed original request cannot create a ride. Scoped to the caller, product and environment. Returns 503 BOOKING_RECOVERY_UNAVAILABLE when the original outcome cannot be confirmed.","tags":["Passenger"],"parameters":[{"name":"X-JEK-Env","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"booking_key":{"type":"string","description":"Original booking key, 1–200 characters without surrounding whitespace."}},"required":["booking_key"]}}}},"security":[{"userBearer":[]}]}},"/api/registry/jumio/signup":{"post":{"operationId":"postApiRegistryJumioSignup","summary":"Create or resume the signed-in JEK account's Jumio SDK workflow","description":"Requires JEK membership and x-jek-env (staging/alpha/production). Server-side Jumio OAuth credentials and workflow are configured at /admin/jumio. Creation is durably reserved and limited to five attempts per 24 hours; ambiguous creation does not re-POST. Returns data.workflow_id, account_id, sdk_token, data_center and expires_at; never OAuth credentials.","tags":["Identity verification"],"parameters":[{"name":"x-jek-env","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","description":"Keep the same request ID on transport retry."},"category_value":{"type":"string","description":"ID_CARD (default), PASSPORT or DRIVING_LICENSE."},"country_value":{"type":"string","description":"Uppercase ISO alpha-3; default HKG."}},"required":["request_id"]}}}},"security":[{"userBearer":[]}]}},"/api/registry/jumio/bind":{"post":{"operationId":"postApiRegistryJumioBind","summary":"Record submission or cancellation of an owned Jumio workflow","description":"Requires JEK membership and x-jek-env. Takes workflow_id and outcome (submitted/cancelled). This does not approve verification. Cancellation checks Jumio retrieval before discarding an acquired workflow.","tags":["Identity verification"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/registry/jumio/status":{"get":{"operationId":"getApiRegistryJumioStatus","summary":"Retrieve the caller's authoritative Jumio KYC status","description":"Requires JEK membership and x-jek-env. Returns data.kyc_status, workflow_id and can_resume. Only overall PROCESSED/PASSED results grant approval; warnings remain pending review. Does not bind or issue a Wonder wallet/card.","tags":["Identity verification"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/da/app-update/check":{"post":{"operationId":"postApiV1DaAppUpdateCheck","summary":"Check for a newer native build","description":"Asks the Wonder App Manager whether a newer Driver Pro binary exists for the device's channel and returns the APK download when one is on offer. Works before sign-in; any upstream failure answers `updateAvailable: false` rather than an error.","tags":["Driver Assistant"],"parameters":[{"name":"x-wonder-env","in":"header","required":false,"description":"Channel: staging, alpha or production. Also read from body `wonder_env` / `wonderEnv`; defaults to production","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"updateAvailable":true,"forced":false,"currentBuild":527,"latestVersion":"2.0.5","latestBuild":528,"downloadUrl":"https://…/driver-pro.apk","md5":"…","notes":{"zh":"…","en":"…"}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"os":{"type":"string","description":"`android` or `ios`"},"build":{"type":"number","description":"Installed build number"}},"required":["os","build"]}}}},"security":[]}},"/api/v1/da/auth/session":{"post":{"operationId":"postApiV1DaAuthSession","summary":"Sign in with a Wonder access token","description":"Verifies the Wonder access token against that environment's user service, provisions the driver (profile, business id, fleet, payout account) and returns a Supabase session for the app. Allowlisted app-review accounts may send `phone` + `password` instead of a token.","tags":["Driver Assistant · Sign-in"],"parameters":[{"name":"x-wonder-env","in":"header","required":false,"description":"staging, alpha or production; falls back to body `wonder_env`","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"session":{"access_token":"…","refresh_token":"…","expires_at":1790000000,"token_type":"bearer"},"scope":"driver","verification_source":"wonder","session_id":"…","supabase_url":"https://….supabase.co","anon_key":"…","wonder_env":"production","driver":{"id":"…"},"wonder_sync":{"business_id":"…","vehicles":"…","payee":"active"}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"wonder_access_token":{"type":"string","description":"From the QR or app-to-app flow"},"phone":{"type":"string","description":"Allowlisted review accounts only, with `password`"},"password":{"type":"string","description":"Forwarded to Wonder; never stored"},"device_id":{"type":"string"},"device_label":{"type":"string"}}}}}},"security":[]},"delete":{"operationId":"deleteApiV1DaAuthSession","summary":"Sign out this device","description":"Revokes the device's driver session, takes the driver off duty and retires their push tokens.","tags":["Driver Assistant · Sign-in"],"parameters":[{"name":"x-da-session","in":"header","required":false,"description":"The `session_id` returned at sign-in","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"ok":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/auth/wonder-callback":{"get":{"operationId":"getApiV1DaAuthWonderCallback","summary":"Browser bridge back into the app","description":"Returns an HTML page, not JSON. Wonder's authorization screen redirects here with `code`; the page verifies the signed state and redirects to the app's deep link with the code appended. A missing or invalid state renders a \"sign in again\" page and never redirects.","tags":["Driver Assistant · Sign-in"],"parameters":[{"name":"code","in":"query","required":true,"description":"One-time code appended by Wonder","schema":{"type":"string"}},{"name":"s","in":"query","required":true,"description":"Signed state from `/wonder-oauth/code`","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/v1/da/auth/wonder-oauth/code":{"post":{"operationId":"postApiV1DaAuthWonderOauthCode","summary":"Start app-to-app Wonder sign-in","description":"Mints a one-time Wonder authorization code and returns it with the app scheme and signed callback state. Returns 503 `WONDER_OAUTH_UNAVAILABLE` if Wonder refuses access to the code endpoint.","tags":["Driver Assistant · Sign-in"],"parameters":[{"name":"x-wonder-env","in":"header","required":true,"description":"staging, alpha or production","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"code":"…","scheme":"…://","state":"…"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"returnUrl":{"type":"string","description":"App deep link to return to; replaced by the default when not on the allow-list"}}}}}},"security":[]}},"/api/v1/da/auth/wonder-oauth/token":{"get":{"operationId":"getApiV1DaAuthWonderOauthToken","summary":"Exchange an app-to-app code for a Wonder token","description":"Polls for a Wonder access token in the environment that issued the authorization code. `status` is `authorized`, `pending` (keep polling) or `rejected` (stop; `errorCode` is Wonder's, e.g. `EU200000` for an account not allowed to use Driver Assistant).","tags":["Driver Assistant · Sign-in"],"parameters":[{"name":"x-wonder-env","in":"header","required":true,"description":"staging, alpha or production","schema":{"type":"string"}},{"name":"code","in":"query","required":true,"schema":{"type":"string"}},{"name":"native","in":"query","required":false,"description":"`1` for the legacy direct access-token exchange","schema":{"type":"string"}},{"name":"callback","in":"query","required":false,"description":"Callback URL used to build the authorization link (legacy exchange)","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"access_token":"…","refresh_token":"…","profile":{"id":"…","displayName":"Chan Tai Man","email":"…","phone":"…"},"authorized":true,"status":"authorized","reason":null}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/v1/da/auth/wonder-qr/start":{"post":{"operationId":"postApiV1DaAuthWonderQrStart","summary":"Create a Sign in with Wonder QR","description":"Mints a Wonder login QR and returns its uuid and scannable URL. Poll `/wonder-qr/status` with the uuid until a token arrives.","tags":["Driver Assistant · Sign-in"],"parameters":[{"name":"x-wonder-env","in":"header","required":true,"description":"staging, alpha or production","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"uuid":"…","qr_url":"https://…"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/v1/da/auth/wonder-qr/status":{"get":{"operationId":"getApiV1DaAuthWonderQrStatus","summary":"Poll a Wonder sign-in QR","description":"Returns Wonder's scan flags for the QR and, once the driver confirms in the Wonder app, the access token to post to `POST /api/v1/da/auth/session`. `is_cancel` means mint a new QR.","tags":["Driver Assistant · Sign-in"],"parameters":[{"name":"x-wonder-env","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"query","required":true,"description":"QR uuid from `/wonder-qr/start`","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"is_scan":true,"is_expired":false,"is_cancel":false,"access_token":"…","profile":{"id":"…","displayName":"Chan Tai Man","email":"…","phone":"…"},"scanned":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/v1/da/chat/config":{"get":{"operationId":"getApiV1DaChatConfig","summary":"Driver's Sendbird chat identity","description":"Returns the Sendbird application id for the session's environment, the driver's Sendbird user id and nickname. No upstream call; 409 `WONDER_NOT_LINKED` when the session has no Wonder identity.","tags":["Driver Assistant · Chat"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"appId":"…","userId":"…","nickname":"Chan Tai Man"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/chat/quick-replies":{"get":{"operationId":"getApiV1DaChatQuickReplies","summary":"Rider-chat quick-reply templates","description":"Wonder's quick-reply templates, normalised to bilingual `en` / `zh` pairs and sorted by position.","tags":["Driver Assistant · Chat"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"source":"wonder","templates":[{"position":1,"en":"I have arrived","zh":"我已到達"}]}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/fleet-orders":{"get":{"operationId":"getApiV1DaFleetOrders","summary":"List Fleet Mode Orders (查詢未登陸訂單)","description":"One page of the orders Wonder flagged for manual settlement. Returns a bare array; a page shorter than `limit` is the last one.","tags":["Driver Assistant · Fleet orders"],"parameters":[{"name":"limit","in":"query","required":false,"description":"1–50, default 10","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Default 0","schema":{"type":"number"}},{"name":"state","in":"query","required":false,"description":"`ordered`, `pending` or `approved`","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]},"post":{"operationId":"postApiV1DaFleetOrders","summary":"Claim a Fleet Mode Order","description":"Submits a withdrawal request to Wonder for one order. The reference number is matched on the device; the call is not retried.","tags":["Driver Assistant · Fleet orders"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"ok":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"taxiOrderUuid":{"type":"string"},"refNumber":{"type":"string"}},"required":["taxiOrderUuid","refNumber"]}}}},"security":[{"driverBearer":[]}]}},"/api/v1/da/fleet-orders/{requestId}":{"get":{"operationId":"getApiV1DaFleetOrdersByRequestId","summary":"Claimed Fleet Mode Order transfer detail","description":"Transfer detail (轉帳詳情) for a claimed order, keyed on the withdrawal request id rather than the taxi order uuid.","tags":["Driver Assistant · Fleet orders"],"parameters":[{"name":"requestId","in":"path","required":true,"description":"Withdrawal request id","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/jobs":{"get":{"operationId":"getApiV1DaJobs","summary":"Combined job feed","description":"One feed of open consumer rides, wishes and partner (supplier) bookings in `data`, plus the jobs the driver already holds in `mine`. Each item carries `source` (`consumer` or `supplier`); when the driver cannot take work, `data` is empty and `blocked_reason` says why.","tags":["Driver Assistant"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":[{"source":"consumer","id":"…","order":{}}],"mine":[{"source":"supplier","id":"…","order":{}}],"can_accept":true,"hidden_by_vehicle_class":0}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/m1os/connect":{"post":{"operationId":"postApiV1DaM1osConnect","summary":"Pair a scanned M1OS meter","description":"Resolves the scanned meter QR, binds the device to the driver's business and, unless `goOnline` is false, starts a device login request. `state` is `complete` (connection applied) or `pending` (poll `/m1os/login-request` with `requestId` + `deviceSn`).","tags":["Driver Assistant · Meter"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"state":"pending","requestId":"…","deviceSn":"…","connection":null}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"rawScan":{"type":"string","description":"Raw QR contents (a Wonder short link)"},"deviceSn":{"type":"string","description":"Device serial, when already known (legacy: `deviceCode`)"},"code":{"type":"string","description":"Pair code"},"goOnline":{"type":"boolean","description":"`false` pairs without starting the login request; default true"}}}}}},"security":[{"driverBearer":[]}]}},"/api/v1/da/m1os/disconnect":{"post":{"operationId":"postApiV1DaM1osDisconnect","summary":"Unpair the driver's meter","description":"Clears the local meter pairing and attempts the OMS unbind; upstream failures are ignored. The vehicle stays in the driver's list.","tags":["Driver Assistant · Meter"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/m1os/login-request":{"get":{"operationId":"getApiV1DaM1osLoginRequest","summary":"Poll a meter login request","description":"Polls a Wonder device login request. On `complete` the meter is paired and, when `goOnline` is set, the driver is put on duty through the same gate as `/me/online`; `online` reports whether that happened.","tags":["Driver Assistant · Meter"],"parameters":[{"name":"id","in":"query","required":true,"description":"Login request id","schema":{"type":"string"}},{"name":"deviceSn","in":"query","required":true,"schema":{"type":"string"}},{"name":"goOnline","in":"query","required":false,"description":"Go on duty on completion","schema":{"type":"boolean"}},{"name":"pair","in":"query","required":false,"description":"With `goOnline`, also persist the pairing","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"state":"complete","id":"…","deviceSn":"…","connection":{},"online":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]},"delete":{"operationId":"deleteApiV1DaM1osLoginRequest","summary":"Cancel a meter login request","description":"Cancels the login request upstream; always answers `cancelled: true`, even if Wonder refuses.","tags":["Driver Assistant · Meter"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"cancelled":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/m1os/status":{"get":{"operationId":"getApiV1DaM1osStatus","summary":"Meter connection status","description":"Whether the driver's paired meter is still bound and to which vehicle, read live from Wonder's meter feed. Drivers with no pairing are answered without an upstream call.","tags":["Driver Assistant · Meter"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/ocr/recognition":{"post":{"operationId":"postApiV1DaOcrRecognition","summary":"Upload a vehicle-licence photo for OCR","description":"Forwards a photo of the taxi's vehicle registration licence to Wonder's OCR and returns the recognition task. JPEG, PNG or HEIC; over 6 MB decoded answers 413 `IMAGE_TOO_LARGE`.","tags":["Driver Assistant · Onboarding"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"task":{"task_id":"…","status":"record"}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"Base64 data URL (JSON), or an `image` part in multipart/form-data"}},"required":["image"]}}}},"security":[{"driverBearer":[]}]}},"/api/v1/da/ocr/status":{"get":{"operationId":"getApiV1DaOcrStatus","summary":"Poll a licence recognition","description":"Status of one OCR task: `crawing` (keep polling), `success` or `failed` (Wonder's spellings). Reaching `success` creates the virtual meter upstream and consumes the task.","tags":["Driver Assistant · Onboarding"],"parameters":[{"name":"taskId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"task":{"task_id":"…","status":"crawing"}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/ocr/task":{"get":{"operationId":"getApiV1DaOcrTask","summary":"Driver's in-flight OCR task","description":"The driver's current licence recognition task, used to resume the capture flow.","tags":["Driver Assistant · Onboarding"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"task":{"task_id":"…","status":"crawing"}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]},"delete":{"operationId":"deleteApiV1DaOcrTask","summary":"Discard the in-flight OCR task","description":"Clears the driver's OCR task at Wonder so a new photo can be taken. Wonder holds one task per driver.","tags":["Driver Assistant · Onboarding"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"ok":true}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/onboarding/status":{"get":{"operationId":"getApiV1DaOnboardingStatus","summary":"Onboarding status","description":"Whether the driver has completed onboarding (`verified`, `pending`, or `unknown` when the probe failed), whether a Wonder identity is linked, and any in-flight licence OCR task.","tags":["Driver Assistant · Onboarding"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"status":"pending","linked":true,"ocrTask":{"taskId":"…","status":"crawing"}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/overlay-feed":{"get":{"operationId":"getApiV1DaOverlayFeed","summary":"Android floating-card feed","description":"Bare array of open jobs, polled every four seconds by the Android overlay service while the app is backgrounded. Every refusal (blocked driver, superseded session, no environment) answers `[]` rather than an error.","tags":["Driver Assistant"],"parameters":[{"name":"x-wonder-env","in":"header","required":false,"description":"The build's environment; the driver's duty environment is used when absent","schema":{"type":"string"}},{"name":"x-da-session","in":"header","required":false,"description":"A superseded session gets an empty feed","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/virtual-meter/task":{"post":{"operationId":"postApiV1DaVirtualMeterTask","summary":"Confirm a licence and create the virtual meter","description":"Confirms a recognised OCR task so Wonder creates the driver's virtual meter, then adds the vehicle to the driver's fleet. A task Wonder has already completed still answers 200 with `outcome` saying so; `landing` reports whether the vehicle was written.","tags":["Driver Assistant · Onboarding"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"ok":true,"status":"verified","outcome":"created","vehicle":{"id":"…","plate":"…"},"landing":{"landed":true}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"taskId":{"type":"string"},"task":{"type":"object","description":"The recognised task as returned by `/ocr/recognition`, used to land the vehicle"}},"required":["taskId"]}}}},"security":[{"driverBearer":[]}]}},"/api/v1/da/wishes/{id}/stops/{stopId}/reached":{"post":{"operationId":"postApiV1DaWishesByIdStopsByStopIdReached","summary":"Mark a stop reached","description":"Marks a planned stop on a held job as reached, which locks it against passenger edits. Only while the job is `arrived` or `in_trip`; idempotent and cannot be undone.","tags":["Driver Assistant"],"parameters":[{"name":"id","in":"path","required":true,"description":"Ride id","schema":{"type":"string"}},{"name":"stopId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"stops":[{"stop_id":"…","status":"reached"}],"plan_version":2},"already":false}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/wonder-link":{"get":{"operationId":"getApiV1DaWonderLink","summary":"Wonder payout-account link status","description":"Whether the driver has authorised a Wonder account to be paid into, plus a payout diagnosis. Attempts payout-account provisioning before reporting.","tags":["Driver Assistant · Payout link"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]},"post":{"operationId":"postApiV1DaWonderLink","summary":"Start a Wonder payout-account link","description":"Creates a BizConnect login QR for the driver to scan in their Wonder app. Render `content` as the QR and poll `/wonder-link/poll` with `server_code`; the QR expires after about 120 seconds.","tags":["Driver Assistant · Payout link"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"content":"…","server_code":"…","status":"PENDING","device_id":"…","expires_at":"2026-09-25T08:00:00Z","poll_interval_ms":2000,"poll_url":"/api/v1/da/wonder-link/poll","app":{}}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"device_id":{"type":"string","description":"Stable per-device id; defaults to the driver id"}}}}}},"security":[{"driverBearer":[]}]},"delete":{"operationId":"deleteApiV1DaWonderLink","summary":"Unlink the Wonder payout account","description":"Stops JEK using the driver's Wonder authorisation. Local only: the driver revokes it in the Wonder app to remove it there too.","tags":["Driver Assistant · Payout link"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/wonder-link/poll":{"post":{"operationId":"postApiV1DaWonderLinkPoll","summary":"Poll a Wonder payout-account link","description":"Polls the link QR. `PENDING` means keep polling; `REJECTED` / `EXPIRED` set `restart: true`; on `SUCCESS` the grant is stored against the calling driver before the answer is returned.","tags":["Driver Assistant · Payout link"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"},"example":{"data":{"status":"PENDING","expires_at":"…","poll_interval_ms":2000,"restart":false}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"server_code":{"type":"string","description":"From `POST /api/v1/da/wonder-link`"},"device_id":{"type":"string"}},"required":["server_code"]}}}},"security":[{"driverBearer":[]}]}},"/api/v1/da/etoll/accounts":{"get":{"operationId":"getApiV1DaEtollAccounts","summary":"List bound HKeToll accounts","description":"Proxies the Wonder gateway e-toll account list using the driver's sealed Wonder session. Returns a bare array of { id, username, status, accountType }.","tags":["Driver Assistant · e-Toll"],"parameters":[{"name":"x-da-session","in":"header","required":true,"description":"Driver app session carrying the sealed Wonder session","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]},"post":{"operationId":"postApiV1DaEtollAccounts","summary":"Bind an HKeToll account","description":"Forwards the credentials to the Wonder gateway e-toll bind once, with no retries; the password is never stored, logged or echoed. Returns the account (status is usually \"Verifying\"), or 400 ETOLL_UPSTREAM_REJECTED when the e-toll service refuses the credentials.","tags":["Driver Assistant · e-Toll"],"parameters":[{"name":"x-da-session","in":"header","required":true,"description":"Driver app session carrying the sealed Wonder session","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","description":"HKeToll username"},"password":{"type":"string","description":"HKeToll password; forwarded only"},"accountType":{"type":"string","description":"Optional HKeToll account type"}},"required":["username","password"]}}}},"security":[{"driverBearer":[]}]}},"/api/v1/da/etoll/accounts/unbind":{"post":{"operationId":"postApiV1DaEtollAccountsUnbind","summary":"Unbind an HKeToll account","description":"Proxies the Wonder gateway e-toll unbind, which is keyed on both the record id and the username; sent once with no retries. Returns { ok: true }, or 400 ETOLL_UPSTREAM_REJECTED when the e-toll service refuses.","tags":["Driver Assistant · e-Toll"],"parameters":[{"name":"x-da-session","in":"header","required":true,"description":"Driver app session carrying the sealed Wonder session","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Bound account record id"},"username":{"type":"string","description":"HKeToll username of that account"}},"required":["id","username"]}}}},"security":[{"driverBearer":[]}]}},"/api/v1/da/etoll/accounts/{id}":{"get":{"operationId":"getApiV1DaEtollAccountsById","summary":"Get one bound HKeToll account","description":"Proxies the Wonder gateway e-toll account read and returns { id, username, status, accountType }.","tags":["Driver Assistant · e-Toll"],"parameters":[{"name":"id","in":"path","required":true,"description":"Bound account record id","schema":{"type":"string"}},{"name":"x-da-session","in":"header","required":true,"description":"Driver app session carrying the sealed Wonder session","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]},"patch":{"operationId":"patchApiV1DaEtollAccountsById","summary":"Update HKeToll account credentials","description":"Forwards the username and password pair to the Wonder gateway e-toll account edit once, with no retries; the upstream takes the full pair, not a partial patch. Returns the account, or 400 ETOLL_UPSTREAM_REJECTED when the e-toll service refuses.","tags":["Driver Assistant · e-Toll"],"parameters":[{"name":"id","in":"path","required":true,"description":"Bound account record id","schema":{"type":"string"}},{"name":"x-da-session","in":"header","required":true,"description":"Driver app session carrying the sealed Wonder session","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","description":"HKeToll username (sent unchanged)"},"password":{"type":"string","description":"New HKeToll password; forwarded only"}},"required":["username","password"]}}}},"security":[{"driverBearer":[]}]}},"/api/v1/da/etoll/person-account":{"get":{"operationId":"getApiV1DaEtollPersonAccount","summary":"HKeToll personal-account record","description":"Proxies the Wonder gateway e-toll person-account read. The object is Wonder's own shape, passed through unmapped with only the envelope removed; an empty answer becomes {}.","tags":["Driver Assistant · e-Toll"],"parameters":[{"name":"x-da-session","in":"header","required":true,"description":"Driver app session carrying the sealed Wonder session","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/etoll/transactions":{"get":{"operationId":"getApiV1DaEtollTransactions","summary":"List HKeToll tunnel charges","description":"Proxies the Wonder gateway e-toll transactions list and returns a bare array of normalised charges (id, trxnStatus, trxnDate, tunnel, tollAmount, plateNumber, ...). A page shorter than limit marks the end of the list.","tags":["Driver Assistant · e-Toll"],"parameters":[{"name":"x-da-session","in":"header","required":true,"description":"Driver app session carrying the sealed Wonder session","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, clamped to 1–100, default 20","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Default 0","schema":{"type":"number"}},{"name":"trxnStatus","in":"query","required":false,"description":"Transaction status filter; empty or \"all\" means no filter","schema":{"type":"string"}},{"name":"tunnel","in":"query","required":false,"description":"Tunnel key from /api/v1/da/etoll/tunnels; empty or \"all\" means no filter","schema":{"type":"string"}},{"name":"search","in":"query","required":false,"description":"Free-text search","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/etoll/transactions/{id}":{"get":{"operationId":"getApiV1DaEtollTransactionsById","summary":"Get one HKeToll tunnel charge","description":"Proxies the Wonder gateway e-toll transaction read and returns the charge in the same normalised shape as the list.","tags":["Driver Assistant · e-Toll"],"parameters":[{"name":"id","in":"path","required":true,"description":"Transaction id","schema":{"type":"string"}},{"name":"x-da-session","in":"header","required":true,"description":"Driver app session carrying the sealed Wonder session","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/etoll/tunnels":{"get":{"operationId":"getApiV1DaEtollTunnels","summary":"List tunnels for toll filtering","description":"Proxies the Wonder gateway e-toll tunnel list and returns [{ tunnel, tunnelTranslation }]. The tunnel key is the value the transactions list filters on.","tags":["Driver Assistant · e-Toll"],"parameters":[{"name":"x-da-session","in":"header","required":true,"description":"Driver app session carrying the sealed Wonder session","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/da/etoll/virtual-meters":{"get":{"operationId":"getApiV1DaEtollVirtualMeters","summary":"List HKeToll virtual meters","description":"Proxies the Wonder gateway e-toll virtual-meter list: vehicles HKeToll knows for the driver, from a bound account or an OCR-read vehicle licence (separate from the driver's JEK vehicles). Returns [{ id, vehicleRegistrationMark, vehicleClass, type }].","tags":["Driver Assistant · e-Toll"],"parameters":[{"name":"x-da-session","in":"header","required":true,"description":"Driver app session carrying the sealed Wonder session","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"driverBearer":[]}]}},"/api/v1/me/payment/cards":{"get":{"operationId":"getApiV1MePaymentCards","summary":"List the caller's saved cards, shared with the legacy JEK app","description":"Reads the caller's card vault at the payment gateway for the declared environment and answers `{ customerId, cards, shared_with_legacy }`; card tokens are stripped from every record. A JEK passenger linked (by verified phone) to their legacy JEK account has two payment customers, the legacy app's and this server's own: both are read, each card carries `customer_source` (`legacy` | `jek`), only one default is shown, and `customerId` is the legacy one. `partial: true` when one customer could not be read. The list is also kept in Supabase (`jek_payment_cards`) without card numbers or tokens (docs/75). Where this deployment collects no card payments the answer is an empty list with `collects: false` and `code: PAYMENT_COLLECTION_CLOSED`. 400 `ENV_NOT_DECLARED` without `x-jek-env`.","tags":["Passenger"],"parameters":[{"name":"x-jek-env","in":"header","required":true,"description":"staging | alpha | production — the environment this app build belongs to","schema":{"type":"string"}},{"name":"x-jek-channel","in":"header","required":false,"description":"Which consumer app is calling; selects the collecting merchant (defaults to jek)","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]},"post":{"operationId":"postApiV1MePaymentCards","summary":"Save a card, or sign an Alipay / WeChat Pay auto-debit agreement","description":"The card number is sealed into the vault envelope and never stored or logged by this server. A passenger linked to their legacy JEK account saves to the legacy app's payment customer, so the card shows in both apps (`card.customer_source`, `shared_with_legacy`). Returns 201 with `state`; when the bank requires 3-D Secure, `verification_required` is true and the app must open `verify_url`, then call POST /api/v1/me/payment/cards/verify with `verify_uuid`. `usable` is false while the card is still pending. With `method: \"alipay\" | \"wechat\"` it signs an auto-debit agreement instead, answering in the same shape plus `instrument`, `handoff` and (WeChat) `wechat_session_id`. A refused card or agreement is 402 with the gateway's own message.","tags":["Passenger"],"parameters":[{"name":"x-jek-env","in":"header","required":true,"description":"staging | alpha | production","schema":{"type":"string"}},{"name":"x-jek-channel","in":"header","required":false,"description":"Which consumer app is calling (defaults to jek)","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"string","description":"Card number, 12–19 digits (card save only), e.g. 4242 4242 4242 4242"},"exp_month":{"type":"string","description":"1–12 (card save only)"},"exp_year":{"type":"string","description":"YY or YYYY (card save only)"},"cvv":{"type":"string","description":"3–4 digits (card save only)"},"holder_name":{"type":"string","description":"Cardholder name (card save only)"},"phone":{"type":"string","description":"Optional cardholder phone"},"method":{"type":"string","description":"alipay | alipayhk | wechat | wechatpay — sign an auto-debit agreement instead of saving a card"},"return_url":{"type":"string","description":"App deep link to return to after consent; required for Alipay agreements"},"terminal_type":{"type":"string","description":"Agreement only: passed to the gateway"},"code":{"type":"string","description":"Agreement only: WeChat auth code, when the app has one"},"openid":{"type":"string","description":"Agreement only: WeChat openid, when the app has one"},"diagnose":{"type":"boolean","description":"true adds the upstream exchange (`wonder` steps, no card data) to the answer for QA"}}}}}},"security":[{"userBearer":[]}]},"patch":{"operationId":"patchApiV1MePaymentCards","summary":"Make a saved card the default","description":"Sets the default card on the payment customer that holds it and confirms it by re-reading the vault. For a passenger shared with the legacy JEK app, a card on the legacy customer becomes the default in both apps. The default is what a fare is charged to when a payment names no card. Answers the updated `{ customerId, cards }`; 409 `CARD_NOT_FOUND` when the card is no longer on the account.","tags":["Passenger"],"parameters":[{"name":"x-jek-env","in":"header","required":true,"description":"staging | alpha | production","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"card_id":{"type":"string","description":"Card id as listed by GET /api/v1/me/payment/cards"}},"required":["card_id"]}}}},"security":[{"userBearer":[]}]},"delete":{"operationId":"deleteApiV1MePaymentCards","summary":"Remove a saved card","description":"Removes one card from the payment customer that holds it (the id travels in the body, not the path, because card ids are not URL-safe) and confirms by re-reading the vault. A card shared with the legacy JEK app is removed from both apps. Answers the remaining `{ customerId, cards, removed: true }`; 409 `CARD_NOT_FOUND` when the card is already gone.","tags":["Passenger"],"parameters":[{"name":"x-jek-env","in":"header","required":true,"description":"staging | alpha | production","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"card_id":{"type":"string","description":"Card id as listed by GET /api/v1/me/payment/cards"}},"required":["card_id"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/payment/cards/verify":{"post":{"operationId":"postApiV1MePaymentCardsVerify","summary":"Check whether a 3-D Secure or agreement save completed","description":"Called after the passenger returns from the 3-D Secure challenge or the Alipay / WeChat consent page. Re-reads the vault and answers `{ verified, state, card, cards }`. When `return_query` is sent, the auto-debit authorization is applied first and its outcome is reported as `auth_apply`.","tags":["Passenger"],"parameters":[{"name":"x-jek-env","in":"header","required":true,"description":"staging | alpha | production","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"verify_uuid":{"type":"string","description":"From the save response; this or card_id is required"},"card_id":{"type":"string","description":"Alternative handle to verify_uuid"},"return_query":{"type":"string","description":"Query string the agreement return URL was opened with"},"diagnose":{"type":"boolean","description":"true adds the upstream exchange to the answer for QA"}}}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/payment/methods":{"get":{"operationId":"getApiV1MePaymentMethods","summary":"What the merchant accepts, for the payment picker","description":"Describes the collecting merchant, not the caller: `methods`, `merchant`, the raw `rules` (Apple Pay and Google Pay appear there as card entry types, not as methods), `wallets` this build can finish, and `google_pay` tokenization parameters. Nothing is charged. When collection is closed the lists are empty with `collects: false`.","tags":["Passenger"],"parameters":[{"name":"x-jek-env","in":"header","required":true,"description":"staging | alpha | production","schema":{"type":"string"}},{"name":"handoffs","in":"query","required":false,"description":"Comma-separated handoffs this build can complete: redirect, qr-code, wechat-sdk, alipay-sdk, unionpay-sdk, native-sdk","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/payment/outstanding":{"get":{"operationId":"getApiV1MePaymentOutstanding","summary":"Fares the caller still owes","description":"Finds rides whose settlement failed or is unpaid and confirms each against its live payment order before reporting it, so a fare that has since been taken is never shown as owed. Answers `{ fares: [{ ride_id, amount, currency, vehicle, completed_at }], more, total }`, at most 5 fares; pay one with POST /api/v1/me/rides/{id}/pay.","tags":["Passenger"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/rides/{id}/pay":{"post":{"operationId":"postApiV1MeRidesByIdPay","summary":"Hold or take a ride's fare with a saved card","description":"`mode: \"authorize\"` (default) pre-authorizes the fare at booking; `mode: \"settle\"` takes what is still outstanding when the trip is over, capturing an existing hold where there is one. Creates the ride's payment order if the booking deferred it. The answer is read back from the order: `held` and `paid` are separate, and a hold is not a payment. 402 `AUTHORIZATION_DECLINED` / `PAYMENT_DECLINED` with the gateway's message; 409 `PAYMENT_ENV_MISMATCH` when the ride's money is at a different environment than the one declared.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-jek-env","in":"header","required":true,"description":"staging | alpha | production","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","description":"authorize (default) | settle"},"saved_card_id":{"type":"string","description":"Card to charge; the vault default when omitted"}}}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/rides/{id}/pay/native-wallet":{"post":{"operationId":"postApiV1MeRidesByIdPayNativeWallet","summary":"Hold a ride's fare with an Apple Pay or Google Pay token","description":"Redeems the one-time token from the OS payment sheet against the ride's payment order as a hold, then releases the `awaiting_payment` ride to drivers. The ride is dispatched only when the order confirms the hold; otherwise 402 `AUTHORIZATION_NOT_HELD`. Retrying after a hold landed answers success with `already` rather than holding twice. The token is never stored or logged.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-jek-env","in":"header","required":true,"description":"staging | alpha | production","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","description":"applepay | googlepay"},"token":{"type":"string","description":"Payment token from the OS sheet"},"merchant_identifier":{"type":"string","description":"Apple Pay merchant identifier the token was minted for"}},"required":["method","token"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/rides/{id}/pay/wallet":{"post":{"operationId":"postApiV1MeRidesByIdPayWallet","summary":"Start paying a ride's fare with a wallet app","description":"Settles (never holds) the outstanding fare on WeChat Pay, Alipay, AlipayHK, PayMe, Octopus, FPS or the UnionPay wallet. The payment finishes in the wallet app, so the answer is always `paid: false, pending: true` with a `handoff` telling the client which of `redirect`, `qr`, `sdk_payload` or `wechat_pay` to use; poll GET on this route for the result. `amount` is what was actually charged (Octopus rounds up to the next 10 cents, shown in `rounding`).","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-jek-env","in":"header","required":true,"description":"staging | alpha | production","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","description":"wechatpay | alipay | alipayhk | payme | octopus | fps | unionpaywallet"},"handoffs":{"type":"string","description":"Handoffs this build can complete: redirect, qr-code, wechat-sdk, alipay-sdk, unionpay-sdk, native-sdk"},"return_url":{"type":"string","description":"App deep link the wallet returns to"},"return_urls":{"type":"object","description":"PayMe `{ return_url, success_url, fail_url }`; derived from return_url when omitted"},"wechat_app_id":{"type":"string","description":"Sent by builds with the WeChat SDK; enables the native in-app WeChat entry"},"app_env":{"type":"string","description":"Passed to the gateway with the wallet request"}},"required":["method"]}}}},"security":[{"userBearer":[]}]},"get":{"operationId":"getApiV1MeRidesByIdPayWallet","summary":"Poll a wallet payment","description":"Reads the ride's payment order and answers `{ order, paid, pending }`. When the order reads paid, the charge is recorded and the ride marked paid on this call. 409 `NO_PAYMENT_ORDER` when no payment has been started.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-jek-env","in":"header","required":true,"description":"staging | alpha | production","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[{"userBearer":[]}]}},"/api/v1/me/rides/{id}/end-preview":{"post":{"operationId":"postApiV1MeRidesByIdEndPreview","summary":"Preview what ending the trip now would settle at","description":"Computes, without ending the trip, the served distance and duration, the final total and any refund or additional charge, and returns them with a signed `preview_ref` and `expires_at` for POST /api/v1/me/rides/{id}/end to spend. The end point is the driver's last reliable position; the passenger's `location` is only a cross-check (`location_agrees`). Answers `allowed: false` with a reason when the trip cannot be ended; `settlement.simulated` is true where no refund rail is live.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"location":{"type":"object","description":"`{ lat, lng }` of the passenger, for the cross-check"},"reason_code":{"type":"string","description":"Why the trip is ending early (max 60 chars); defaults to passenger_requested"}}}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/rides/{id}/schedule":{"patch":{"operationId":"patchApiV1MeRidesByIdSchedule","summary":"Move a scheduled ride to another time","description":"Changes the pickup time of the caller's own unclaimed scheduled ride; moves no money and keeps the booked fare (`quote.repriced` is always false, `quote.card_fare` shows today's card price for reference). A ride already released to drivers is taken back out of the pool until its new time (`withdrawn_from_pool`). The new time follows the booking's rules: at least 15 minutes ahead and within 30 days. 409 when a driver accepted in the meantime.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Rescheduled","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"The updated ride row."},"schedule":{"type":"object","properties":{"previous_scheduled_at":{"type":"string","format":"date-time","nullable":true},"scheduled_at":{"type":"string","format":"date-time"},"release_at":{"type":"string","format":"date-time","description":"When the ride rejoins the driver pool."},"status":{"type":"string","example":"scheduled"},"withdrawn_from_pool":{"type":"boolean","description":"True when this call took a live offer back out of the pool."}}},"quote":{"type":"object","properties":{"fare":{"type":"number","description":"What the ride costs, and will still cost."},"currency":{"type":"string"},"repriced":{"type":"boolean","example":false},"card_fare":{"type":"number","nullable":true,"description":"Today's card price for the recorded route. Informational — NOT what is charged."},"class_name":{"type":"string","nullable":true}}}}}}}},"400":{"description":"scheduled_at_required, invalid_scheduled_at, scheduled_at_in_seconds, scheduled_too_soon or scheduled_too_far"},"404":{"description":"Not the caller's ride, or no such ride"},"409":{"description":"ride_finished, not_a_ride, ride_claimed, trip_started, not_reschedulable, not_scheduled, or ride_changed (a driver accepted mid-request)"},"503":{"description":"trip_plan_unavailable — the deployment has not run migration 20260823140000"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["scheduled_at"],"properties":{"scheduled_at":{"oneOf":[{"type":"integer","format":"int64"},{"type":"string","format":"date-time"}],"description":"Epoch milliseconds, or ISO-8601."}}}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/rides/{id}/stops-preview":{"post":{"operationId":"postApiV1MeRidesByIdStopsPreview","summary":"Preview a new remaining itinerary and its price","description":"Prices distance already served plus the proposed remaining route from where the car is, without changing the ride. `stops` is the complete list of places still to visit (reached stops are kept automatically and cannot be edited). Returns the route, ETA, stops, `money` (new total, refund or additional charge) and a signed `preview_ref` for POST /api/v1/me/rides/{id}/stops. 409 `PLAN_CHANGED` when `plan_version` is stale.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"stops":{"type":"string","description":"`{ stop_id?, label, address?, lat, lng, place_id? }`; include stop_id to keep an existing stop"},"dropoff":{"type":"object","description":"New final drop-off `{ lat, lng, label? }`"},"plan_version":{"type":"number","description":"The plan version the client is editing"}},"required":["stops"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/me/rides/{id}/stops":{"post":{"operationId":"postApiV1MeRidesByIdStops","summary":"Commit a previewed itinerary change","description":"Applies exactly what a `preview_ref` from stops-preview carries, without recomputing it. The write is conditional on the plan version, so a concurrent change answers 409 `PLAN_CHANGED` with the current plan instead of being overwritten; an expired preview is refused. Records the revision and the fare difference, and notifies the assigned driver. 400 `PREVIEW_REQUIRED` without a valid preview.","tags":["Passenger"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Alternative to the body idempotency_key","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"preview_ref":{"type":"string","description":"From POST /api/v1/me/rides/{id}/stops-preview"},"idempotency_key":{"type":"string","description":"Replays answer `already: true` (also accepted as `client_ref`)"}},"required":["preview_ref"]}}}},"security":[{"userBearer":[]}]}},"/api/v1/wonder/quotes":{"post":{"operationId":"postApiV1WonderQuotes","summary":"Quote every vehicle class for a trip (legacy OMS dialect)","description":"Accepts the legacy `CreateQuoteDto` body (`initial_location`, `destination_location`, up to four `additional_stops`), routes the trip server-side and prices each enabled class from JEK's rate card. Answers `{ code, message, data: { quotes, batch_id, routes, map_platform } }`; the batch is stored for 10 minutes so the booking can name only `batch_id` and `selected_quote_ids`. Authenticated by the `X-Internal-Token` header (an environment console credential, a partner's issued token, or the shared dispatch token); `x-jek-env` is required and must match the credential's environment.","tags":["Wonder-compatible Ride API"],"parameters":[{"name":"x-jek-env","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Internal-Token","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Partner-ID","in":"header","required":false,"description":"The partner's OMS `taxi_partners` id for the declared environment.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"initial_location":{"type":"string"},"destination_location":{"type":"string"},"additional_stops":{"type":"string","description":"At most 4."},"vehicle_type_codes":{"type":"string","description":"Optional class filter; absent quotes the whole card."}},"required":["initial_location","destination_location"]}}}},"security":[]}},"/api/v1/wonder/taxi_orders":{"post":{"operationId":"postApiV1WonderTaxiOrders","summary":"Book a quoted ride (legacy OMS dialect)","description":"Accepts the legacy `CreateTaxiOrderDto` body, rebuilds the trip from the stored quote batch and creates a supplier order in the environment named by `x-jek-env`. Only configured demand partners may book; the stored fare is JEK's own priced total, with the partner's `fare`/`tips` kept in metadata. `external_customer.reference_number` is the idempotency key, so a retried booking returns the original order with 200. Answers `{ code, message, data: { taxi_order } }`.","tags":["Wonder-compatible Ride API"],"parameters":[{"name":"x-jek-env","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Internal-Token","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Partner-ID","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"batch_id":{"type":"string","description":"From POST /api/v1/wonder/quotes."},"selected_quote_ids":{"type":"string"},"channel":{"type":"string"},"fare":{"type":"string","description":"Recorded, not trusted."},"tips":{"type":"string"},"external_customer":{"type":"string","description":"`reference_number` is required when the object is sent."}},"required":["batch_id","selected_quote_ids"]}}}},"security":[]}},"/api/v1/wonder/taxi_orders/{id}":{"get":{"operationId":"getApiV1WonderTaxiOrdersById","summary":"Read a booking (legacy OMS dialect)","description":"Returns `{ code, message, data: { taxi_order_detail } }` with the order, driver and vehicle. `id` is either the JEK order id or the partner's own reference number; an order belonging to another partner or environment answers \"Order not found\".","tags":["Wonder-compatible Ride API"],"parameters":[{"name":"id","in":"path","required":true,"description":"JEK order id or the partner's reference number.","schema":{"type":"string"}},{"name":"x-jek-env","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Internal-Token","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Partner-ID","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/v1/wonder/taxi_orders/{id}/cancel":{"put":{"operationId":"putApiV1WonderTaxiOrdersByIdCancel","summary":"Cancel a booking (legacy OMS dialect)","description":"PUT matches the legacy OMS route; POST on the same path runs the same handler. Answers `{ code, message, data: { taxi_order } }` with the order in its cancelled state. An already-cancelled order is a success; a completed trip is refused with an operation-conflict code.","tags":["Wonder-compatible Ride API"],"parameters":[{"name":"id","in":"path","required":true,"description":"JEK order id or the partner's reference number.","schema":{"type":"string"}},{"name":"x-jek-env","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Internal-Token","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Partner-ID","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"cancel_remark":{"type":"string","description":"Optional reason (also read from `cancel_type` or `reason`); max 200 chars."}}}}}},"security":[]},"post":{"operationId":"postApiV1WonderTaxiOrdersByIdCancel","summary":"Cancel a booking (POST alias)","description":"Same handler as the PUT route, for callers not coming through the OMS proxy.","tags":["Wonder-compatible Ride API"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-jek-env","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Internal-Token","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Partner-ID","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/v1/wonder/taxi_orders/{id}/chat_channel":{"put":{"operationId":"putApiV1WonderTaxiOrdersByIdChatChannel","summary":"Attach Wonder's Sendbird chat channel to a booking","description":"Called by Wonder to hand over the Sendbird channel it provisioned for a partner booking, after which the order renders `allow_chat: true` with a `chat_configure`. Idempotent; the channel is stored as sent and not validated with Sendbird. A completed, cancelled or expired order is refused.","tags":["Wonder-compatible Ride API"],"parameters":[{"name":"id","in":"path","required":true,"description":"JEK order id or the partner's reference number.","schema":{"type":"string"}},{"name":"x-jek-env","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Internal-Token","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"chat_configure.channel":{"type":"string","description":"May also be sent flat as `channel`."},"chat_configure.passenger_id":{"type":"string"},"chat_configure.driver_id":{"type":"string"}},"required":["chat_configure.channel"]}}}},"security":[]}},"/api/v1/wonder/taxi_orders/{id}/ride":{"get":{"operationId":"getApiV1WonderTaxiOrdersByIdRide","summary":"Live driver position for a booking (legacy OMS dialect)","description":"Returns the order's state and, while it is accepted, arrived or in trip, the driver's latest position and heading if the fix is under 10 minutes old. The driver's identity is not included.","tags":["Wonder-compatible Ride API"],"parameters":[{"name":"id","in":"path","required":true,"description":"JEK order id or the partner's reference number.","schema":{"type":"string"}},{"name":"x-jek-env","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Internal-Token","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Partner-ID","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}},"/api/v1/wonder/taxi_orders/{id}/status":{"get":{"operationId":"getApiV1WonderTaxiOrdersByIdStatus","summary":"Order status poll (legacy OMS dialect)","description":"What Heycars and Hoppa poll about every 4 seconds. Byte-compatible with OMS `GetTaxiOrderStatusPresenter`: while accepted, arrived or in trip and with a driver fix under 10 minutes old it returns state, location, angle and the remaining-route estimate (distance, duration, polyline, progress — measured along a cached Google leg route exactly as OMS measures it); otherwise every field is null and the estimate zero. An unknown order is HTTP 400 code 100001, as in OMS.","tags":["Wonder-compatible Ride API"],"parameters":[{"name":"id","in":"path","required":true,"description":"JEK order id or the partner's reference number.","schema":{"type":"string"}},{"name":"x-jek-env","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Internal-Token","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Partner-ID","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"500":{"$ref":"#/components/responses/Problem"}},"security":[]}}}}