{ "components": { "schemas": { "buyer.BuyerContext": { "properties": { "organisation_access_id": { "type": "string" }, "retail_customer_number": { "type": "string" }, "type": { "$ref": "#/components/schemas/retail_enums.BuyerType" }, "wholesale_organisation_code": { "type": "string" } }, "type": "object" }, "buyer.PricingContext": { "properties": { "audience": { "$ref": "#/components/schemas/market_enums.PriceAudience" }, "geographic_context": { "$ref": "#/components/schemas/geography.GeographicContext" }, "visibility": { "$ref": "#/components/schemas/product_enums.PriceVisibility" } }, "required": [ "geographic_context" ], "type": "object" }, "classification_enums.StorageType": { "enum": [ "AMBIENT", "CHILLED", "FROZEN" ], "type": "string", "x-enum-varnames": [ "StorageAmbient", "StorageChilled", "StorageFrozen" ] }, "commerce_enums.OrderType": { "enum": [ "online", "pos", "b2b", "relay", "manual", "import" ], "type": "string", "x-enum-varnames": [ "OrderTypeOnline", "OrderTypePOS", "OrderTypeB2B", "OrderTypeRelay", "OrderTypeManual", "OrderTypeImport" ] }, "data": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_posregisters.sessionTotalsResponse" } }, "type": "object" }, "fulfilment.OrderPackingProgress": { "properties": { "containers": { "items": { "$ref": "#/components/schemas/fulfilment.OutboundContainerPlan" }, "type": "array", "uniqueItems": false }, "damages": { "items": { "$ref": "#/components/schemas/fulfilment.PackingDamage" }, "type": "array", "uniqueItems": false }, "discrepancies": { "items": { "$ref": "#/components/schemas/fulfilment.PackingDiscrepancy" }, "type": "array", "uniqueItems": false }, "fulfilled_at": { "type": "string" }, "lines": { "items": { "$ref": "#/components/schemas/fulfilment.PackingLine" }, "type": "array", "uniqueItems": false }, "operator": { "type": "string" }, "packed_at": { "type": "string" }, "started_at": { "type": "string" }, "status": { "$ref": "#/components/schemas/order_enums.FulfillmentStatus" }, "updated_at": { "type": "string" } }, "type": "object" }, "fulfilment.OutboundContainerContent": { "properties": { "allocation_id": { "type": "string" }, "bucket_id": { "type": "string" }, "lot_id": { "type": "string" }, "order_item_id": { "type": "string" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "packed_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "sku_code": { "type": "string" }, "substitutions": { "items": { "$ref": "#/components/schemas/fulfilment.PackageSubstitutionSnapshot" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "fulfilment.OutboundContainerPlan": { "properties": { "container_code": { "type": "string" }, "contents": { "items": { "$ref": "#/components/schemas/fulfilment.OutboundContainerContent" }, "type": "array", "uniqueItems": false }, "id": { "type": "string" }, "is_manually_planned": { "type": "boolean" }, "storage_type": { "$ref": "#/components/schemas/classification_enums.StorageType" }, "updated_at": { "type": "string" } }, "type": "object" }, "fulfilment.PackageSubstitutionSnapshot": { "properties": { "captured_at": { "type": "string" }, "fulfilled_sealed_case_count": { "type": "integer" }, "id": { "type": "string" }, "lot_id": { "type": "string" }, "operator": { "type": "string" }, "reason_code": { "type": "string" }, "replacement_base_units": { "type": "integer" }, "replacement_each_package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "requested_case_count": { "type": "integer" }, "requested_case_package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "requested_units_per_case": { "type": "integer" }, "source_bucket_id": { "type": "string" }, "stock_unit_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "required": [ "captured_at", "fulfilled_sealed_case_count", "id", "lot_id", "operator", "reason_code", "replacement_base_units", "replacement_each_package_option", "requested_case_count", "requested_case_package_option", "requested_units_per_case", "source_bucket_id" ], "type": "object" }, "fulfilment.PackingDamage": { "properties": { "affected_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "handling": { "$ref": "#/components/schemas/warehouse_enums.PackingDamageHandling" }, "id": { "type": "string" }, "note": { "type": "string" }, "quality_assessment_id": { "type": "string" }, "resulting_movement_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "sku_code": { "type": "string" }, "source_bucket_id": { "type": "string" }, "stock_unit_id": { "type": "string" } }, "type": "object" }, "fulfilment.PackingDiscrepancy": { "properties": { "customer_name": { "type": "string" }, "damage_handling": { "$ref": "#/components/schemas/warehouse_enums.PackingDamageHandling" }, "id": { "type": "string" }, "kind": { "$ref": "#/components/schemas/warehouse_enums.PackingDiscrepancyKind" }, "notified": { "type": "boolean" }, "observed_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "order_date": { "type": "string" }, "order_number": { "type": "string" }, "product_name": { "type": "string" }, "quality_assessment_id": { "type": "string" }, "recorded_at": { "type": "string" }, "recorded_by": { "type": "string" }, "refund_amount": { "$ref": "#/components/schemas/money.Money" }, "requested_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "sku_code": { "type": "string" } }, "type": "object" }, "fulfilment.PackingLine": { "properties": { "allocated_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "id": { "type": "string" }, "order_item_id": { "type": "string" }, "packed_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "picked_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "product_name": { "type": "string" }, "refunded_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "requested_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "returned_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "sku_code": { "type": "string" }, "substituted_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "substitutions": { "items": { "$ref": "#/components/schemas/fulfilment.PackageSubstitutionSnapshot" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "fulfilment.PricedPackageComponent": { "properties": { "component_total": { "$ref": "#/components/schemas/money.Money" }, "discount_amount": { "$ref": "#/components/schemas/money.Money" }, "package_price": { "$ref": "#/components/schemas/money.Money" }, "price_snapshot": { "$ref": "#/components/schemas/quote.PriceSnapshot" }, "requested_base_units": { "type": "integer" }, "requested_package_count": { "type": "integer" }, "tax_amount": { "$ref": "#/components/schemas/money.Money" } }, "required": [ "component_total", "discount_amount", "package_price", "price_snapshot", "requested_base_units", "requested_package_count", "tax_amount" ], "type": "object" }, "geography.Address": { "properties": { "administrative_area": { "$ref": "#/components/schemas/geography.AdministrativeAreaRef" }, "country": { "$ref": "#/components/schemas/geography.CountryRef" }, "formatted_address": { "type": "string" }, "label": { "type": "string" }, "latitude": { "type": "number" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "locality": { "description": "Locality covers a city, suburb, town, municipality, or equivalent\npostal locality.", "type": "string" }, "longitude": { "type": "number" }, "place_id": { "type": "string" }, "postal_code": { "type": "string" } }, "required": [ "country", "line1", "locality", "postal_code" ], "type": "object" }, "geography.AdministrativeAreaRef": { "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "type": { "$ref": "#/components/schemas/geography_enums.AdministrativeAreaType" } }, "required": [ "code" ], "type": "object" }, "geography.CountryRef": { "properties": { "code": { "type": "string" }, "name": { "type": "string" } }, "required": [ "code" ], "type": "object" }, "geography.GeographicContext": { "properties": { "evaluation_timezone": { "type": "string" }, "market_code": { "description": "Authoritative single commercial owning market, separate from geographic path selection.", "type": "string" }, "matched_path": { "$ref": "#/components/schemas/geography.GeographicPath" }, "path": { "$ref": "#/components/schemas/geography.GeographicPath" }, "rule_revision": { "type": "integer" }, "scope_revision": { "type": "integer" }, "source": { "$ref": "#/components/schemas/geography_enums.GeographicContextSource" } }, "required": [ "source", "scope_revision", "rule_revision", "evaluation_timezone" ], "type": "object" }, "geography.GeographicPath": { "additionalProperties": false, "description": "One contiguous country, market, state, depot path; each selected child requires all parents. Never mix fields from separate targets.", "properties": { "country_code": { "pattern": "^[A-Z]{2}$", "type": "string" }, "depot_code": { "type": "string" }, "market_code": { "type": "string" }, "state_code": { "type": "string" } }, "required": [ "country_code" ], "type": "object" }, "geography_enums.AdministrativeAreaType": { "enum": [ "STATE", "TERRITORY", "PROVINCE", "PREFECTURE", "REGION", "DISTRICT" ], "type": "string", "x-enum-varnames": [ "AdministrativeAreaState", "AdministrativeAreaTerritory", "AdministrativeAreaProvince", "AdministrativeAreaPrefecture", "AdministrativeAreaRegion", "AdministrativeAreaDistrict" ] }, "geography_enums.GeographicContextSource": { "enum": [ "DELIVERY_ADDRESS", "FULFILMENT_DEPOT", "WHOLESALE_ORGANISATION_PROFILE", "GLOBAL_FALLBACK" ], "type": "string", "x-enum-varnames": [ "GeographicContextSourceDeliveryAddress", "GeographicContextSourceFulfilmentDepot", "GeographicContextSourceWholesaleOrganisationProfile", "GeographicContextSourceGlobalFallback" ] }, "geography_enums.GeographicTargetKind": { "enum": [ "COUNTRY", "MARKET", "STATE", "DEPOT" ], "type": "string", "x-enum-varnames": [ "GeographicTargetCountry", "GeographicTargetMarket", "GeographicTargetState", "GeographicTargetDepot" ] }, "github_com_Potato-Mart_Backend-Payments_internal_modules_invoices.Invoice": { "properties": { "billing": { "$ref": "#/components/schemas/party.ContactAddress" }, "buyer": { "$ref": "#/components/schemas/buyer.BuyerContext" }, "buyer_legal": { "$ref": "#/components/schemas/payment.BuyerLegalSnapshot" }, "created_at": { "type": "string" }, "currency": { "type": "string" }, "customer": { "$ref": "#/components/schemas/party.PartyRef" }, "discount_amount": { "$ref": "#/components/schemas/money.Money" }, "document_kind": { "$ref": "#/components/schemas/payment_enums.DocumentKind" }, "id": { "type": "string" }, "invoice_number": { "type": "string" }, "issued_at": { "type": "string" }, "issuer": { "$ref": "#/components/schemas/merchant.MerchantLegalSnapshot" }, "items": { "items": { "$ref": "#/components/schemas/order.OrderItem" }, "type": "array", "uniqueItems": false }, "order_id": { "type": "string" }, "order_number": { "type": "string" }, "page_content": { "description": "PageContent is the rendered, self-contained HTML the frontend\nconverts to a PDF. Stored so re-rendering is deterministic and\nthe document is immutable once issued.", "type": "string" }, "payment_completeness": { "$ref": "#/components/schemas/payment_enums.PaymentCompleteness" }, "payment_rows": { "description": "PaymentRows is the immutable snapshot of how the order was paid.\nPaymentCompleteness records whether every component was assembled.", "items": { "$ref": "#/components/schemas/payment.CustomerPaymentAllocation" }, "type": "array", "uniqueItems": false }, "processor_fee": { "$ref": "#/components/schemas/money.Money" }, "schema_version": { "type": "integer" }, "shipping_amount": { "$ref": "#/components/schemas/money.Money" }, "status": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_modules_invoices.InvoiceStatus" }, "subtotal": { "$ref": "#/components/schemas/money.Money" }, "surcharge_amount": { "$ref": "#/components/schemas/money.Money" }, "tax_amount": { "$ref": "#/components/schemas/money.Money" }, "tip_amount": { "$ref": "#/components/schemas/money.Money" }, "total": { "$ref": "#/components/schemas/money.Money" }, "updated_at": { "type": "string" } }, "required": [ "created_at", "currency", "customer", "discount_amount", "id", "invoice_number", "items", "order_number", "page_content", "payment_completeness", "payment_rows", "schema_version", "shipping_amount", "status", "subtotal", "surcharge_amount", "tax_amount", "tip_amount", "total", "updated_at" ], "type": "object" }, "github_com_Potato-Mart_Backend-Payments_internal_modules_invoices.InvoiceStatus": { "enum": [ "draft", "issued", "void" ], "type": "string", "x-enum-varnames": [ "InvoiceDraft", "InvoiceIssued", "InvoiceVoid" ] }, "github_com_Potato-Mart_Backend-Payments_internal_modules_payments.PaymentCapability": { "properties": { "payment_method": { "$ref": "#/components/schemas/payment_enums.PaymentMethod" }, "payment_option": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_modules_payments.PaymentOption" }, "presentation": { "type": "string" }, "requires_client_confirmation": { "type": "boolean" }, "requires_redirect": { "type": "boolean" }, "surcharge_applies": { "type": "boolean" } }, "required": [ "payment_method", "payment_option", "presentation", "surcharge_applies" ], "type": "object" }, "github_com_Potato-Mart_Backend-Payments_internal_modules_payments.PaymentMethodInspection": { "properties": { "issuer_country": { "type": "string" }, "issuer_scope": { "type": "string" } }, "required": [ "issuer_scope" ], "type": "object" }, "github_com_Potato-Mart_Backend-Payments_internal_modules_payments.PaymentOption": { "enum": [ "apple_pay", "google_pay", "card", "payto", "link" ], "type": "string", "x-enum-varnames": [ "PaymentOptionApplePay", "PaymentOptionGooglePay", "PaymentOptionCard", "PaymentOptionPayTo", "PaymentOptionLink" ] }, "github_com_Potato-Mart_Backend-Payments_internal_modules_payments.RecordGiftCardInput": { "properties": { "amount": { "$ref": "#/components/schemas/money.Money" }, "gift_card_code": { "type": "string" }, "idempotency_key": { "type": "string" }, "order_number": { "type": "string" }, "wallet_transaction_id": { "type": "string" } }, "required": [ "amount", "gift_card_code", "idempotency_key", "order_number", "wallet_transaction_id" ], "type": "object" }, "github_com_Potato-Mart_Backend-Payments_internal_modules_payments.SessionStatus": { "properties": { "amount_minor": { "type": "integer" }, "capture_timing": { "$ref": "#/components/schemas/payment.CaptureTimingEvidence" }, "checkout_session_id": { "description": "Checkout identity from the validated durable session binding, when recorded.", "type": "string" }, "currency": { "type": "string" }, "order_number": { "description": "Order identity from the validated durable session binding.", "type": "string" }, "payment_id": { "type": "string" }, "provider": { "description": "Provider from the validated durable session binding (STRIPE_ONLINE).", "type": "string" }, "provider_session_id": { "type": "string" }, "requested_provider_session_id": { "description": "Original durable provider session identity, retaining the hosted Checkout identity for PaymentIntent alias lookups.", "type": "string" }, "status": { "type": "string" } }, "required": [ "amount_minor", "currency", "provider_session_id", "status" ], "type": "object" }, "github_com_Potato-Mart_Backend-Payments_internal_modules_refunds.Kind": { "enum": [ "full", "partial_lines", "partial_amount" ], "type": "string", "x-enum-varnames": [ "KindFull", "KindPartialLines", "KindPartialAmount" ] }, "github_com_Potato-Mart_Backend-Payments_internal_modules_refunds.Refund": { "properties": { "amount": { "$ref": "#/components/schemas/money.Money" }, "confirmed_at": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "destination": { "$ref": "#/components/schemas/refunds.RefundDestination", "description": "Always present in responses; original_tender for every refund without a stored destination." }, "failed_at": { "type": "string" }, "full_order_refund": { "description": "FullOrderRefund is frozen when the row consumes the order's entire\nremaining reserved refundable balance. Reconciliation separately proves\nthat completed refunds now equal all captured sources before it asks\nPricing to reactivate a coupon.", "type": "boolean" }, "gift_card_issuance": { "$ref": "#/components/schemas/refunds.GiftCardIssuanceEvidence", "description": "Present only for a new_gift_card destination." }, "gift_card_refund_amount": { "$ref": "#/components/schemas/money.Money" }, "gift_remedy_state": { "description": "Present only for a purchased gift-value remedy; refund status remains the money outcome.", "enum": [ "pending", "prepared", "completed", "released", "refused" ], "type": "string" }, "id": { "type": "string" }, "idempotency_key": { "type": "string" }, "kind": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_modules_refunds.Kind" }, "lines": { "items": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_modules_refunds.RefundLine" }, "type": "array", "uniqueItems": false }, "order_number": { "type": "string" }, "packing_review": { "$ref": "#/components/schemas/refunds.PackingRefundReview" }, "payment_id": { "type": "string" }, "points_to_restore": { "type": "integer" }, "provider": { "type": "string" }, "provider_ref": { "type": "string" }, "qualifying_spend_reversal": { "$ref": "#/components/schemas/money.Money" }, "reason": { "type": "string" }, "request_generation": { "type": "integer" }, "schema_version": { "type": "integer" }, "source": { "description": "Stable source correlation is returned by the internal detail endpoint and\nincluded in the idempotency fingerprint for Orders short-ship commands.", "type": "string" }, "source_discrepancy_id": { "type": "string" }, "source_refund_request_id": { "type": "string" }, "status": { "$ref": "#/components/schemas/payment_enums.PaymentRecordStatus" }, "terminal_handoff": { "$ref": "#/components/schemas/refunds.TerminalHandoff" } }, "required": [ "amount", "created_at", "gift_card_refund_amount", "id", "kind", "order_number", "provider", "qualifying_spend_reversal", "schema_version", "source", "status" ], "type": "object" }, "github_com_Potato-Mart_Backend-Payments_internal_modules_refunds.RefundComponentAllocation": { "properties": { "amount": { "$ref": "#/components/schemas/money.Money" }, "base_unit_ordinal_end": { "format": "int64", "minimum": 1, "type": "integer" }, "base_unit_ordinal_start": { "description": "Present only for a reviewed partial CASE refund; addresses original commercial component base units instead of whole package ordinals.", "format": "int64", "minimum": 1, "type": "integer" }, "base_units": { "type": "integer" }, "component_index": { "type": "integer" }, "converted_base_unit_ordinal_end": { "description": "Last original commercial unit in the verified whole-CASE conversion span.", "minimum": 1, "type": "integer" }, "converted_base_unit_ordinal_start": { "description": "First original commercial unit in the verified whole-CASE conversion span.", "minimum": 1, "type": "integer" }, "handling_unit": { "$ref": "#/components/schemas/packaging_enums.PackageHandlingUnit" }, "package_count": { "type": "integer" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "package_ordinal_end": { "type": "integer" }, "package_ordinal_start": { "type": "integer" }, "price_line_id": { "type": "string" }, "quote_id": { "description": "QuoteID and PriceLineID identify the frozen quote.PriceSnapshot this\nallocation was priced against. They replace the retired\npackage_pricing_id/package_pricing_revision pair. PackagePricing was split\ninto a Pricing-owned commercial snapshot and\nSupply-owned inventory evidence, and mongox's retired-key guard fails the\nbuild if either old key reappears in an update or a query.\n\nA refund is always priced against the ORIGINAL snapshot. Re-reading a\nlive price here would let a later price change rewrite history, which is\nexactly what freezing the snapshot prevents.", "type": "string" }, "review_reservation_key": { "description": "Existing reviewed refund authority used only to close its exact remaining component units and paid money.", "type": "string" }, "source_bucket_id": { "description": "SourceBucketID and SourceStockUnitID come from the Supply sale-eligibility\nevidence embedded in that snapshot.", "type": "string" }, "source_stock_unit_id": { "type": "string" }, "units_per_package": { "type": "integer" } }, "required": [ "amount", "base_units", "component_index", "handling_unit", "package_count", "package_option", "package_ordinal_end", "package_ordinal_start", "price_line_id", "quote_id", "units_per_package" ], "type": "object" }, "github_com_Potato-Mart_Backend-Payments_internal_modules_refunds.RefundLine": { "properties": { "amount": { "$ref": "#/components/schemas/money.Money" }, "components": { "items": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_modules_refunds.RefundComponentAllocation" }, "type": "array", "uniqueItems": false }, "composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "item_id": { "type": "string" }, "participant_shares": { "items": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_modules_refunds.RefundParticipantShare" }, "type": "array", "uniqueItems": false }, "sku_code": { "type": "string" } }, "required": [ "amount", "components", "composition", "item_id", "sku_code" ], "type": "object" }, "github_com_Potato-Mart_Backend-Payments_internal_modules_refunds.RefundParticipantShare": { "properties": { "amount": { "$ref": "#/components/schemas/money.Money" }, "composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "parent_allocation_line_id": { "type": "string" }, "participant_order_item_id": { "type": "string" }, "participant_order_number": { "type": "string" } }, "required": [ "amount", "composition", "parent_allocation_line_id", "participant_order_item_id", "participant_order_number" ], "type": "object" }, "github_com_Potato-Mart_Backend-Payments_internal_platform_apiresponse.Error": { "properties": { "code": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_apiresponse_apiresponse_enums.Code" }, "details": { "additionalProperties": { "type": "string" }, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "github_com_Potato-Mart_Backend-Payments_internal_platform_apiresponse_apiresponse_enums.Code": { "enum": [ "INTERNAL_ERROR", "BAD_REQUEST", "VALIDATION_ERROR", "NOT_FOUND", "CONFLICT", "UNAUTHORIZED", "FORBIDDEN", "TOO_MANY_REQUESTS", "REQUEST_BODY_TOO_LARGE", "SERVICE_UNAVAILABLE", "AUTH_INVALID_CREDENTIALS", "AUTH_INVALID_TOKEN", "AUTH_EXPIRED_TOKEN", "AUTH_WRONG_PORTAL", "AUTH_ACCOUNT_DISABLED", "AUTH_MFA_REQUIRED", "AUTH_REAUTH_REQUIRED", "EMAIL_VERIFICATION_REQUIRED", "SECURITY_POLICY_VIOLATION", "IDENTITY_ACCOUNT_TYPE_NOT_ALLOWED", "IDENTITY_PORTAL_ACCESS_DENIED", "IDENTITY_PORTAL_ACCESS_REVOKED", "IDENTITY_ACCOUNT_SUSPENDED", "IDENTITY_AUTH_IDENTITY_DISABLED", "IDENTITY_MFA_REQUIRED", "IDENTITY_WHOLESALE_ORGANISATION_NOT_APPROVED", "IDENTITY_ORGANISATION_ACCESS_REQUIRED", "MEMBERSHIP_NOT_FOUND", "MEMBERSHIP_INACTIVE", "MEMBERSHIP_INSUFFICIENT_POINTS", "MEMBERSHIP_REWARD_UNAVAILABLE", "MEMBERSHIP_POINT_RESERVATION_EXPIRED", "USER_EMAIL_TAKEN", "SKU_CODE_TAKEN", "STORAGE_LOCATION_CODE_TAKEN", "PRODUCT_CODE_TAKEN", "STORAGE_MISMATCH", "INSUFFICIENT_STOCK", "ORDER_INVALID_TRANSITION", "ORDER_TERMINAL", "ORDER_EMPTY", "CART_NOT_ACTIVE", "DISCOUNT_NOT_FOUND", "DISCOUNT_INACTIVE", "DISCOUNT_NOT_STARTED", "DISCOUNT_EXPIRED", "DISCOUNT_EXHAUSTED", "DISCOUNT_MIN_NOT_MET", "DISCOUNT_CODE_TAKEN", "DISCOUNT_INAPPLICABLE", "TERMINAL_NOT_CONNECTED", "TERMINAL_NOT_REGISTERED", "TERMINAL_OUTCOME_UNKNOWN", "TERMINAL_SIGNATURE_FAIL", "TERMINAL_TIMEOUT", "TERMINAL_REQUEST_REJECTED", "TERMINAL_BUSY", "REFUND_ALTERNATIVE_OFFER_OPEN", "REFUND_REQUEST_SHORTAGE_CHANGED", "REGISTER_ARCHIVED", "REGISTER_HAS_OPEN_SESSION", "SESSION_NOT_EMPTY" ], "type": "string", "x-enum-varnames": [ "CodeInternal", "CodeBadRequest", "CodeValidation", "CodeNotFound", "CodeConflict", "CodeUnauthorized", "CodeForbidden", "CodeTooManyRequests", "CodeRequestTooLarge", "CodeServiceUnavailable", "CodeAuthInvalidCredentials", "CodeAuthInvalidToken", "CodeAuthExpiredToken", "CodeAuthWrongPortal", "CodeAuthAccountDisabled", "CodeAuthMFARequired", "CodeAuthReauthRequired", "CodeEmailVerificationRequired", "CodeSecurityPolicyViolation", "CodeIdentityAccountTypeNotAllowed", "CodeIdentityPortalAccessDenied", "CodeIdentityPortalAccessRevoked", "CodeIdentityAccountSuspended", "CodeIdentityAuthIdentityDisabled", "CodeIdentityMFARequired", "CodeIdentityWholesaleOrganisationNotApproved", "CodeIdentityOrganisationAccessRequired", "CodeMembershipNotFound", "CodeMembershipInactive", "CodeMembershipInsufficientPoints", "CodeMembershipRewardUnavailable", "CodeMembershipPointReservationExpired", "CodeUserEmailTaken", "CodeSKUCodeTaken", "CodeStorageLocationCodeTaken", "CodeProductCodeTaken", "CodeStorageMismatch", "CodeInsufficientStock", "CodeOrderInvalidTransition", "CodeOrderTerminal", "CodeOrderEmpty", "CodeCartNotActive", "CodeDiscountNotFound", "CodeDiscountInactive", "CodeDiscountNotStarted", "CodeDiscountExpired", "CodeDiscountExhausted", "CodeDiscountMinNotMet", "CodeDiscountCodeTaken", "CodeDiscountInapplicable", "CodeTerminalNotConnected", "CodeTerminalNotRegistered", "CodeTerminalOutcomeUnknown", "CodeTerminalSignatureFail", "CodeTerminalTimeout", "CodeTerminalRequestRejected", "CodeTerminalBusy", "CodeRefundAlternativeOfferOpen", "CodeRefundRequestShortageChanged", "CodeRegisterArchived", "CodeRegisterHasOpenSession", "CodeSessionNotEmpty" ] }, "github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "required": [ "success" ], "type": "object" }, "group_order.GroupOrderAggregateLine": { "properties": { "allocated_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "allocation_line_id": { "type": "string" }, "components": { "items": { "$ref": "#/components/schemas/fulfilment.PricedPackageComponent" }, "type": "array", "uniqueItems": false }, "discount_amount": { "$ref": "#/components/schemas/money.Money" }, "id": { "type": "string" }, "market_code": { "type": "string" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "refund_amount": { "$ref": "#/components/schemas/money.Money" }, "refunded_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "requested_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "reservation_id": { "type": "string" }, "returned_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "shortage_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "sku_code": { "type": "string" }, "tax_amount": { "$ref": "#/components/schemas/money.Money" }, "total": { "$ref": "#/components/schemas/money.Money" } }, "type": "object" }, "group_order.GroupOrderContext": { "properties": { "group_order_code": { "type": "string" }, "parent_allocation_line_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "parent_fulfilment_id": { "type": "string" }, "parent_order_number": { "type": "string" }, "role": { "$ref": "#/components/schemas/group_order_enums.GroupOrderRole" } }, "type": "object" }, "group_order.GroupOrderFulfilmentPlan": { "properties": { "aggregate_lines": { "items": { "$ref": "#/components/schemas/group_order.GroupOrderAggregateLine" }, "type": "array", "uniqueItems": false }, "captured_at": { "type": "string" }, "group_order_code": { "type": "string" }, "id": { "type": "string" }, "parent_fulfilment_id": { "type": "string" }, "parent_order_number": { "type": "string" }, "participant_shares": { "items": { "$ref": "#/components/schemas/group_order.GroupOrderParticipantShare" }, "type": "array", "uniqueItems": false }, "revision": { "type": "integer" }, "timezone": { "type": "string" } }, "type": "object" }, "group_order.GroupOrderParticipantShare": { "properties": { "components": { "items": { "$ref": "#/components/schemas/fulfilment.PricedPackageComponent" }, "type": "array", "uniqueItems": false }, "discount_amount": { "$ref": "#/components/schemas/money.Money" }, "fulfilled_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "parent_allocation_line_id": { "type": "string" }, "participant_order_item_id": { "type": "string" }, "participant_order_number": { "type": "string" }, "refund_amount": { "$ref": "#/components/schemas/money.Money" }, "refunded_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "requested_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "returned_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "sequence": { "type": "integer" }, "shortage_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "tax_amount": { "$ref": "#/components/schemas/money.Money" }, "total": { "$ref": "#/components/schemas/money.Money" } }, "type": "object" }, "group_order_enums.GroupOrderRole": { "enum": [ "CONSOLIDATED_PARENT", "PARTICIPANT" ], "type": "string", "x-enum-varnames": [ "GroupOrderRoleConsolidatedParent", "GroupOrderRoleParticipant" ] }, "internal_modules_invoices.InvoiceCardPaymentResult": { "properties": { "invoice_id": { "type": "string" }, "invoice_number": { "type": "string" }, "order_number": { "type": "string" }, "payment": { "$ref": "#/components/schemas/internal_modules_invoices.InvoiceCardPaymentSession" }, "total": { "$ref": "#/components/schemas/money.Money" } }, "required": [ "invoice_id", "invoice_number", "order_number", "payment", "total" ], "type": "object" }, "internal_modules_invoices.InvoiceCardPaymentSession": { "properties": { "client_key": { "type": "string" }, "expires_at": { "type": "string" }, "payment_option": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_modules_payments.PaymentOption" }, "presentation": { "type": "string" }, "provider": { "type": "string" }, "provider_session_id": { "type": "string" }, "return_url": { "type": "string" }, "session_data": { "type": "string" }, "surcharge": { "$ref": "#/components/schemas/money.Money" } }, "required": [ "payment_option", "presentation", "provider", "provider_session_id", "return_url", "surcharge" ], "type": "object" }, "internal_modules_paymentmethods.Bootstrap": { "properties": { "customer_session_client_secret": { "type": "string" }, "publishable_key": { "type": "string" }, "setup_intent_client_secret": { "type": "string" }, "stripe_customer_id": { "type": "string" } }, "required": [ "customer_session_client_secret", "publishable_key", "setup_intent_client_secret", "stripe_customer_id" ], "type": "object" }, "internal_modules_paymentmethods.List": { "properties": { "methods": { "items": { "$ref": "#/components/schemas/internal_modules_paymentmethods.Summary" }, "type": "array", "uniqueItems": false } }, "required": [ "methods" ], "type": "object" }, "internal_modules_paymentmethods.Summary": { "properties": { "brand": { "type": "string" }, "exp_month": { "type": "integer" }, "exp_year": { "type": "integer" }, "id": { "type": "string" }, "is_default": { "type": "boolean" }, "last4": { "type": "string" }, "type": { "type": "string" } }, "required": [ "brand", "exp_month", "exp_year", "id", "is_default", "last4", "type" ], "type": "object" }, "internal_modules_paymentsinternal.CancelSessionRequest": { "properties": { "checkout_session_id": { "type": "string" }, "idempotency_key": { "type": "string" } }, "required": [ "idempotency_key" ], "type": "object" }, "internal_modules_paymentsinternal.CancelSessionResponse": { "properties": { "provider": { "type": "string" }, "provider_session_id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "provider", "provider_session_id", "status" ], "type": "object" }, "internal_modules_paymentsinternal.CancelUnpaidOrderRequest": { "additionalProperties": false, "properties": { "idempotency_key": { "maxLength": 200, "minLength": 1, "type": "string" } }, "required": [ "idempotency_key" ], "type": "object" }, "internal_modules_paymentsinternal.CapabilitiesRequest": { "properties": { "apple_pay_ready": { "type": "boolean" }, "currency": { "type": "string" }, "google_pay_ready": { "description": "The two wallet-readiness probes Orders forwards from the storefront.\nThey are independent: a retail_web request may carry both.", "type": "boolean" }, "market_code": { "type": "string" }, "payment_presentation": { "description": "Send only for staff-created payment links. PayTo is advertised for nothing else.", "enum": [ "hosted_checkout" ], "type": "string" }, "platform": { "type": "string" }, "purchase_kind": { "type": "string" }, "retail_persona": { "type": "string" } }, "type": "object" }, "internal_modules_paymentsinternal.CapabilitiesResponse": { "properties": { "methods": { "items": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_modules_payments.PaymentCapability" }, "type": "array", "uniqueItems": false } }, "required": [ "methods" ], "type": "object" }, "internal_modules_paymentsinternal.CreateSessionRequest": { "properties": { "amount": { "$ref": "#/components/schemas/money.Money" }, "buyer_type": { "$ref": "#/components/schemas/retail_enums.BuyerType" }, "cart_id": { "type": "string" }, "checkout_session_id": { "type": "string" }, "country_code": { "type": "string" }, "customer_account_id": { "description": "Canonical payer account; may be empty only for hosted guest_retail.", "type": "string" }, "customer_email": { "type": "string" }, "customer_ref": { "type": "string" }, "idempotency_key": { "type": "string" }, "order_number": { "type": "string" }, "order_total": { "$ref": "#/components/schemas/money.Money" }, "payment_method": { "$ref": "#/components/schemas/payment_enums.PaymentMethod" }, "payment_option": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_modules_payments.PaymentOption" }, "payment_presentation": { "description": "Explicit hosted card, PayTo or Link Checkout. Omit for existing embedded presentations. PayTo requires this value.", "enum": [ "hosted_checkout" ], "type": "string" }, "return_target": { "type": "string" }, "stripe_payment_method_id": { "type": "string" }, "surcharge": { "$ref": "#/components/schemas/money.Money" } }, "required": [ "amount", "buyer_type", "order_number", "order_total", "return_target" ], "type": "object" }, "internal_modules_paymentsinternal.EnsureInvoiceRequest": { "properties": { "mode": { "description": "paid | confirmed", "type": "string" }, "order": { "$ref": "#/components/schemas/order.Order" } }, "required": [ "mode", "order" ], "type": "object" }, "internal_modules_paymentsinternal.EnsurePOSReceiptRequest": { "additionalProperties": false, "description": "Empty command. The order is named by the path; any field is refused.", "properties": {}, "type": "object" }, "internal_modules_paymentsinternal.GenerateInvoiceRequest": { "properties": { "issue": { "type": "boolean" }, "order_number": { "type": "string" } }, "required": [ "order_number" ], "type": "object" }, "internal_modules_paymentsinternal.InspectPaymentMethodRequest": { "properties": { "customer_account_id": { "type": "string" }, "payment_option": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_modules_payments.PaymentOption" }, "stripe_payment_method_id": { "type": "string" } }, "required": [ "customer_account_id", "payment_option", "stripe_payment_method_id" ], "type": "object" }, "internal_modules_paymentsinternal.ReverseCapturedPaymentRequest": { "properties": { "amount": { "$ref": "#/components/schemas/money.Money" }, "idempotency_key": { "type": "string" }, "order_number": { "type": "string" }, "payment_id": { "type": "string" }, "provider_session_id": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "idempotency_key", "order_number" ], "type": "object" }, "internal_modules_paymentsinternal.SessionResponse": { "properties": { "client_key": { "type": "string" }, "expires_at": { "type": "string" }, "hosted_url": { "description": "Provider-hosted URL; only present for explicit hosted_checkout. expires_at is provider expiry, not inventory reservation expiry.", "format": "uri", "type": "string" }, "payment_option": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_modules_payments.PaymentOption" }, "presentation": { "type": "string" }, "provider": { "type": "string" }, "provider_session_id": { "type": "string" }, "provider_status": { "type": "string" }, "return_url": { "type": "string" }, "session_data": { "type": "string" }, "surcharge": { "$ref": "#/components/schemas/money.Money" }, "surcharge_status": { "type": "string" } }, "required": [ "payment_option", "presentation", "provider", "provider_session_id", "return_url", "surcharge" ], "type": "object" }, "internal_modules_paymentsinternal.SessionStatusRequest": { "properties": { "provider": { "type": "string" }, "provider_session_id": { "type": "string" } }, "required": [ "provider_session_id" ], "type": "object" }, "internal_modules_posregisters.CheckoutContext": { "description": "Payments-owned attribution for an open session with an active, matching register. Orders must additionally enforce the requesting operator's geographic scope.", "properties": { "country_code": { "minLength": 1, "type": "string" }, "depot_code": { "minLength": 1, "type": "string" }, "market_code": { "minLength": 1, "type": "string" }, "register_id": { "minLength": 1, "type": "string" }, "session_id": { "minLength": 1, "type": "string" }, "terminal_id": { "minLength": 1, "type": "string" } }, "required": [ "session_id", "register_id", "depot_code", "market_code", "country_code" ], "type": "object" }, "internal_modules_posregisters.DeletedSession": { "properties": { "business_date": { "type": "string" }, "deleted_at": { "format": "date-time", "type": "string" }, "deleted_by": { "type": "string" }, "register_id": { "type": "string" }, "session_id": { "type": "string" }, "status": { "$ref": "#/components/schemas/register_enums.SessionStatus" } }, "required": [ "session_id", "register_id", "business_date", "status", "deleted_at" ], "type": "object" }, "internal_modules_posregisters.cashMovementResponse": { "properties": { "amount": { "$ref": "#/components/schemas/money.Money" }, "classification": { "$ref": "#/components/schemas/security_enums.DataClassification" }, "contains_pii": { "type": "boolean" }, "contains_sensitive_pii": { "type": "boolean" }, "data_owner_id": { "type": "string" }, "deletion_completed_at": { "type": "string" }, "deletion_requested_at": { "type": "string" }, "depot_code": { "type": "string" }, "id": { "type": "string" }, "kind": { "$ref": "#/components/schemas/register_enums.CashMovementKind" }, "legal_hold": { "type": "boolean" }, "occurred_at": { "type": "string" }, "protection_basis": { "$ref": "#/components/schemas/security_enums.DataProtectionBasis" }, "reason": { "type": "string" }, "recorded_by": { "type": "string" }, "register_id": { "type": "string" }, "retention_policy_key": { "type": "string" }, "retention_until": { "type": "string" }, "session_id": { "type": "string" } }, "type": "object" }, "internal_modules_posregisters.registerResponse": { "properties": { "archive_reason": { "description": "Present only on an archived register when a reason was given.", "type": "string" }, "archived_at": { "description": "Present only on an archived register.", "format": "date-time", "type": "string" }, "archived_by": { "description": "Present only on an archived register (actor email, or user id when no email).", "type": "string" }, "country_code": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "depot_code": { "type": "string" }, "id": { "type": "string" }, "market_code": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "terminal_id": { "type": "string" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } }, "type": "object" }, "internal_modules_posregisters.registerSessionResponse": { "properties": { "business_date": { "type": "string" }, "cash_variance": { "$ref": "#/components/schemas/money.Money" }, "classification": { "$ref": "#/components/schemas/security_enums.DataClassification" }, "closed_at": { "type": "string" }, "closed_by_user_id": { "type": "string" }, "closing_count": { "$ref": "#/components/schemas/money.Money" }, "contains_pii": { "type": "boolean" }, "contains_sensitive_pii": { "type": "boolean" }, "country_code": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "data_owner_id": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "deletion_completed_at": { "type": "string" }, "deletion_requested_at": { "type": "string" }, "depot_code": { "type": "string" }, "expected_cash": { "$ref": "#/components/schemas/money.Money" }, "id": { "type": "string" }, "legal_hold": { "type": "boolean" }, "market_code": { "type": "string" }, "opened_at": { "type": "string" }, "opened_by_user_id": { "type": "string" }, "opening_float": { "$ref": "#/components/schemas/money.Money" }, "protection_basis": { "$ref": "#/components/schemas/security_enums.DataProtectionBasis" }, "register_id": { "type": "string" }, "retention_policy_key": { "type": "string" }, "retention_until": { "type": "string" }, "sequence": { "description": "Numbers the register's sessions on business_date from 1. A register has at most one open session at a time and may run several sequential sessions per business date; (register_id, business_date, sequence) identifies a session. Sessions recorded before sequential sessions carry 1.", "format": "int64", "minimum": 1, "type": "integer" }, "status": { "$ref": "#/components/schemas/register_enums.SessionStatus" }, "terminal_id": { "type": "string" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } }, "type": "object" }, "internal_modules_posregisters.sessionTotalsResponse": { "properties": { "business_date": { "type": "string" }, "cash_movement_total": { "$ref": "#/components/schemas/money.Money" }, "depot_code": { "type": "string" }, "generated_at": { "type": "string" }, "manual_discount_count": { "description": "Number of sales in the session that carried a cart-level manual discount. Omitted when the session had none, or when the report predates the field.", "format": "int64", "type": "integer" }, "manual_discount_total": { "$ref": "#/components/schemas/money.Money", "description": "Sum of the cart-level manual discounts on the session's receipts. This is discount given, not a deduction that reconciles against method_totals, which already net it. Omitted when the session had none." }, "method_totals": { "items": { "$ref": "#/components/schemas/register.MethodTotal" }, "type": "array", "uniqueItems": false }, "refund_total": { "$ref": "#/components/schemas/money.Money" }, "register_id": { "type": "string" }, "session_id": { "type": "string" } }, "type": "object" }, "listing.DamageSaleApproval": { "properties": { "approved_at": { "type": "string" }, "approved_by": { "type": "string" }, "quality_assessment_id": { "type": "string" }, "reason_code": { "type": "string" }, "tier": { "$ref": "#/components/schemas/warehouse_enums.DamageSaleTier" } }, "required": [ "approved_at", "approved_by", "quality_assessment_id", "reason_code", "tier" ], "type": "object" }, "listing.SaleEligibilitySnapshot": { "description": "Eligibility is the Supply-owned physical inventory evidence the price was\nresolved against, referencing Pricing-owned listing revision and tax category facts.", "properties": { "available_base_units": { "type": "integer" }, "bucket_id": { "type": "string" }, "captured_at": { "type": "string" }, "condition": { "$ref": "#/components/schemas/warehouse_enums.InventoryCondition" }, "damage_approval": { "$ref": "#/components/schemas/listing.DamageSaleApproval" }, "date_mark": { "$ref": "#/components/schemas/warehouse.InventoryDateMark" }, "depot_code": { "type": "string" }, "disposition": { "$ref": "#/components/schemas/warehouse_enums.InventoryDisposition" }, "expiry_lead_days": { "description": "ExpiryLeadDays is the soon-expiry lead time that was in force, after\nany listing override.", "type": "integer" }, "inventory_revision": { "type": "integer" }, "listing_revision": { "type": "integer" }, "lot_id": { "type": "string" }, "market_code": { "type": "string" }, "sku_code": { "type": "string" }, "stock_location": { "$ref": "#/components/schemas/warehouse.StockLocationRef" }, "stock_unit_id": { "type": "string" }, "tax_category_code": { "type": "string" }, "valid_until": { "type": "string" }, "validity_token": { "type": "string" } }, "required": [ "available_base_units", "captured_at", "condition", "depot_code", "disposition", "expiry_lead_days", "inventory_revision", "listing_revision", "market_code", "sku_code", "stock_location", "tax_category_code", "valid_until", "validity_token" ], "type": "object" }, "localization.LocalizedText": { "properties": { "language": { "type": "string" }, "text": { "type": "string" } }, "required": [ "language", "text" ], "type": "object" }, "market_enums.PriceAudience": { "enum": [ "retail", "wholesale" ], "type": "string", "x-enum-varnames": [ "PriceAudienceRetail", "PriceAudienceWholesale" ] }, "measurement.Dimensions": { "properties": { "height_mm": { "type": "integer" }, "length_mm": { "type": "integer" }, "width_mm": { "type": "integer" } }, "required": [ "height_mm", "length_mm", "width_mm" ], "type": "object" }, "measurement.Measure": { "properties": { "amount": { "type": "integer" }, "exponent": { "type": "integer" }, "unit": { "type": "string" } }, "required": [ "amount", "exponent", "unit" ], "type": "object" }, "measurement.NetContent": { "properties": { "net_quantity": { "$ref": "#/components/schemas/measurement.Measure" }, "standard_measure": { "$ref": "#/components/schemas/measurement.Measure" } }, "required": [ "net_quantity", "standard_measure" ], "type": "object" }, "measurement.Weight": { "properties": { "grams": { "type": "integer" } }, "required": [ "grams" ], "type": "object" }, "media.DownloadURL": { "properties": { "code": { "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "method": { "enum": [ "GET" ], "type": "string" }, "mime_type": { "type": "string" }, "url": { "type": "string" } }, "required": [ "code", "url", "method", "mime_type", "expires_at" ], "type": "object" }, "media.Evidence": { "properties": { "captured_at": { "format": "date-time", "type": "string" }, "captured_by": { "description": "User id of the staff member who finalized the evidence.", "type": "string" }, "code": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "mime_type": { "type": "string" }, "order_number": { "type": "string" }, "payment_id": { "description": "The bank-transfer payment the evidence is attached to.", "type": "string" }, "sha256": { "type": "string" }, "size_bytes": { "format": "int64", "type": "integer" }, "status": { "enum": [ "pending", "active", "deleted" ], "type": "string" } }, "required": [ "code", "order_number", "status", "mime_type", "created_at" ], "type": "object" }, "media.FinalizeRequest": { "additionalProperties": false, "properties": { "sha256": { "description": "Hex SHA-256 of the uploaded bytes.", "pattern": "^[0-9a-fA-F]{64}$", "type": "string" } }, "required": [ "sha256" ], "type": "object" }, "media.Header": { "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value" ], "type": "object" }, "media.UploadRequest": { "additionalProperties": false, "properties": { "filename": { "description": "Display only; never part of the object name.", "maxLength": 200, "type": "string" }, "mime_type": { "enum": [ "image/jpeg", "image/png", "image/webp", "image/heic", "application/pdf" ], "type": "string" }, "order_number": { "minLength": 1, "type": "string" }, "size_bytes": { "format": "int64", "maximum": 10485760, "minimum": 1, "type": "integer" } }, "required": [ "order_number", "mime_type", "size_bytes" ], "type": "object" }, "media.UploadURL": { "properties": { "code": { "description": "Evidence code (24 lowercase hex) used by finalize and the bank-transfer payment.", "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "headers": { "description": "Headers the PUT must send unchanged (Content-Type).", "items": { "$ref": "#/components/schemas/media.Header" }, "type": "array" }, "max_bytes": { "format": "int64", "type": "integer" }, "method": { "enum": [ "PUT" ], "type": "string" }, "upload_url": { "description": "V4 signed URL for one PUT of the raw bytes.", "type": "string" } }, "required": [ "code", "upload_url", "method", "headers", "max_bytes", "expires_at" ], "type": "object" }, "merchant.MerchantLegalSnapshot": { "description": "Issuer is the merchant legal identity FROZEN at issuance. A later profile\nedit, or a new revision superseding this one, never changes what an\nissued document says.", "properties": { "address": { "$ref": "#/components/schemas/geography.Address" }, "business_number": { "type": "string" }, "business_number_scheme": { "$ref": "#/components/schemas/payment_enums.BusinessNumberScheme" }, "business_number_scheme_label": { "type": "string" }, "contact": { "$ref": "#/components/schemas/party.Recipient" }, "frozen_at": { "type": "string" }, "legal_name": { "type": "string" }, "market_code": { "type": "string" }, "profile_id": { "type": "string" }, "profile_revision": { "type": "integer" }, "tax_registration_number": { "type": "string" }, "tax_registration_status": { "$ref": "#/components/schemas/payment_enums.TaxRegistrationStatus" }, "trading_name": { "type": "string" } }, "type": "object" }, "metadata.Metadata": { "additionalProperties": {}, "description": "Metadata stores source-specific details that should not become first-class\ncontract fields yet, for example app_version, operator_id,\nforwarded_for, device_model, or network_interface.", "type": "object" }, "money.CurrencyExponent": { "properties": { "currency": { "type": "string" }, "exponent": { "type": "integer" } }, "required": [ "currency", "exponent" ], "type": "object" }, "money.Money": { "description": "TipAmount and SurchargeAmount surface card-terminal-applied\nextras. They are part of the customer-paid total and must appear\non tax invoices.\nCashout is intentionally not on Order - it is a parallel cash\nwithdrawal that does not change the order's payable total - and\nlives only on Payment / TerminalTransaction.", "properties": { "amount_minor": { "type": "integer" }, "currency": { "type": "string" } }, "required": [ "amount_minor", "currency" ], "type": "object" }, "order.GiftCardRedemptionSnapshot": { "properties": { "applied_amount": { "$ref": "#/components/schemas/money.Money" }, "gift_card_code": { "type": "string" }, "occurred_at": { "type": "string" }, "reservation_id": { "type": "string" }, "wallet_transaction_id": { "type": "string" } }, "type": "object" }, "order.LooseSubstitutionPolicySnapshot": { "properties": { "allowed": { "type": "boolean" }, "captured_at": { "type": "string" }, "source": { "$ref": "#/components/schemas/order_enums.LooseSubstitutionPolicySource" } }, "required": [ "allowed", "captured_at", "source" ], "type": "object" }, "order.Order": { "properties": { "billing": { "$ref": "#/components/schemas/party.ContactAddress" }, "buyer": { "$ref": "#/components/schemas/buyer.BuyerContext" }, "cancelled_at": { "type": "string" }, "channel": { "$ref": "#/components/schemas/commerce_enums.OrderType" }, "completed_at": { "type": "string" }, "confirmed_at": { "description": "── Lifecycle timestamps ──────────────────────────────────────────", "type": "string" }, "country_code": { "description": "CountryCode is the denormalized country of MarketCode, carried so a\ncountry-scoped staff query is a plain indexed match.", "type": "string" }, "coupon_code": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "customer": { "$ref": "#/components/schemas/party.PartyRef" }, "customer_note": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "delivered_at": { "type": "string" }, "delivery_method": { "$ref": "#/components/schemas/shipping_enums.DeliveryMethod" }, "discount_amount": { "$ref": "#/components/schemas/money.Money" }, "expected_delivery_date": { "description": "── Delivery scheduling ───────────────────────────────────────────\nExpectedDeliveryDate/Time are the promised delivery slot, set by\nstaff or checkout — distinct from the DeliveredAt lifecycle\ntimestamp recorded after the fact.", "type": "string" }, "expected_delivery_time": { "type": "string" }, "fulfillment_readiness": { "$ref": "#/components/schemas/order_enums.FulfillmentReadiness" }, "fulfillment_status": { "$ref": "#/components/schemas/order_enums.FulfillmentStatus" }, "fulfilment_location": { "$ref": "#/components/schemas/shipping.FulfilmentLocationSnapshot" }, "gift_card_redemptions": { "items": { "$ref": "#/components/schemas/order.GiftCardRedemptionSnapshot" }, "type": "array", "uniqueItems": false }, "group_order": { "$ref": "#/components/schemas/group_order.GroupOrderContext" }, "group_order_fulfilment": { "$ref": "#/components/schemas/group_order.GroupOrderFulfilmentPlan" }, "history": { "items": { "$ref": "#/components/schemas/security.HistoryEntry" }, "type": "array", "uniqueItems": false }, "id": { "type": "string" }, "internal_note": { "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/order.OrderItem" }, "type": "array", "uniqueItems": false }, "manual_discount": { "$ref": "#/components/schemas/quote.CartManualDiscountEvidence", "description": "Pricing's evidence of a cart-level manual discount, frozen from the\naccepted quote. Pricing has already allocated it onto the item price\nsnapshots and tax, so discount_amount and the line amounts include\nit. Present only on a sale that carried one." }, "market_code": { "description": "MarketCode is the immutable commercial market the order was placed\nin. It is captured when the cart is created and never re-derived\nfrom country or currency.", "type": "string" }, "order_number": { "type": "string" }, "outsourced_carrier": { "description": "OutsourcedCarrier names the third-party delivery company; set only\nwhen DeliveryMethod is outsourced.", "type": "string" }, "packed_at": { "type": "string" }, "packing": { "$ref": "#/components/schemas/fulfilment.OrderPackingProgress" }, "packing_revision": { "type": "integer" }, "paid_at": { "type": "string" }, "payment_method": { "$ref": "#/components/schemas/payment_enums.PaymentMethod" }, "payment_status": { "$ref": "#/components/schemas/payment_enums.PaymentStatus" }, "picking_started_at": { "type": "string" }, "point_redemption": { "$ref": "#/components/schemas/order.PointRedemptionSnapshot" }, "promotion_applications": { "items": { "$ref": "#/components/schemas/promotion.PromotionApplication" }, "type": "array", "uniqueItems": false }, "reward_redemptions": { "items": { "$ref": "#/components/schemas/order.RewardRedemptionSnapshot" }, "type": "array", "uniqueItems": false }, "shipped_at": { "type": "string" }, "shipping_amount": { "$ref": "#/components/schemas/money.Money" }, "shipping_method": { "$ref": "#/components/schemas/shipping_enums.ShippingRateName" }, "shipping_packages": { "items": { "$ref": "#/components/schemas/packaging.PhysicalPackage" }, "type": "array", "uniqueItems": false }, "shipping_rate_id": { "type": "string" }, "shipping_zone_id": { "type": "string" }, "source_device": { "$ref": "#/components/schemas/order.SourceDevice" }, "status": { "$ref": "#/components/schemas/order_enums.SalesOrderStatus" }, "subtotal": { "$ref": "#/components/schemas/money.Money" }, "surcharge_amount": { "$ref": "#/components/schemas/money.Money" }, "tags": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "tax_amount": { "$ref": "#/components/schemas/money.Money" }, "tip_amount": { "$ref": "#/components/schemas/money.Money" }, "total": { "$ref": "#/components/schemas/money.Money" }, "tracking_number": { "type": "string" }, "tracking_url": { "type": "string" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } }, "type": "object" }, "order.OrderItem": { "properties": { "allocated_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "captured_at": { "type": "string" }, "components": { "items": { "$ref": "#/components/schemas/fulfilment.PricedPackageComponent" }, "type": "array", "uniqueItems": false }, "discount_amount": { "$ref": "#/components/schemas/money.Money" }, "id": { "type": "string" }, "packed_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "picked_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "preorder": { "$ref": "#/components/schemas/order.PreorderItemState" }, "pricing": { "$ref": "#/components/schemas/buyer.PricingContext" }, "product_image": { "$ref": "#/components/schemas/security.ObjectMedia" }, "product_name": { "type": "string" }, "product_package_option": { "$ref": "#/components/schemas/product.ProductPackageOption" }, "refunded_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "requested_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "returned_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "sku_code": { "description": "SKUCode is the frozen SKU code captured when the line was priced.", "type": "string" }, "substitution_policy": { "$ref": "#/components/schemas/order.LooseSubstitutionPolicySnapshot" }, "substitutions": { "items": { "$ref": "#/components/schemas/fulfilment.PackageSubstitutionSnapshot" }, "type": "array", "uniqueItems": false }, "total": { "$ref": "#/components/schemas/money.Money" }, "total_base_units": { "type": "integer" }, "variant_title": { "type": "string" } }, "required": [ "allocated_composition", "captured_at", "components", "discount_amount", "id", "packed_composition", "picked_composition", "product_name", "product_package_option", "refunded_composition", "requested_composition", "returned_composition", "sku_code", "substitution_policy", "total", "total_base_units" ], "type": "object" }, "order.POSAttribution": { "description": "POS carries first-class in-store attribution when the order originates\nat a point of sale.", "properties": { "depot_code": { "type": "string" }, "event_id": { "type": "string" }, "form_factor": { "type": "string" }, "operator_user_id": { "type": "string" }, "platform": { "type": "string" }, "register_id": { "type": "string" }, "session_id": { "type": "string" }, "terminal_id": { "type": "string" } }, "type": "object" }, "order.PointRedemptionSnapshot": { "properties": { "customer_number": { "type": "string" }, "discount_amount": { "$ref": "#/components/schemas/money.Money" }, "ledger_entry_id": { "type": "string" }, "occurred_at": { "type": "string" }, "points": { "type": "integer" }, "reservation_id": { "type": "string" } }, "type": "object" }, "order.PreorderItemSnapshot": { "properties": { "captured_at": { "type": "string" }, "expected_available_at": { "type": "string" }, "max_quantity_per_customer": { "type": "integer" }, "max_quantity_per_order": { "type": "integer" }, "policy_version": { "type": "string" }, "schedule_timezone": { "type": "string" }, "sku_code": { "type": "string" } }, "required": [ "captured_at", "policy_version", "schedule_timezone", "sku_code" ], "type": "object" }, "order.PreorderItemState": { "properties": { "allocated_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "first_allocated_at": { "type": "string" }, "fully_allocated_at": { "type": "string" }, "requested_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "reservation_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "snapshot": { "$ref": "#/components/schemas/order.PreorderItemSnapshot" }, "status": { "$ref": "#/components/schemas/order_enums.PreorderAllocationStatus" } }, "required": [ "allocated_composition", "requested_composition", "snapshot", "status" ], "type": "object" }, "order.RewardRedemptionSnapshot": { "properties": { "customer_number": { "type": "string" }, "discount_amount": { "$ref": "#/components/schemas/money.Money" }, "occurred_at": { "type": "string" }, "points_spent": { "type": "integer" }, "reward_code": { "type": "string" }, "reward_redemption_id": { "type": "string" }, "reward_type": { "$ref": "#/components/schemas/wallet_enums.RewardType" }, "sku_code": { "type": "string" } }, "type": "object" }, "order.SourceDevice": { "properties": { "browser": { "type": "string" }, "device_key": { "type": "string" }, "ip_address": { "type": "string" }, "local_id": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/metadata.Metadata" }, "name": { "type": "string" }, "os": { "type": "string" }, "pos": { "$ref": "#/components/schemas/order.POSAttribution" }, "type": { "$ref": "#/components/schemas/order_enums.OrderSourceDeviceType" }, "user_agent": { "type": "string" } }, "type": "object" }, "order_enums.FulfillmentReadiness": { "enum": [ "ready", "waiting_for_preorder_stock" ], "type": "string", "x-enum-varnames": [ "FulfillmentReadinessReady", "FulfillmentReadinessWaitingForPreorderStock" ] }, "order_enums.FulfillmentStatus": { "enum": [ "unfulfilled", "picking_in_progress", "packing", "packed", "fulfilled", "cancelled" ], "type": "string", "x-enum-varnames": [ "FulfillmentStatusUnfulfilled", "FulfillmentStatusPickingInProgress", "FulfillmentStatusPacking", "FulfillmentStatusPacked", "FulfillmentStatusFulfilled", "FulfillmentStatusCancelled" ] }, "order_enums.LooseSubstitutionPolicySource": { "enum": [ "CHANNEL_DEFAULT", "BUYER_SELECTED", "GROUP_MANAGER_SELECTED" ], "type": "string", "x-enum-varnames": [ "LooseSubstitutionPolicySourceChannelDefault", "LooseSubstitutionPolicySourceBuyerSelected", "LooseSubstitutionPolicySourceGroupManager" ] }, "order_enums.OrderSourceDeviceType": { "enum": [ "ios", "android", "pc", "mobile_web", "tablet", "pos", "manual", "phone", "vr" ], "type": "string", "x-enum-varnames": [ "OrderSourceDeviceTypeIOS", "OrderSourceDeviceTypeAndroid", "OrderSourceDeviceTypePC", "OrderSourceDeviceTypeMobileWeb", "OrderSourceDeviceTypeTablet", "OrderSourceDeviceTypePos", "OrderSourceDeviceTypeManual", "OrderSourceDeviceTypePhone", "OrderSourceDeviceTypeVR" ] }, "order_enums.PreorderAllocationStatus": { "enum": [ "waiting_for_stock", "partially_allocated", "stock_allocated" ], "type": "string", "x-enum-varnames": [ "PreorderAllocationStatusWaitingForStock", "PreorderAllocationStatusPartiallyAllocated", "PreorderAllocationStatusStockAllocated" ] }, "order_enums.SalesOrderStatus": { "enum": [ "pending", "confirmed", "paid", "processing", "picking", "packed", "shipped", "delivered", "completed", "cancelled", "refunded" ], "type": "string", "x-enum-varnames": [ "SalesOrderStatusPending", "SalesOrderStatusConfirmed", "SalesOrderStatusPaid", "SalesOrderStatusProcessing", "SalesOrderStatusPicking", "SalesOrderStatusPacked", "SalesOrderStatusShipped", "SalesOrderStatusDelivered", "SalesOrderStatusCompleted", "SalesOrderStatusCancelled", "SalesOrderStatusRefunded" ] }, "packaging.PackageComponentSnapshot": { "properties": { "base_units": { "type": "integer" }, "handling_unit": { "$ref": "#/components/schemas/packaging_enums.PackageHandlingUnit" }, "package_count": { "type": "integer" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "units_per_package": { "type": "integer" } }, "required": [ "base_units", "handling_unit", "package_count", "package_option", "units_per_package" ], "type": "object" }, "packaging.PackageCompositionSnapshot": { "properties": { "components": { "items": { "$ref": "#/components/schemas/packaging.PackageComponentSnapshot" }, "type": "array", "uniqueItems": false }, "total_base_units": { "type": "integer" } }, "required": [ "components", "total_base_units" ], "type": "object" }, "packaging.PackageOptionRef": { "additionalProperties": false, "properties": { "code": { "minLength": 1, "type": "string" }, "sku_code": { "minLength": 1, "type": "string" }, "version": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "sku_code", "code", "version" ], "type": "object" }, "packaging.PhysicalPackage": { "properties": { "dimensions": { "$ref": "#/components/schemas/measurement.Dimensions" }, "quantity": { "type": "integer" }, "weight": { "$ref": "#/components/schemas/measurement.Weight" } }, "type": "object" }, "packaging_enums.PackageHandlingUnit": { "enum": [ "EACH", "CASE" ], "type": "string", "x-enum-varnames": [ "PackageHandlingUnitEach", "PackageHandlingUnitCase" ] }, "party.ContactAddress": { "description": "── Shipping \u0026 billing ────────────────────────────────────────────", "properties": { "address": { "$ref": "#/components/schemas/geography.Address" }, "contact": { "$ref": "#/components/schemas/party.Recipient" }, "id": { "description": "ID is populated for persisted address-book entries. Inline checkout,\norder, billing, and fulfilment snapshots may leave it empty.", "type": "string" } }, "type": "object" }, "party.PartyRef": { "properties": { "code": { "description": "Code is the organisation / supplier business key (supplier_code /\norganisation_code) used as the canonical cross-struct reference. It is\nempty for person-like parties (e.g. an order customer) that have no\norganisation code.", "type": "string" }, "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "type": "object" }, "party.Recipient": { "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "name" ], "type": "object" }, "payment.BuyerLegalSnapshot": { "description": "BuyerLegal is required on a tax invoice at or above the market's\nthreshold (AU: one thousand dollars). Below it a tax invoice needs no\nbuyer identity, so none is frozen.", "properties": { "address": { "$ref": "#/components/schemas/geography.Address" }, "business_number": { "type": "string" }, "business_number_scheme": { "$ref": "#/components/schemas/payment_enums.BusinessNumberScheme" }, "business_number_scheme_label": { "type": "string" }, "frozen_at": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "payment.CaptureConfirmationEvidence": { "properties": { "evidence_reference": { "description": "Opaque authenticated provider event or immutable observation reference. Protected source proof remains private.", "type": "string" }, "provider": { "type": "string" }, "source": { "enum": [ "provider_event", "provider_status_observation" ], "type": "string" }, "upper_bound_at": { "format": "date-time", "type": "string" } }, "required": [ "upper_bound_at", "source", "provider", "evidence_reference" ], "type": "object" }, "payment.CaptureTimingEvidence": { "description": "Exact capture time is optional. Confirmation proves capture no later than a conservative bound, conditional on the documented five-second clock allowance. A bound after a deadline is ambiguous, never proof of late capture. Missing evidence stays unknown; paid_at and envelope/processing times are not substitutes.", "properties": { "captured_at": { "format": "date-time", "type": "string" }, "confirmation": { "$ref": "#/components/schemas/payment.CaptureConfirmationEvidence" } }, "type": "object" }, "payment.CustomerPaymentAllocation": { "properties": { "allocation_id": { "type": "string" }, "amount": { "$ref": "#/components/schemas/money.Money" }, "kind": { "$ref": "#/components/schemas/payment_enums.CustomerPaymentAllocationKind" }, "method": { "$ref": "#/components/schemas/payment_enums.PaymentMethod" }, "occurred_at": { "type": "string" }, "points": { "type": "integer" }, "provider": { "type": "string" }, "refunded_amount": { "$ref": "#/components/schemas/money.Money" }, "status": { "type": "string" } }, "required": [ "amount", "kind", "occurred_at" ], "type": "object" }, "payment.CustomerPaymentSummary": { "properties": { "allocations": { "items": { "$ref": "#/components/schemas/payment.CustomerPaymentAllocation" }, "type": "array", "uniqueItems": false }, "captured_total": { "$ref": "#/components/schemas/money.Money" }, "completeness": { "$ref": "#/components/schemas/payment_enums.PaymentCompleteness" }, "missing_components": { "items": { "$ref": "#/components/schemas/payment_enums.PaymentSummaryComponent" }, "type": "array", "uniqueItems": false }, "order_number": { "type": "string" }, "paid_at": { "type": "string" }, "point_debt_remaining": { "description": "Frozen release-time debt receipt, not current wallet debt; absent before release.", "type": "integer" }, "points_applied_to_debt": { "type": "integer" }, "points_award_status": { "$ref": "#/components/schemas/wallet_enums.PointAwardStatus" }, "points_earned": { "description": "Released points; absent while held. Dropped awards report zero.", "type": "integer" }, "points_earned_at": { "type": "string" }, "points_held": { "description": "Frozen unspendable points held until explicit order completion.", "type": "integer" }, "points_ledger_entry_id": { "type": "string" }, "points_net_credited": { "type": "integer" }, "processor_fee": { "$ref": "#/components/schemas/money.Money" }, "provider": { "type": "string" }, "refunded_total": { "$ref": "#/components/schemas/money.Money" }, "status": { "$ref": "#/components/schemas/payment_enums.PaymentStatus" }, "total_paid": { "$ref": "#/components/schemas/money.Money" }, "updated_at": { "type": "string" } }, "required": [ "completeness", "order_number", "status" ], "type": "object" }, "payment.Payment": { "properties": { "amount": { "$ref": "#/components/schemas/money.Money" }, "capture_timing": { "$ref": "#/components/schemas/payment.CaptureTimingEvidence" }, "cashout_amount": { "$ref": "#/components/schemas/money.Money" }, "classification": { "$ref": "#/components/schemas/security_enums.DataClassification" }, "contains_pii": { "type": "boolean" }, "contains_sensitive_pii": { "type": "boolean" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "customer_receipt": { "type": "string" }, "data_owner_id": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "deletion_completed_at": { "type": "string" }, "deletion_requested_at": { "type": "string" }, "history": { "items": { "$ref": "#/components/schemas/security.HistoryEntry" }, "type": "array", "uniqueItems": false }, "id": { "type": "string" }, "legal_hold": { "type": "boolean" }, "merchant_receipt": { "description": "Receipt strings exactly as returned by the terminal. Optional;\nwhen present, the POS is expected to print or store them.", "type": "string" }, "metadata": { "$ref": "#/components/schemas/metadata.Metadata" }, "method": { "$ref": "#/components/schemas/payment_enums.PaymentMethod" }, "moto_amount": { "$ref": "#/components/schemas/money.Money" }, "net_amount": { "$ref": "#/components/schemas/money.Money" }, "order_number": { "type": "string" }, "paid_at": { "type": "string" }, "processor_fee": { "$ref": "#/components/schemas/money.Money" }, "protection_basis": { "$ref": "#/components/schemas/security_enums.DataProtectionBasis" }, "provider": { "type": "string" }, "provider_reference": { "$ref": "#/components/schemas/payment.PaymentReference" }, "recovery_decision": { "$ref": "#/components/schemas/payment_enums.RecoveryDecision" }, "refund_amount": { "$ref": "#/components/schemas/money.Money" }, "refund_reason": { "type": "string" }, "refunded_at": { "type": "string" }, "retention_policy_key": { "type": "string" }, "retention_until": { "type": "string" }, "status": { "$ref": "#/components/schemas/payment_enums.PaymentRecordStatus" }, "surcharge_amount": { "$ref": "#/components/schemas/money.Money" }, "terminal_id": { "description": "Terminal linkage, populated for eftpos / moto / cashout methods.", "type": "string" }, "terminal_transaction_id": { "type": "string" }, "tip_amount": { "$ref": "#/components/schemas/money.Money" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } }, "required": [ "amount", "created_at", "id", "method", "order_number", "status", "updated_at" ], "type": "object" }, "payment.PaymentReference": { "properties": { "bank_transfer": { "$ref": "#/components/schemas/provider.BankTransferPaymentReference" }, "mx51": { "$ref": "#/components/schemas/provider.Mx51PaymentReference" }, "stripe": { "$ref": "#/components/schemas/provider.StripePaymentReference" }, "wallet": { "$ref": "#/components/schemas/provider.WalletPaymentReference" } }, "type": "object" }, "payment_enums.BankTransferConfirmationStatus": { "description": "Both values complete the payment for the full amount due; confirmed_partial flags it for finance follow-up.", "enum": [ "confirmed_full", "confirmed_partial" ], "type": "string", "x-enum-varnames": [ "BankTransferConfirmationStatusConfirmedFull", "BankTransferConfirmationStatusConfirmedPartial" ] }, "payment_enums.BusinessNumberScheme": { "enum": [ "abn", "acn", "nzbn", "uen", "vat", "ein", "other" ], "type": "string", "x-enum-varnames": [ "BusinessNumberSchemeABN", "BusinessNumberSchemeACN", "BusinessNumberSchemeNZBN", "BusinessNumberSchemeUEN", "BusinessNumberSchemeVAT", "BusinessNumberSchemeEIN", "BusinessNumberSchemeOther" ] }, "payment_enums.CustomerPaymentAllocationKind": { "enum": [ "external_payment", "wallet_balance", "wallet_points", "gift_card", "other" ], "type": "string", "x-enum-varnames": [ "CustomerPaymentAllocationKindExternalPayment", "CustomerPaymentAllocationKindWalletBalance", "CustomerPaymentAllocationKindWalletPoints", "CustomerPaymentAllocationKindGiftCard", "CustomerPaymentAllocationKindOther" ] }, "payment_enums.DocumentKind": { "description": "DocumentKind records what this document QUALIFIES as, which is not the\nsame as what it was requested as. \"tax_invoice\" is claimed only when the\nfrozen issuer is registered for the tax and carries the registration\nnumber the document has to print; otherwise it downgrades to \"invoice\"\nrather than asserting a registration no register supports.", "enum": [ "receipt", "tax_invoice", "invoice", "adjustment_note" ], "type": "string", "x-enum-varnames": [ "DocumentKindReceipt", "DocumentKindTaxInvoice", "DocumentKindInvoice", "DocumentKindAdjustmentNote" ] }, "payment_enums.PaymentCompleteness": { "enum": [ "complete", "partial", "unavailable" ], "type": "string", "x-enum-varnames": [ "PaymentCompletenessComplete", "PaymentCompletenessPartial", "PaymentCompletenessUnavailable" ] }, "payment_enums.PaymentMethod": { "enum": [ "card", "cash", "qr", "bank_transfer", "payto", "link", "line_pay", "apple_pay", "google_pay", "ecpay", "manual", "gift_card", "eftpos", "moto", "cashout" ], "type": "string", "x-enum-varnames": [ "PaymentMethodCard", "PaymentMethodCash", "PaymentMethodQR", "PaymentMethodBankTransfer", "PaymentMethodPayTo", "PaymentMethodLink", "PaymentMethodLinePay", "PaymentMethodApplePay", "PaymentMethodGooglePay", "PaymentMethodECPay", "PaymentMethodManual", "PaymentMethodGiftCard", "PaymentMethodEFTPOS", "PaymentMethodMOTO", "PaymentMethodCashout" ] }, "payment_enums.PaymentRecordStatus": { "enum": [ "pending", "processing", "completed", "failed", "cancelled", "refunded", "awaiting_action", "unknown" ], "type": "string", "x-enum-varnames": [ "PaymentRecordStatusPending", "PaymentRecordStatusProcessing", "PaymentRecordStatusCompleted", "PaymentRecordStatusFailed", "PaymentRecordStatusCancelled", "PaymentRecordStatusRefunded", "PaymentRecordStatusAwaitingAction", "PaymentRecordStatusUnknown" ] }, "payment_enums.PaymentStatus": { "enum": [ "unknown", "unpaid", "pending", "paid", "partially_paid", "refunded", "partially_refunded" ], "type": "string", "x-enum-varnames": [ "PaymentStatusUnknown", "PaymentStatusUnpaid", "PaymentStatusPending", "PaymentStatusPaid", "PaymentStatusPartiallyPaid", "PaymentStatusRefunded", "PaymentStatusPartialRefunded" ] }, "payment_enums.PaymentSummaryComponent": { "enum": [ "allocation_history", "payment_totals", "redemption_timestamps", "points_earned" ], "type": "string", "x-enum-varnames": [ "PaymentSummaryComponentAllocationHistory", "PaymentSummaryComponentPaymentTotals", "PaymentSummaryComponentRedemptionTimestamps", "PaymentSummaryComponentPointsEarned" ] }, "payment_enums.RecoveryDecision": { "description": "RecoveryDecision is the merchant's manual answer when the terminal\noutcome stayed unknown after provider status checks.", "enum": [ "pending", "approved", "declined" ], "type": "string", "x-enum-varnames": [ "RecoveryDecisionPending", "RecoveryDecisionApproved", "RecoveryDecisionDeclined" ] }, "payment_enums.TaxRegistrationStatus": { "enum": [ "registered", "not_registered", "unknown" ], "type": "string", "x-enum-varnames": [ "TaxRegistrationStatusRegistered", "TaxRegistrationStatusNotRegistered", "TaxRegistrationStatusUnknown" ] }, "payments.AmendmentFenceReceipt": { "properties": { "buyer_reassignment_allowed": { "description": "Verify the active owner receipt server-side before using this evidence.", "type": "boolean" }, "edit_id": { "type": "string" }, "expected_updated_at": { "format": "date-time", "type": "string" }, "fulfillment_generation": { "format": "int64", "type": "integer" }, "order_number": { "type": "string" }, "receipt_id": { "type": "string" }, "state": { "enum": [ "prepared", "released" ], "type": "string" } }, "required": [ "edit_id", "order_number", "fulfillment_generation", "state" ], "type": "object" }, "payments.AmendmentFenceRequest": { "additionalProperties": false, "properties": { "abort": { "description": "Release only: abort before composition commit, requires exact original owner timestamp.", "type": "boolean" }, "buyer_reassignment": { "description": "Require no historical financial activity or issued invoice; held until release. Existing draft invoices also block reassignment because draft buyer rebuilding is unsupported.", "type": "boolean" }, "edit_id": { "type": "string" }, "expected_updated_at": { "description": "Required for prepare and unchanged-order abort.", "format": "date-time", "type": "string" }, "fulfillment_generation": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "edit_id", "fulfillment_generation" ], "type": "object" }, "payments.CancelPaymentRequest": { "additionalProperties": false, "properties": { "idempotency_key": { "maxLength": 200, "minLength": 1, "type": "string" } }, "required": [ "idempotency_key" ], "type": "object" }, "payments.ExistingPaymentEvidence": { "additionalProperties": false, "description": "A point-in-time Payments observation, not authorization or proof that pending money was captured.", "properties": { "amount": { "$ref": "#/components/schemas/money.Money" }, "charge_id": { "type": "string" }, "fingerprint": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "mx51_reference_id": { "type": "string" }, "mx51_transaction_id": { "type": "string" }, "order_number": { "type": "string" }, "paid_at": { "type": "string" }, "payment_checkout_session_id": { "type": "string" }, "payment_id": { "type": "string" }, "payment_intent_id": { "type": "string" }, "payment_method": { "type": "string" }, "payment_status": { "enum": [ "pending", "processing", "completed" ], "type": "string" }, "payment_updated_at": { "type": "string" }, "provider": { "type": "string" }, "provider_binding": { "$ref": "#/components/schemas/payments.ExistingPaymentSessionEvidence" }, "reference_fingerprint": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "reference_kind": { "enum": [ "none", "stripe", "mx51", "wallet" ], "type": "string" }, "refund_amount": { "oneOf": [ { "$ref": "#/components/schemas/money.Money" }, { "type": "null" } ] }, "refunded_at": { "type": "string" }, "schema": { "const": "payments-existing-payment-evidence/1", "type": "string" }, "terminal_id": { "type": "string" }, "terminal_transaction_id": { "type": "string" }, "wallet_transaction_id": { "type": "string" } }, "required": [ "schema", "order_number", "payment_id", "payment_method", "payment_status", "provider", "amount", "refund_amount", "refunded_at", "payment_intent_id", "charge_id", "payment_checkout_session_id", "terminal_id", "terminal_transaction_id", "reference_kind", "reference_fingerprint", "mx51_transaction_id", "mx51_reference_id", "wallet_transaction_id", "paid_at", "payment_updated_at", "provider_binding", "fingerprint" ], "type": "object" }, "payments.ExistingPaymentSessionEvidence": { "additionalProperties": false, "properties": { "checkout_session_id": { "type": "string" }, "expected_amount": { "$ref": "#/components/schemas/money.Money" }, "kind": { "enum": [ "unverified", "session_unavailable", "matched_session" ], "type": "string" }, "order_total": { "$ref": "#/components/schemas/money.Money" }, "provider_session_id": { "type": "string" }, "session_status": { "type": "string" }, "session_updated_at": { "type": "string" } }, "required": [ "kind", "provider_session_id", "checkout_session_id", "expected_amount", "order_total", "session_status", "session_updated_at" ], "type": "object" }, "payments.Mx51ReferenceInput": { "additionalProperties": false, "properties": { "authorization_code": { "type": "string" }, "merchant_id": { "type": "string" }, "reference_id": { "type": "string" }, "retrieval_reference_number": { "type": "string" }, "settlement_id": { "type": "string" }, "system_trace_audit_number": { "type": "string" }, "terminal_id": { "type": "string" }, "transaction_id": { "minLength": 1, "type": "string" } }, "required": [ "transaction_id" ], "type": "object" }, "payments.NativeFundingSeal": { "additionalProperties": false, "description": "Historical individual capture facts sealed prospectively in the native capture transaction. This is not original gift classification, issuance permission or a permanent uncompensated assertion. Orders owns purchase and accepted-version identity; Pricing owns issuance authority.", "properties": { "capture_evidence_reference": { "description": "Exact retained native authenticated capture evidence reference. Confirmation bounds remain bounds; seal time does not supply captured_at.", "minLength": 1, "type": "string" }, "capture_timing": { "$ref": "#/components/schemas/payment.CaptureTimingEvidence" }, "captured_amount": { "$ref": "#/components/schemas/money.Money", "description": "Positive native individual captured amount, never the aggregate payment.captured event Amount." }, "charge_id": { "minLength": 1, "type": "string" }, "checkout_session_id": { "description": "Exact native optional application checkout identity. The required field is empty when the established provider session has none; no alias is invented.", "type": "string" }, "classification": { "enum": [ "original_capture" ], "type": "string" }, "order_number": { "minLength": 1, "type": "string" }, "payment_id": { "minLength": 1, "type": "string" }, "payment_intent_id": { "minLength": 1, "type": "string" }, "provider": { "enum": [ "STRIPE_ONLINE" ], "type": "string" }, "provider_session_id": { "minLength": 1, "type": "string" }, "schema_version": { "const": 1, "format": "int64", "type": "integer" }, "seal_fingerprint": { "description": "Native versioned digest of the complete immutable seal; a digest alone is not financial or issuance authority.", "minLength": 1, "type": "string" }, "seal_id": { "minLength": 1, "type": "string" }, "sealed_at": { "description": "Immutable native recording time in UTC at BSON millisecond precision, not an exact capture time.", "format": "date-time", "type": "string" } }, "required": [ "schema_version", "seal_id", "seal_fingerprint", "classification", "payment_id", "order_number", "provider", "provider_session_id", "checkout_session_id", "payment_intent_id", "charge_id", "captured_amount", "capture_timing", "capture_evidence_reference", "sealed_at" ], "type": "object" }, "payments.OrderBalance": { "description": "Completed and pending refunds are separate. Completed refund IDs let Orders prove its physical refund projection is current. physical_refund_total includes only completed line amounts matching current Order item IDs; historical generation or amount-only refunds do not reduce current physical demand. Current payable consideration is order total plus frozen cash_rounding_adjustment minus physical_refund_total minus Pricing-owned committed_tender_total; balance/refund due compare that consideration with captured minus completed and pending refunds. Gift cards remain captures.", "properties": { "balance_due": { "$ref": "#/components/schemas/money.Money" }, "captured_total": { "$ref": "#/components/schemas/money.Money" }, "cash_amount_due": { "$ref": "#/components/schemas/money.Money", "description": "Rounded remaining cash collection target; absent if incompatible or authority unavailable." }, "cash_rounding": { "$ref": "#/components/schemas/receipt.CashRoundingSnapshot" }, "cash_rounding_adjustment": { "$ref": "#/components/schemas/money.Money" }, "committed_tender_total": { "$ref": "#/components/schemas/money.Money" }, "completed_refund_ids": { "items": { "type": "string" }, "type": "array" }, "pending_refund_total": { "$ref": "#/components/schemas/money.Money" }, "physical_refund_total": { "$ref": "#/components/schemas/money.Money" }, "refund_due": { "$ref": "#/components/schemas/money.Money" }, "refunded_total": { "$ref": "#/components/schemas/money.Money" }, "status": { "type": "string" } }, "required": [ "cash_rounding_adjustment", "captured_total", "refunded_total", "pending_refund_total", "balance_due", "refund_due", "committed_tender_total", "physical_refund_total", "status", "completed_refund_ids" ], "type": "object" }, "payments.POSReceiptEnsureResponse": { "properties": { "data": { "$ref": "#/components/schemas/payments.POSReceiptEnsureResult" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "payments.POSReceiptEnsureResult": { "properties": { "created": { "description": "true when this call issued the receipt; false when it already existed and nothing was written.", "type": "boolean" }, "order_number": { "type": "string" } }, "required": [ "order_number", "created" ], "type": "object" }, "payments.PayToSettings": { "properties": { "enabled": { "type": "boolean" }, "reason": { "description": "Why the switch was last changed. Absent until the first change.", "type": "string" }, "updated_at": { "description": "When the switch last changed. Absent until the first change.", "format": "date-time", "type": "string" }, "updated_by": { "description": "Staff member who last changed the switch. Absent until the first change.", "type": "string" } }, "required": [ "enabled" ], "type": "object" }, "payments.PayToSettingsInput": { "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "reason": { "maxLength": 500, "minLength": 1, "type": "string" } }, "required": [ "enabled", "reason" ], "type": "object" }, "payments.PaymentRequest": { "description": "Durable amendment-bound collection. Original captures remain immutable. Unknown provider outcomes retain the shared financial fence. Paid requires canonical recorded capture; provider-only success is processing. Cancellation and supersession keep the fence until confirmed, including late-capture refund completion. Request keys are permanent and changed payloads conflict.", "properties": { "accepted_quote": { "properties": { "quote_key": { "type": "string" }, "quote_revision": { "type": "string" }, "version_id": { "type": "string" } }, "required": [ "version_id", "quote_key", "quote_revision" ], "type": "object" }, "amount": { "$ref": "#/components/schemas/money.Money" }, "committed_order_updated_at": { "format": "date-time", "type": "string" }, "edit_id": { "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "fulfillment_generation": { "format": "int64", "type": "integer" }, "hosted_url": { "format": "uri", "type": "string" }, "order_number": { "type": "string" }, "payment_id": { "type": "string" }, "payment_option": { "enum": [ "card", "link" ], "type": "string" }, "provider_session_id": { "type": "string" }, "request_id": { "type": "string" }, "state": { "enum": [ "creating", "open", "processing", "cancellation_pending", "paid", "settled", "canceled", "expired", "superseded" ], "type": "string" } }, "required": [ "request_id", "order_number", "edit_id", "fulfillment_generation", "committed_order_updated_at", "state", "amount", "payment_option" ], "type": "object" }, "payments.PaymentRequestInput": { "additionalProperties": false, "properties": { "edit_id": { "type": "string" }, "fulfillment_generation": { "format": "int64", "minimum": 0, "type": "integer" }, "idempotency_key": { "maxLength": 200, "minLength": 1, "type": "string" }, "payment_option": { "enum": [ "card", "link" ], "type": "string" }, "return_target": { "enum": [ "retail_web", "wholesale_web", "ios", "android" ], "type": "string" } }, "required": [ "edit_id", "fulfillment_generation", "idempotency_key", "payment_option", "return_target" ], "type": "object" }, "payments.ReconcileOrderEdit": { "additionalProperties": false, "properties": { "edit_id": { "type": "string" }, "fulfillment_generation": { "format": "int64", "type": "integer" }, "revised_total": { "$ref": "#/components/schemas/money.Money" } }, "required": [ "edit_id", "fulfillment_generation", "revised_total" ], "type": "object" }, "payments.RecordBankTransferInput": { "additionalProperties": false, "properties": { "confirmation_status": { "$ref": "#/components/schemas/payment_enums.BankTransferConfirmationStatus" }, "customer": { "$ref": "#/components/schemas/provider.BankTransferCustomer" }, "evidence_codes": { "description": "Finalized evidence codes for this order, not attached to another payment.", "items": { "minLength": 1, "type": "string" }, "maxItems": 5, "minItems": 1, "type": "array", "uniqueItems": true }, "idempotency_key": { "maxLength": 200, "minLength": 1, "type": "string" }, "order_number": { "minLength": 1, "type": "string" }, "payer_reference": { "maxLength": 140, "type": "string" }, "transfer_amount": { "$ref": "#/components/schemas/money.Money", "description": "Must equal the order's remaining amount due exactly." } }, "required": [ "order_number", "transfer_amount", "confirmation_status", "evidence_codes", "idempotency_key" ], "type": "object" }, "payments.RecordEFTPOSInput": { "additionalProperties": false, "properties": { "amount": { "$ref": "#/components/schemas/money.Money", "description": "Positive total received in the order currency; cashout is a separate withdrawal. POS tills accept neither tips nor card surcharges." }, "cashout_minor": { "format": "int64", "type": "integer" }, "customer_receipt": { "type": "string" }, "idempotency_key": { "description": "Optional globally unique retry key. Provider plus terminal transaction identity also prevents duplicate recording. A retry with changed provider, order, method, amount, components or transaction identity conflicts.", "type": "string" }, "merchant_receipt": { "type": "string" }, "method": { "default": "eftpos", "enum": [ "eftpos", "moto", "cashout" ], "type": "string" }, "mx51": { "$ref": "#/components/schemas/payments.Mx51ReferenceInput", "description": "Terminal reference fields for either provider. The property name remains mx51 for wire compatibility." }, "order_number": { "minLength": 1, "type": "string" }, "provider": { "default": "linkly", "description": "Terminal provider selector. Omitted or empty uses Linkly (LINKLY_POS); mx51 records MX51_POS. Both retain the mx51 reference object.", "enum": [ "", "linkly", "mx51" ], "type": "string" }, "surcharge_minor": { "description": "Must be omitted or zero. A non-zero card surcharge is refused with VALIDATION and details.reason surcharge_not_accepted.", "format": "int64", "type": "integer" }, "terminal_transaction_id": { "type": "string" }, "tip_minor": { "description": "Must be omitted or zero. A non-zero tip is refused with VALIDATION and details.reason tip_not_accepted.", "format": "int64", "type": "integer" } }, "required": [ "order_number", "amount", "mx51" ], "type": "object" }, "payments.RecordManualInput": { "additionalProperties": false, "properties": { "amount": { "$ref": "#/components/schemas/money.Money", "description": "Positive captured amount in the order currency, subject to the remaining payable balance and configured cash rounding." }, "idempotency_key": { "minLength": 1, "type": "string" }, "method": { "enum": [ "cash", "bank_transfer", "manual" ], "type": "string" }, "order_number": { "minLength": 1, "type": "string" }, "reference": { "type": "string" } }, "required": [ "order_number", "method", "amount", "idempotency_key" ], "type": "object" }, "payments.RecoveryLookupInput": { "additionalProperties": false, "properties": { "idempotency_key": { "maxLength": 256, "minLength": 1, "type": "string" }, "order_number": { "maxLength": 128, "minLength": 1, "type": "string" } }, "required": [ "order_number", "idempotency_key" ], "type": "object" }, "payments.RecoveryLookupResponse": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/payments.RecoveryLookupResult" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "payments.RecoveryLookupResult": { "additionalProperties": false, "properties": { "idempotency_key": { "minLength": 1, "type": "string" }, "order_number": { "minLength": 1, "type": "string" }, "payment_id": { "minLength": 1, "type": "string" } }, "required": [ "payment_id", "order_number", "idempotency_key" ], "type": "object" }, "payments.UnpaidCancellationResponse": { "properties": { "data": { "$ref": "#/components/schemas/payments.UnpaidCancellationResult" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "payments.UnpaidCancellationResult": { "properties": { "captured_amount": { "$ref": "#/components/schemas/money.Money" }, "order_number": { "type": "string" }, "status": { "enum": [ "cancelled" ], "type": "string" } }, "required": [ "order_number", "status", "captured_amount" ], "type": "object" }, "payments.resolvePaymentRequest": { "additionalProperties": false, "properties": { "evidence_ref": { "description": "Reference to the evidence relied on, such as a terminal log or shift note (trimmed).", "maxLength": 500, "minLength": 1, "type": "string" }, "expected_updated_at": { "description": "The record's updated_at as last read. A changed record answers 409.", "format": "date-time", "type": "string" }, "outcome": { "description": "Final status for the record.", "enum": [ "failed", "cancelled" ], "type": "string" }, "reason": { "description": "Why staff are finalizing the record (trimmed).", "maxLength": 500, "minLength": 1, "type": "string" } }, "required": [ "outcome", "reason", "evidence_ref", "expected_updated_at" ], "type": "object" }, "paymentstatistics.CurrencyTotal": { "additionalProperties": false, "properties": { "captured_minor": { "format": "int64", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "currency": { "pattern": "^[A-Z]{3}$", "type": "string" }, "net_minor": { "format": "int64", "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "refunded_minor": { "format": "int64", "maximum": 9007199254740991, "minimum": 0, "type": "integer" } }, "required": [ "currency", "captured_minor", "refunded_minor", "net_minor" ], "type": "object" }, "paymentstatistics.Request": { "additionalProperties": false, "properties": { "order_numbers": { "description": "Exact canonical order identities. Each must be valid UTF-8, nonblank, at most 128 UTF-8 bytes, with no whitespace or control characters.", "items": { "maxLength": 128, "minLength": 1, "type": "string" }, "maxItems": 5000, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "order_numbers" ], "type": "object" }, "paymentstatistics.Response": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/paymentstatistics.Summary" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "paymentstatistics.Summary": { "additionalProperties": false, "properties": { "order_count": { "description": "Number of accepted distinct input orders including orders with no payment records.", "format": "int64", "maximum": 5000, "minimum": 1, "type": "integer" }, "totals": { "description": "Sorted by currency. Empty for wholly unpaid orders; fully refunded captures retain a zero-net currency entry. Net equals captured minus completed refunds. Currencies are never converted.", "items": { "$ref": "#/components/schemas/paymentstatistics.CurrencyTotal" }, "type": "array" } }, "required": [ "order_count", "totals" ], "type": "object" }, "posTerminalRefundOutcomeInput": { "additionalProperties": false, "properties": { "amount": { "$ref": "#/components/schemas/money.Money" }, "approval_generation": { "description": "Exact approved request generation; zero is the first generation.", "minimum": 0, "type": "integer" }, "authorization_code": { "maxLength": 128, "type": "string" }, "customer_receipt": { "maxLength": 8192, "type": "string" }, "financial_status": { "enum": [ "approved", "declined", "cancelled" ], "type": "string" }, "merchant_id": { "maxLength": 128, "type": "string" }, "merchant_receipt": { "maxLength": 8192, "type": "string" }, "message": { "maxLength": 256, "type": "string" }, "order_number": { "maxLength": 256, "minLength": 1, "type": "string" }, "payment_id": { "maxLength": 128, "minLength": 1, "type": "string" }, "provider": { "default": "linkly", "description": "Omitted or empty selects Linkly. Must match the prepared refund and captured payment provider (LINKLY_POS or MX51_POS).", "enum": [ "", "linkly", "mx51" ], "type": "string" }, "provider_terminal_id": { "maxLength": 128, "type": "string" }, "provider_transaction_id": { "maxLength": 128, "type": "string" }, "refund_request_id": { "description": "Approved refund request identity. Must be supplied with its approval generation and the exact frozen external amount/payment. Omit for a direct refund.", "maxLength": 128, "type": "string" }, "register_id": { "description": "Required for request-backed attached execution; must own the open session.", "type": "string" }, "retrieval_reference_number": { "maxLength": 128, "type": "string" }, "session_id": { "description": "Required for request-backed attached execution. Remains held until a definitive outcome is durably recorded.", "type": "string" }, "system_trace_audit_number": { "maxLength": 128, "type": "string" }, "terminal_id": { "maxLength": 128, "minLength": 1, "type": "string" }, "transaction_id": { "maxLength": 128, "minLength": 1, "type": "string" } }, "required": [ "transaction_id", "terminal_id", "order_number", "payment_id", "amount", "financial_status" ], "type": "object" }, "posTerminalRefundPrepareInput": { "additionalProperties": false, "properties": { "amount": { "$ref": "#/components/schemas/money.Money" }, "approval_generation": { "description": "Exact approved request generation; zero is the first generation.", "minimum": 0, "type": "integer" }, "order_number": { "maxLength": 256, "minLength": 1, "type": "string" }, "payment_id": { "maxLength": 128, "minLength": 1, "type": "string" }, "provider": { "default": "linkly", "description": "Omitted or empty selects Linkly. The resolved provider (LINKLY_POS or MX51_POS) must match the captured payment and remains bound through outcomes and recovery.", "enum": [ "", "linkly", "mx51" ], "type": "string" }, "refund_request_id": { "description": "Approved refund request identity. Must be supplied with its approval generation and the exact frozen external amount/payment. Omit for a direct refund.", "maxLength": 128, "type": "string" }, "register_id": { "description": "Required for request-backed attached execution; must own the open session.", "type": "string" }, "session_id": { "description": "Required for request-backed attached execution. Remains held until a definitive outcome is durably recorded.", "type": "string" }, "terminal_id": { "maxLength": 128, "minLength": 1, "type": "string" }, "transaction_id": { "maxLength": 128, "minLength": 1, "type": "string" } }, "required": [ "transaction_id", "terminal_id", "order_number", "payment_id", "amount" ], "type": "object" }, "posregisters.archiveRegisterReq": { "additionalProperties": false, "properties": { "reason": { "description": "Optional free-text reason (at most 500 characters, trimmed).", "maxLength": 500, "type": "string" } }, "type": "object" }, "posregisters.cashMovementReq": { "properties": { "amount": { "$ref": "#/components/schemas/money.Money", "description": "Cash movement amount_minor must be strictly positive." }, "kind": { "$ref": "#/components/schemas/register_enums.CashMovementKind" }, "reason": { "type": "string" } }, "required": [ "kind", "amount" ], "type": "object" }, "posregisters.closeSessionReq": { "description": "The request body may be omitted. An omitted closing_count uses zero amount with empty currency.", "properties": { "closing_count": { "$ref": "#/components/schemas/money.Money" } }, "type": "object" }, "posregisters.openSessionReq": { "properties": { "business_date": { "description": "YYYY-MM-DD; omitted or empty uses the current Melbourne (Australia/Melbourne) date.", "type": "string" }, "opening_float": { "$ref": "#/components/schemas/money.Money", "description": "Opening cash count. Omission uses zero amount with empty currency." } }, "type": "object" }, "posterminals.AssignmentConflictDetails": { "additionalProperties": false, "description": "register_id, connection_id and retired describe an occupying connection for register_provider_occupied and appear only when the caller's geographic scope covers it.", "properties": { "connection_id": { "description": "The occupying connection.", "type": "string" }, "reason": { "description": "transaction_active means the connection holds an active financial transaction, a reprint or pairing lease, or a terminal transaction that is not completed. stale_revision means expected_revision is not the current revision; re-read and retry. register_mismatch means the request's register_id does not hold (or did not release) the connection. not_released means only a released connection can be claimed without takeover. owner_session_open means a takeover claim was refused because the register holding the connection has an open session. depot_mismatch means the claiming register is in another depot, market or country. register_provider_occupied means the claiming register already has a connection for this provider. reader_busy means the Stripe reader has an action in progress. connection_released means the connection must be claimed before it can transact, be reassigned, updated or paired. connection_shared means the connection is a shared reader, which no register holds, so it cannot be claimed, released, taken over or reassigned. sandbox_retired means the connection is a retired sandbox connection. invalid_connection_request means a blank register_id or a non-positive expected_revision reached the service.", "enum": [ "connection_shared", "transaction_active", "stale_revision", "register_mismatch", "not_released", "depot_mismatch", "register_provider_occupied", "reader_busy", "connection_released", "sandbox_retired", "invalid_connection_request", "owner_session_open" ], "type": "string" }, "register_id": { "description": "Register holding the occupying connection.", "type": "string" }, "retired": { "description": "Present when the occupying connection is a retired sandbox connection.", "enum": [ "true" ], "type": "string" } }, "required": [ "reason" ], "type": "object" }, "posterminals.AssignmentConflictResponse": { "description": "409 envelope for terminal-connection release and claim, and for transacting, reassigning, updating or pairing a released connection. code and message are unchanged for every cause; error.details.reason names it.", "properties": { "error": { "properties": { "code": { "const": "CONFLICT", "type": "string" }, "details": { "$ref": "#/components/schemas/posterminals.AssignmentConflictDetails" }, "message": { "example": "terminal identity, authority or occupancy conflicts", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" }, "posterminals.AssignmentInput": { "additionalProperties": false, "properties": { "expected_revision": { "description": "The connection revision the till last read.", "format": "int64", "minimum": 1, "type": "integer" }, "register_id": { "description": "Release: the register that holds the connection. Claim: the register taking it.", "minLength": 1, "type": "string" }, "takeover": { "default": false, "description": "Claim only; a release with takeover true is a 400 VALIDATION_ERROR. When true, the claim may also take a connection still assigned to another register in the same depot, provided that register has no open session, the connection holds no active or unresolved transaction, reprint or pairing lease, and a Stripe reader has no action in progress. Without it only a released connection can be claimed.", "type": "boolean" } }, "required": [ "register_id", "expected_revision" ], "type": "object" }, "posterminals.Connection": { "additionalProperties": false, "properties": { "active_transaction_id": { "description": "The transaction holding the connection. On a shared reader it is shown only to the register whose sale holds the reader (the register_id of the request) and omitted for every other register.", "type": "string" }, "assignment": { "description": "released after POST /pos/terminal-connections/{id}/release until a register in the same depot claims it; a released connection accepts no transactions. A shared reader reports assigned; tell it apart by shared true.", "enum": [ "assigned", "released" ], "type": "string" }, "connection_id": { "type": "string" }, "enabled": { "type": "boolean" }, "label": { "type": "string" }, "location_id": { "type": "string" }, "owner_register_id": { "description": "Only in GET /pos/terminal-connections/available, for an assigned connection that may be claimed with takeover. The register that holds it (equal to register_id).", "type": "string" }, "provider": { "enum": [ "stripe_terminal", "linkly_cloud" ], "type": "string" }, "reader_id": { "type": "string" }, "reader_state": { "allOf": [ { "$ref": "#/components/schemas/posterminals.ReaderState" } ], "description": "Present only on a shared reader. The reader state evaluated when the response was built; poll GET /pos/terminal-connections/{id}/state for a state whose deadlines have been applied and stored." }, "readiness": { "enum": [ "ready", "offline", "busy", "unavailable" ], "type": "string" }, "register_id": { "description": "Register holding the connection. Omitted while the connection is released and for a shared reader, which no register holds.", "type": "string" }, "released_at": { "description": "Present only while released.", "format": "date-time", "type": "string" }, "released_by": { "description": "User id that released the connection; present only while released.", "type": "string" }, "released_from_register_id": { "description": "Register that released the connection; present only while released.", "type": "string" }, "revision": { "format": "int64", "type": "integer" }, "sandbox_retirement": { "$ref": "#/components/schemas/posterminals.SandboxRetirement" }, "shared": { "default": false, "description": "true for a shared reader (stripe_terminal or linkly_cloud): every\nregister in the connection's depot, market and country may use it,\nfirst come first served, without claiming it. Set with\nPATCH /pos/terminal-connections/{id}. A shared reader cannot be\nclaimed, released, taken over or reassigned (409 connection_shared),\nand a register session close never releases it; the closing\nregister only leaves its queue and gives up its turn or hold.\n", "type": "boolean" }, "takeover_eligible": { "description": "Only in GET /pos/terminal-connections/available. false for a released connection (claim it without takeover); true for an assigned connection of another register that may be claimed with takeover true.", "type": "boolean" } }, "required": [ "connection_id", "assignment", "shared", "provider", "reader_id", "label", "enabled", "revision", "readiness" ], "type": "object" }, "posterminals.ConnectionConflictDetails": { "additionalProperties": false, "description": "Absent only when a storage conflict cannot be attributed. register_id, connection_id and retired describe the occupying connection and appear only when the caller's geographic scope covers it.", "properties": { "connection_id": { "description": "The occupying connection.", "type": "string" }, "reason": { "description": "stripe_terminal_disabled and linkly_cloud_disabled mean the requested provider is not configured on this service. reader_busy means the Stripe reader has an action in progress. reader_already_assigned means another connection holds this provider reader. register_provider_occupied means the register already has a connection for this provider. invalid_connection_request means an unsupported provider, a blank or over-120-character label, or a reader_id sent for linkly_cloud.", "enum": [ "stripe_terminal_disabled", "linkly_cloud_disabled", "reader_busy", "reader_already_assigned", "register_provider_occupied", "invalid_connection_request" ], "type": "string" }, "register_id": { "description": "Register holding the occupying connection; equal to the request's register_id when it is this register's own connection.", "type": "string" }, "retired": { "description": "Present when the occupying connection is a retired sandbox connection.", "enum": [ "true" ], "type": "string" } }, "required": [ "reason" ], "type": "object" }, "posterminals.ConnectionConflictResponse": { "description": "409 envelope for createPOSTerminalConnection. code and message are unchanged for every cause; error.details.reason names it.", "properties": { "error": { "properties": { "code": { "const": "CONFLICT", "type": "string" }, "details": { "$ref": "#/components/schemas/posterminals.ConnectionConflictDetails" }, "message": { "example": "terminal identity, authority or occupancy conflicts", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" }, "posterminals.ConnectionInput": { "additionalProperties": false, "properties": { "label": { "type": "string" }, "provider": { "enum": [ "stripe_terminal", "linkly_cloud" ], "type": "string" }, "reader_id": { "type": "string" }, "register_id": { "type": "string" } }, "required": [ "register_id", "provider", "label" ], "type": "object" }, "posterminals.ConnectionPatch": { "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "expected_revision": { "format": "int64", "type": "integer" }, "label": { "type": "string" }, "reader_id": { "type": "string" }, "shared": { "description": "Turns the connection into a shared reader (true) or back (false);\nomitted or unchanged leaves sharing as is. Turning it on needs an\nidle connection with no active or unresolved transaction or lease\n(transaction_active) and also works on a released connection; the\nconnection gives up its register and reader_state starts free with\nan empty queue. Turning it off needs a free reader with an empty\nqueue (reader_busy, reader_held, reader_queue_not_empty) and leaves\nthe connection released, claimable as before. Other fields in the\nsame body are applied in the same write. The audit records the\nauthenticated actor.\n", "type": "boolean" } }, "required": [ "expected_revision" ], "type": "object" }, "posterminals.ConnectionResponse": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/posterminals.Connection" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "posterminals.ConnectionsResponse": { "additionalProperties": false, "properties": { "data": { "items": { "$ref": "#/components/schemas/posterminals.Connection" }, "type": "array" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "posterminals.PairingInput": { "additionalProperties": false, "properties": { "pair_code": { "maxLength": 64, "minLength": 1, "type": "string", "writeOnly": true }, "password": { "maxLength": 256, "minLength": 1, "type": "string", "writeOnly": true }, "username": { "maxLength": 200, "minLength": 1, "type": "string", "writeOnly": true } }, "required": [ "username", "password", "pair_code" ], "type": "object" }, "posterminals.ProgressEvent": { "additionalProperties": false, "properties": { "sequence": { "format": "int64", "type": "integer" }, "transaction": { "$ref": "#/components/schemas/posterminals.Transaction" } }, "required": [ "sequence", "transaction" ], "type": "object" }, "posterminals.ReaderQueueEntry": { "additionalProperties": false, "properties": { "joined_at": { "format": "date-time", "type": "string" }, "register_id": { "type": "string" } }, "required": [ "register_id", "joined_at" ], "type": "object" }, "posterminals.ReaderQueueJoin": { "additionalProperties": false, "properties": { "register_id": { "maxLength": 128, "minLength": 1, "type": "string" }, "session_id": { "description": "An open session of register_id.", "maxLength": 128, "minLength": 1, "type": "string" } }, "required": [ "register_id", "session_id" ], "type": "object" }, "posterminals.ReaderQueueLeave": { "additionalProperties": false, "properties": { "register_id": { "maxLength": 128, "minLength": 1, "type": "string" } }, "required": [ "register_id" ], "type": "object" }, "posterminals.ReaderState": { "additionalProperties": false, "description": "State of a shared reader. busy: a transaction, a reprint or pairing\nlease, or a Linkly transaction awaiting recovery holds the reader; the\nqueue waits. A Stripe sale declined at the reader or in\nrecovery_required releases the reader at once, so it never blocks other\nregisters; a retry must take the reader again under the start rules.\nholding: the last attempt, by holder_register_id for\nhold_order_number, completed declined or cancelled (or, on Stripe, was\ndeclined and awaits the operator); until hold_until\n(5 seconds) only that register may start, and only for that order.\nturn: the reader is free and turn_register_id, the queue head, may\nstart until turn_until (10 seconds); an unused turn passes to the next\nqueued register with a fresh 10 seconds, and an empty queue frees the\nreader. free: any register of the depot may start. An approved\ntransaction frees the reader at once. Waiting in the queue has no time\nlimit. The service runs no timers: every deadline is applied when the\nstate is read or changed (this state route, the queue routes,\ntransaction start and GET, the transaction event stream, recovery).\n", "properties": { "active_transaction_id": { "description": "The financial transaction holding a busy reader, shown only to the register whose sale it is (the register_id of the request). Omitted for every other register and for a reprint or pairing lease.", "type": "string" }, "hold_order_number": { "description": "Present while holding; the only order the holder may start.", "type": "string" }, "hold_until": { "description": "Present while holding.", "format": "date-time", "type": "string" }, "holder_register_id": { "description": "Present while holding.", "type": "string" }, "queue": { "description": "Registers waiting, in join order; joined_at never decreases along the queue (a join that commits after a concurrent one takes at least its predecessor's joined_at). Starting a transaction removes the starting register.", "items": { "$ref": "#/components/schemas/posterminals.ReaderQueueEntry" }, "type": "array" }, "status": { "enum": [ "free", "busy", "holding", "turn" ], "type": "string" }, "turn_register_id": { "description": "Present during a turn; always the queue head.", "type": "string" }, "turn_until": { "description": "Present during a turn.", "format": "date-time", "type": "string" } }, "required": [ "status", "queue" ], "type": "object" }, "posterminals.ReaderStateResponse": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/posterminals.ReaderState" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "posterminals.ReassignmentInput": { "additionalProperties": false, "properties": { "expected_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "register_id": { "minLength": 1, "type": "string" } }, "required": [ "register_id", "expected_revision" ], "type": "object" }, "posterminals.Receipt": { "additionalProperties": false, "properties": { "lines": { "items": { "type": "string" }, "type": "array" }, "receipt_id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "receipt_id", "type", "lines" ], "type": "object" }, "posterminals.ResponseInput": { "additionalProperties": false, "properties": { "action": { "enum": [ "retry", "accept", "decline", "ok", "authorise", "cancel" ], "type": "string" }, "expected_revision": { "format": "int64", "type": "integer" } }, "required": [ "action", "expected_revision" ], "type": "object" }, "posterminals.SandboxRetirement": { "additionalProperties": false, "description": "Administrative sandbox retirement; never proof of financial completion or cancellation.", "properties": { "actor": { "maxLength": 240, "minLength": 1, "type": "string" }, "environment": { "enum": [ "sandbox" ], "type": "string" }, "evidence_sha256": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "financial_outcome": { "enum": [ "unknown" ], "type": "string" }, "reason": { "maxLength": 240, "minLength": 1, "type": "string" }, "retired_at": { "format": "date-time", "type": "string" }, "retirement_id": { "format": "uuid", "type": "string" } }, "required": [ "retirement_id", "retired_at", "actor", "reason", "environment", "financial_outcome", "evidence_sha256" ], "type": "object" }, "posterminals.SharedReaderConflictDetails": { "additionalProperties": false, "properties": { "reason": { "description": "reader_busy: the shared reader runs a transaction, a utility lease or\na transaction awaiting recovery (start), or is busy (sharing off).\nreader_held: the reader holds for another register, or for this\nregister but another order. reader_turn_not_yours: another queued\nregister has the turn. A start refused for one of these three\nrecords no attempt, so the same transaction_id may be retried.\nconnection_not_shared: the state or queue route named a connection\nthat is not shared. depot_mismatch: the register is in another\ndepot, market or country than the reader. session_not_open: joining\nneeds an open session of the register. reader_queue_not_empty:\nsharing cannot be turned off while registers wait or have the turn.\ntransaction_active: sharing cannot be turned on while the\nconnection holds an active or unresolved transaction or a lease.\nstale_revision: expected_revision is not the current revision.\nsandbox_retired: the connection is a retired sandbox connection.\ninvalid_connection_request: a malformed identifier reached the\nservice, a session of another register, or a sharing change\nwithout an authenticated actor.\n", "enum": [ "reader_busy", "reader_held", "reader_turn_not_yours", "connection_not_shared", "depot_mismatch", "session_not_open", "reader_queue_not_empty", "transaction_active", "stale_revision", "sandbox_retired", "invalid_connection_request" ], "type": "string" } }, "required": [ "reason" ], "type": "object" }, "posterminals.SharedReaderConflictResponse": { "description": "409 envelope for shared reader refusals (transaction start, reader state and queue routes, and a PATCH that changes shared). code and message are unchanged for every cause; error.details.reason names it.", "properties": { "error": { "properties": { "code": { "const": "CONFLICT", "type": "string" }, "details": { "$ref": "#/components/schemas/posterminals.SharedReaderConflictDetails" }, "message": { "example": "terminal identity, authority or occupancy conflicts", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "success": { "const": false, "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" }, "posterminals.StartInput": { "additionalProperties": false, "properties": { "approval_generation": { "description": "Exact approved request generation; zero is the first generation.", "minimum": 0, "type": "integer" }, "connection_id": { "type": "string" }, "idempotency_key": { "type": "string" }, "kind": { "enum": [ "purchase", "refund" ], "type": "string" }, "order_number": { "type": "string" }, "payment_id": { "type": "string" }, "refund_amount": { "additionalProperties": false, "properties": { "amount_minor": { "format": "int64", "type": "integer" }, "currency": { "type": "string" } }, "required": [ "amount_minor", "currency" ], "type": "object" }, "refund_request_id": { "description": "Approved refund request identity. Must be supplied with its approval generation and the exact frozen external amount/payment. Omit for a direct refund.", "maxLength": 128, "type": "string" }, "register_id": { "type": "string" }, "session_id": { "type": "string" }, "transaction_id": { "type": "string" } }, "required": [ "transaction_id", "idempotency_key", "kind", "register_id", "session_id", "connection_id", "order_number" ], "type": "object" }, "posterminals.Transaction": { "additionalProperties": false, "properties": { "amount": { "additionalProperties": false, "properties": { "amount_minor": { "format": "int64", "type": "integer" }, "currency": { "type": "string" } }, "required": [ "amount_minor", "currency" ], "type": "object" }, "approval_generation": { "description": "Exact approved request generation; zero is the first generation.", "minimum": 0, "type": "integer" }, "can_cancel": { "type": "boolean" }, "can_retry": { "type": "boolean" }, "card_wait_until": { "description": "Shared-reader purchases only: thirty seconds after the reader\naccepted the dispatch. When it passes while the purchase still waits\nat the reader (not completed, reconciling, awaiting_action or\nrecovery_required), the service cancels it through the same path as\nPOST /pos/terminal-transactions/{id}/cancel. A card already being\nprocessed that can no longer be cancelled finishes and its real\noutcome stands. A Linkly purchase is only cancelled while the\nterminal offers its cancel key. Cleared by a retry.\n", "format": "date-time", "type": "string" }, "connection_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "error_code": { "type": "string" }, "event_sequence": { "format": "int64", "type": "integer" }, "idempotency_key": { "type": "string" }, "kind": { "enum": [ "purchase", "refund" ], "type": "string" }, "operator_actions": { "items": { "enum": [ "accept", "decline", "ok", "authorise" ], "type": "string" }, "type": "array" }, "order_number": { "type": "string" }, "original_payment_id": { "type": "string" }, "outcome": { "enum": [ "pending", "approved", "declined", "cancelled", "unknown" ], "type": "string" }, "payment_id": { "type": "string" }, "phase": { "enum": [ "created", "dispatching", "processing", "awaiting_action", "reconciling", "completed", "recovery_required" ], "type": "string" }, "prompt": { "type": "string" }, "provider": { "enum": [ "stripe_terminal", "linkly_cloud" ], "type": "string" }, "provider_session_id": { "format": "uuid", "type": "string" }, "receipts": { "items": { "$ref": "#/components/schemas/posterminals.Receipt" }, "type": "array" }, "refund_id": { "type": "string" }, "refund_request_id": { "description": "Approved refund request identity. Must be supplied with its approval generation and the exact frozen external amount/payment. Omit for a direct refund.", "maxLength": 128, "type": "string" }, "register_id": { "type": "string" }, "revision": { "format": "int64", "type": "integer" }, "sandbox_retirement": { "$ref": "#/components/schemas/posterminals.SandboxRetirement" }, "session_id": { "type": "string" }, "transaction_id": { "type": "string" }, "transaction_reference": { "maxLength": 16, "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "transaction_id", "idempotency_key", "register_id", "session_id", "connection_id", "order_number", "kind", "provider", "amount", "phase", "outcome", "revision", "event_sequence", "can_cancel", "can_retry", "created_at", "updated_at" ], "type": "object" }, "posterminals.TransactionResponse": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/posterminals.Transaction" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "pricebook_enums.PriceEndingPolicy": { "enum": [ "none", "charm_nine" ], "type": "string", "x-enum-varnames": [ "PriceEndingPolicyNone", "PriceEndingPolicyCharmNine" ] }, "pricebook_enums.PriceTaxInclusion": { "enum": [ "tax_inclusive", "tax_exclusive" ], "type": "string", "x-enum-varnames": [ "PriceTaxInclusionInclusive", "PriceTaxInclusionExclusive" ] }, "pricing.TierRefundPreparedResult": { "additionalProperties": false, "properties": { "batch_id": { "minLength": 1, "type": "string" }, "order_number": { "minLength": 1, "type": "string" }, "proof": { "$ref": "#/components/schemas/refunds.TierBatchPreparedProof" }, "refund_id": { "minLength": 1, "type": "string" }, "request_fingerprint": { "minLength": 1, "type": "string" }, "schema_version": { "const": 1, "type": "integer" }, "selection_fingerprint": { "minLength": 1, "type": "string" }, "state": { "enum": [ "prepared" ], "type": "string" } }, "required": [ "schema_version", "batch_id", "refund_id", "order_number", "request_fingerprint", "selection_fingerprint", "state", "proof" ], "type": "object" }, "product.ProductPackageOption": { "properties": { "code": { "type": "string" }, "dimensions": { "$ref": "#/components/schemas/measurement.Dimensions" }, "effective_from": { "type": "string" }, "effective_to": { "type": "string" }, "handling_unit": { "$ref": "#/components/schemas/packaging_enums.PackageHandlingUnit" }, "is_active": { "type": "boolean" }, "is_canonical": { "type": "boolean" }, "sku_code": { "type": "string" }, "units_per_package": { "type": "integer" }, "version": { "format": "int64", "minimum": 1, "type": "integer" }, "weight": { "$ref": "#/components/schemas/measurement.Weight" } }, "required": [ "version", "code", "effective_from", "handling_unit", "is_active", "is_canonical", "sku_code", "units_per_package" ], "type": "object" }, "product_enums.PriceVisibility": { "enum": [ "public", "login_required", "wholesale_approved_only", "hidden" ], "type": "string", "x-enum-varnames": [ "PriceVisibilityPublic", "PriceVisibilityLoginRequired", "PriceVisibilityWholesaleApprovedOnly", "PriceVisibilityHidden" ] }, "promotion.PromotionAmount": { "properties": { "amount": { "$ref": "#/components/schemas/money.Money" }, "key": { "type": "string" } }, "required": [ "amount", "key" ], "type": "object" }, "promotion.PromotionApplication": { "properties": { "applied_at": { "type": "string" }, "display_messages": { "items": { "$ref": "#/components/schemas/localization.LocalizedText" }, "type": "array", "uniqueItems": false }, "promotion_id": { "type": "string" }, "promotion_kind": { "type": "string" }, "promotion_revision": { "type": "integer" }, "receipt_messages": { "items": { "$ref": "#/components/schemas/localization.LocalizedText" }, "type": "array", "uniqueItems": false }, "relation_id": { "type": "string" }, "resolved_amounts": { "items": { "$ref": "#/components/schemas/promotion.PromotionAmount" }, "type": "array", "uniqueItems": false }, "resolved_qualifier_sku_codes": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "resolved_target_sku_codes": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "resolved_terms": { "items": { "$ref": "#/components/schemas/promotion.PromotionTerm" }, "type": "array", "uniqueItems": false } }, "required": [ "applied_at", "promotion_id", "promotion_kind", "promotion_revision", "relation_id" ], "type": "object" }, "promotion.PromotionTerm": { "properties": { "basis_points_value": { "type": "integer" }, "boolean_value": { "type": "boolean" }, "integer_value": { "type": "integer" }, "key": { "type": "string" }, "money_value": { "$ref": "#/components/schemas/money.Money" }, "string_value": { "type": "string" }, "timestamp_value": { "type": "string" } }, "required": [ "key" ], "type": "object" }, "provider.BankTransferCustomer": { "properties": { "code": { "type": "string" }, "customer_number": { "type": "string" }, "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "type": "object" }, "provider.BankTransferEvidence": { "properties": { "captured_at": { "format": "date-time", "type": "string" }, "captured_by": { "type": "string" }, "code": { "type": "string" }, "mime_type": { "type": "string" }, "sha256": { "type": "string" } }, "required": [ "code", "mime_type", "sha256", "captured_at", "captured_by" ], "type": "object" }, "provider.BankTransferPaymentReference": { "properties": { "confirmation_status": { "$ref": "#/components/schemas/payment_enums.BankTransferConfirmationStatus" }, "confirmed_at": { "format": "date-time", "type": "string" }, "confirmed_by": { "type": "string" }, "customer": { "$ref": "#/components/schemas/provider.BankTransferCustomer" }, "evidence": { "items": { "$ref": "#/components/schemas/provider.BankTransferEvidence" }, "type": "array" }, "payer_reference": { "type": "string" }, "transfer_amount": { "$ref": "#/components/schemas/money.Money" } }, "required": [ "transfer_amount", "confirmation_status", "confirmed_at", "confirmed_by" ], "type": "object" }, "provider.Mx51PaymentReference": { "properties": { "authorization_code": { "type": "string" }, "merchant_id": { "type": "string" }, "reference_id": { "type": "string" }, "retrieval_reference_number": { "type": "string" }, "settlement_id": { "type": "string" }, "system_trace_audit_number": { "type": "string" }, "terminal_id": { "type": "string" }, "transaction_id": { "type": "string" } }, "type": "object" }, "provider.StripePaymentReference": { "properties": { "balance_transaction_id": { "description": "BalanceTransactionID is the Stripe balance transaction that carries\nthe processor fee and net amount for the charge.", "type": "string" }, "charge_id": { "type": "string" }, "checkout_session_id": { "type": "string" }, "customer_id": { "type": "string" }, "payment_intent_id": { "type": "string" }, "refund_id": { "type": "string" } }, "type": "object" }, "provider.WalletPaymentReference": { "properties": { "gift_card_code": { "type": "string" }, "wallet_transaction_id": { "type": "string" } }, "required": [ "gift_card_code", "wallet_transaction_id" ], "type": "object" }, "pubpayments.RefundCompletedEvent": { "additionalProperties": false, "description": "Exact retained shared-v41.0 RefundCompletedEvent payload, preserving opaque identities, original geography, request and buyer facts, Money, native completion instant, separate gross point reversal and original proof. Shared optional fields retain their original omission; no value is inferred. The present native source supports amount-only forward amendments; this schema does not admit line, gift, ordinary, financial-only or other contexts.", "properties": { "amount": { "$ref": "#/components/schemas/money.Money" }, "benefit_reservation_id": { "type": "string" }, "completed_at": { "description": "Exact first durable native Refund.ConfirmedAt in UTC at BSON millisecond precision, never provider-created, read, receipt or publication time.", "format": "date-time", "type": "string" }, "country_code": { "type": "string" }, "full_order_refund": { "type": "boolean" }, "gift_card_refund_amount": { "$ref": "#/components/schemas/money.Money" }, "items": { "items": { "$ref": "#/components/schemas/sales.RefundItemFact" }, "type": "array" }, "market_code": { "type": "string" }, "order_id": { "type": "string" }, "order_number": { "type": "string" }, "organisation_access_id": { "type": "string" }, "payment_id": { "type": "string" }, "points_to_restore": { "type": "integer" }, "qualifying_spend_reversal": { "$ref": "#/components/schemas/money.Money", "description": "Original gross earned-point clawback only; absent remains absent, independently of explicit NET zero." }, "refund_id": { "type": "string" }, "request_id": { "type": "string" }, "retail_customer_number": { "type": "string" }, "tier_refund_proof": { "$ref": "#/components/schemas/refunds.TierBatchPreparedProof", "description": "Exact original Contract39.3 quoted_credit proof; required by supported native completion backing, including intermediate explicit zero." } }, "required": [ "refund_id", "order_number", "amount", "completed_at" ], "type": "object" }, "quote.AppliedPriceRule": { "properties": { "amount_after": { "$ref": "#/components/schemas/money.Money" }, "amount_before": { "$ref": "#/components/schemas/money.Money" }, "applied_at": { "type": "string" }, "chargeable_base_units": { "description": "ChargeableBaseUnits records how many base units the rule charged for,\nwhich differs from the reserved quantity under a buy-one-get-one\nexpiry mechanic.", "type": "integer" }, "exclusive": { "type": "boolean" }, "factor_denominator": { "type": "integer" }, "factor_numerator": { "description": "FactorNumerator over FactorDenominator is the exact multiplier the\nrule applied, for example 85/100 for group_15 or 8/10 for\ndamage_tier_30.", "type": "integer" }, "kind": { "type": "string" }, "reason": { "type": "string" }, "rule_id": { "type": "string" }, "rule_revision": { "type": "integer" } }, "required": [ "amount_after", "amount_before", "applied_at", "exclusive", "kind" ], "type": "object" }, "quote.CartManualDiscountEvidence": { "description": "Pricing's evidence of a cart-level manual discount on a POS sale, frozen\nonto the order from the accepted quote. Exactly one requested value is\npresent for the mode: percent_basis_points for percent (10000 is 100%),\nrequested_amount for amount, target_total for set_total. All amounts are\ngross, tax-inclusive merchandise values.", "properties": { "actor_user_id": { "description": "Staff member who set the discount. Orders blanks this before serving the order to a peer, and it is never copied onto a receipt.", "type": "string" }, "applied_amount": { "$ref": "#/components/schemas/money.Money", "description": "Gross amount actually taken off. Equals the sum of the line allocations." }, "applied_at": { "type": "string" }, "applied_tax": { "$ref": "#/components/schemas/money.Money" }, "coupon_amount": { "$ref": "#/components/schemas/money.Money" }, "coupon_code": { "type": "string" }, "mode": { "$ref": "#/components/schemas/quote_enums.ManualDiscountMode" }, "percent_basis_points": { "format": "int64", "type": "integer" }, "pre_discount_total": { "$ref": "#/components/schemas/money.Money", "description": "Gross merchandise total after promotions and the coupon and before this discount. Shipping is never part of it." }, "reason": { "type": "string" }, "reason_code": { "description": "Free-form, service-validated string rather than an enum, because POS discount reasons are owner-configured.", "type": "string" }, "requested_amount": { "$ref": "#/components/schemas/money.Money" }, "target_total": { "$ref": "#/components/schemas/money.Money" } }, "required": [ "mode", "pre_discount_total", "applied_amount", "applied_tax", "reason_code", "actor_user_id", "applied_at" ], "type": "object" }, "quote.CustomPriceOverrideEvidence": { "properties": { "actor_user_id": { "type": "string" }, "below_cost_warning": { "type": "boolean" }, "compared_cost": { "$ref": "#/components/schemas/money.Money" }, "cost_comparison": { "$ref": "#/components/schemas/quote_enums.CostComparison" }, "custom_price_code": { "type": "string" }, "custom_price_revision": { "format": "int64", "type": "integer" }, "overridden_at": { "type": "string" }, "override_gross_amount": { "$ref": "#/components/schemas/money.Money" }, "reason": { "type": "string" }, "reason_code": { "enum": [ "quick_sale", "soon_expiry", "damaged" ], "type": "string" }, "source_approved_price": { "$ref": "#/components/schemas/money.Money" } }, "required": [ "actor_user_id", "below_cost_warning", "cost_comparison", "overridden_at", "override_gross_amount", "reason", "source_approved_price" ], "type": "object" }, "quote.ManualDiscountLineAllocation": { "description": "One line's share of a cart-level manual discount. A breakdown, not an\nextra adjustment: Pricing folds the share into the line's\ndiscount_amount, taxable_base, tax, tax_amount and line_total.", "properties": { "allocated_gross": { "$ref": "#/components/schemas/money.Money" }, "allocated_tax": { "$ref": "#/components/schemas/money.Money" } }, "required": [ "allocated_gross", "allocated_tax" ], "type": "object" }, "quote.PriceSnapshot": { "properties": { "applied_rules": { "items": { "$ref": "#/components/schemas/quote.AppliedPriceRule" }, "type": "array", "uniqueItems": false }, "audience": { "$ref": "#/components/schemas/market_enums.PriceAudience" }, "base_units": { "type": "integer" }, "captured_at": { "type": "string" }, "channel": { "$ref": "#/components/schemas/commerce_enums.OrderType" }, "currency": { "type": "string" }, "currency_exponent": { "$ref": "#/components/schemas/money.CurrencyExponent" }, "custom_override": { "$ref": "#/components/schemas/quote.CustomPriceOverrideEvidence" }, "discount_amount": { "$ref": "#/components/schemas/money.Money" }, "eligibility": { "$ref": "#/components/schemas/listing.SaleEligibilitySnapshot" }, "fingerprint": { "description": "Fingerprint is the Pricing-owned immutable identity of the resolved\nquote inputs and outputs.", "type": "string" }, "line_id": { "type": "string" }, "line_total": { "$ref": "#/components/schemas/money.Money" }, "list_unit_price": { "$ref": "#/components/schemas/money.Money" }, "manual_discount": { "$ref": "#/components/schemas/quote.ManualDiscountLineAllocation", "description": "This line's share of a cart-level manual discount. A breakdown, not\nan extra adjustment: Pricing has already folded the share into this\nline's discount_amount, taxable_base, tax, tax_amount and\nline_total." }, "market_code": { "type": "string" }, "membership_tier_key": { "type": "string" }, "membership_tier_price_book_assignment_id": { "type": "string" }, "membership_tier_price_book_assignment_revision": { "format": "int64", "type": "integer" }, "package_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "package_list_amount": { "$ref": "#/components/schemas/money.Money" }, "package_price_entry_id": { "type": "string" }, "package_price_entry_revision": { "format": "int64", "type": "integer" }, "price_book_code": { "type": "string" }, "price_book_revision": { "description": "PriceBookRevision and PriceEntryRevision pin the exact price\ndefinitions that resolved. A newer revision requires a re-quote.", "type": "integer" }, "price_entry_id": { "type": "string" }, "price_entry_revision": { "type": "integer" }, "quote_id": { "type": "string" }, "rounding": { "$ref": "#/components/schemas/quote.RoundingEvidence" }, "sku_code": { "type": "string" }, "tax": { "$ref": "#/components/schemas/quote.TaxSnapshot" }, "tax_amount": { "$ref": "#/components/schemas/money.Money" }, "taxable_base": { "$ref": "#/components/schemas/money.Money" }, "unit_price": { "$ref": "#/components/schemas/quote.UnitPriceEvidence" } }, "required": [ "audience", "base_units", "captured_at", "channel", "currency", "currency_exponent", "discount_amount", "eligibility", "fingerprint", "line_id", "line_total", "list_unit_price", "market_code", "package_composition", "price_book_code", "price_book_revision", "price_entry_id", "price_entry_revision", "quote_id", "rounding", "sku_code", "tax", "tax_amount", "taxable_base" ], "type": "object" }, "quote.RoundingEvidence": { "properties": { "exact_denominator": { "type": "integer" }, "exact_numerator": { "description": "ExactNumerator over ExactDenominator is the unrounded value in minor\nunits before the mode was applied.", "type": "integer" }, "exponent": { "type": "integer" }, "mode": { "$ref": "#/components/schemas/quote_enums.RoundingMode" }, "price_ending": { "$ref": "#/components/schemas/pricebook_enums.PriceEndingPolicy" }, "remainder_minor_applied": { "type": "integer" }, "remainder_rank": { "description": "RemainderRank and RemainderMinorApplied record this line's position\nand share when document minor units were allocated by largest\nremainder. TieBreakKey is the stable line identity used to break\nequal remainders.", "type": "integer" }, "rounded_amount": { "$ref": "#/components/schemas/money.Money" }, "tie_break_key": { "type": "string" } }, "required": [ "exact_denominator", "exact_numerator", "exponent", "mode", "price_ending", "rounded_amount" ], "type": "object" }, "quote.TaxSnapshot": { "properties": { "allocated_tax": { "$ref": "#/components/schemas/money.Money" }, "calculation_source": { "$ref": "#/components/schemas/quote_enums.TaxCalculationSource" }, "inclusion_basis": { "$ref": "#/components/schemas/pricebook_enums.PriceTaxInclusion" }, "rate_denominator": { "type": "integer" }, "rate_numerator": { "description": "RateNumerator over RateDenominator is the exact rate that was\napplied, for example 1/11 to extract tax from a tax-inclusive\nconsideration or 1/10 to add tax to a tax-exclusive one.", "type": "integer" }, "rounding_method": { "$ref": "#/components/schemas/quote_enums.TaxRoundingMethod" }, "tax_category_code": { "type": "string" }, "tax_rule_id": { "type": "string" }, "tax_rule_revision": { "type": "integer" }, "taxable_base": { "$ref": "#/components/schemas/money.Money" } }, "required": [ "allocated_tax", "calculation_source", "inclusion_basis", "rate_denominator", "rate_numerator", "rounding_method", "tax_category_code", "tax_rule_id", "tax_rule_revision", "taxable_base" ], "type": "object" }, "quote.UnitPriceEvidence": { "properties": { "comparison_amount": { "$ref": "#/components/schemas/money.Money" }, "exempt": { "type": "boolean" }, "exemption_reason": { "type": "string" }, "net_content": { "$ref": "#/components/schemas/measurement.NetContent" } }, "required": [ "comparison_amount", "exempt", "net_content" ], "type": "object" }, "quote_enums.CostComparison": { "enum": [ "below_cost", "at_or_above_cost", "unavailable" ], "type": "string", "x-enum-varnames": [ "CostComparisonBelowCost", "CostComparisonAtOrAboveCost", "CostComparisonUnavailable" ] }, "quote_enums.ManualDiscountMode": { "description": "How a cart-level manual discount was requested at the till.", "enum": [ "percent", "amount", "set_total" ], "type": "string", "x-enum-varnames": [ "ManualDiscountModePercent", "ManualDiscountModeAmount", "ManualDiscountModeSetTotal" ] }, "quote_enums.RoundingMode": { "enum": [ "half_up", "half_cent_up", "charm_nine_up", "cash_increment", "largest_remainder" ], "type": "string", "x-enum-varnames": [ "RoundingModeHalfUp", "RoundingModeHalfCentUp", "RoundingModeCharmNineUp", "RoundingModeCashIncrement", "RoundingModeLargestRemainder" ] }, "quote_enums.TaxCalculationSource": { "enum": [ "inclusive_extraction", "exclusive_addition", "zero_rated", "exempt", "out_of_scope" ], "type": "string", "x-enum-varnames": [ "TaxCalculationSourceInclusiveExtraction", "TaxCalculationSourceExclusiveAddition", "TaxCalculationSourceZeroRated", "TaxCalculationSourceExempt", "TaxCalculationSourceOutOfScope" ] }, "quote_enums.TaxRoundingMethod": { "enum": [ "sum_exact_then_round", "per_line_round" ], "type": "string", "x-enum-varnames": [ "TaxRoundingMethodSumExactThenRound", "TaxRoundingMethodPerLineRound" ] }, "receipt.CashRoundingSnapshot": { "properties": { "applied_at": { "format": "date-time", "type": "string" }, "cash_amount_due": { "$ref": "#/components/schemas/money.Money" }, "exact_amount_due": { "$ref": "#/components/schemas/money.Money" }, "increment_minor": { "format": "int64", "type": "integer" }, "mode": { "type": "string" }, "rounding_adjustment": { "$ref": "#/components/schemas/money.Money" } }, "required": [ "exact_amount_due", "rounding_adjustment", "cash_amount_due", "increment_minor", "mode", "applied_at" ], "type": "object" }, "receipts.DeliverReceiptInput": { "additionalProperties": false, "description": "A till request to email one stored POS receipt. Unknown fields are refused.", "properties": { "channel": { "description": "Delivery channel. Only email is delivered today; any other value, including sms, is refused with details.reason unsupported_channel.", "enum": [ "email" ], "type": "string" }, "email": { "description": "Optional typed bare address (no display name, no quoted local part). Wins over the customer bound to the sale and is used for this receipt only; it is stored nowhere by Payments.", "format": "email", "maxLength": 254, "type": "string" }, "idempotency_key": { "description": "UUID chosen by the till, in any letter case (keys differing only in case are the same key; Payments forwards it lowercased). The nil UUID is refused. Repeating it with the same body sends once; reusing it with a different body is a 409.", "format": "uuid", "type": "string" }, "locale": { "description": "Optional email language.", "enum": [ "en", "zh-TW", "zh-CN" ], "type": "string" } }, "required": [ "channel", "idempotency_key" ], "type": "object" }, "receipts.ReceiptDelivery": { "properties": { "delivery_id": { "description": "Notification's delivery identifier for the queued email.", "type": "string" } }, "required": [ "delivery_id" ], "type": "object" }, "refundrequests.AlternativeOffer": { "additionalProperties": false, "description": "One staff-proposed alternative to refunding the request. Recording an offer moves no money and reserves no stock. A newer revision withdraws the previous one.", "properties": { "contact_note": { "type": "string" }, "lines": { "items": { "$ref": "#/components/schemas/refundrequests.AlternativeOfferLine" }, "minItems": 1, "type": "array" }, "locale": { "type": "string" }, "offered_at": { "format": "date-time", "type": "string" }, "offered_by": { "type": "string" }, "order_edit_id": { "description": "Orders amendment recorded with an accepted offer.", "type": "string" }, "original_payable": { "$ref": "#/components/schemas/money.Money" }, "proposed_payable": { "$ref": "#/components/schemas/money.Money" }, "responded_at": { "format": "date-time", "type": "string" }, "responded_by": { "type": "string" }, "response_note": { "type": "string" }, "revision": { "minimum": 1, "type": "integer" }, "status": { "enum": [ "offered", "accepted", "rejected", "withdrawn" ], "type": "string" } }, "required": [ "revision", "status", "lines", "original_payable", "proposed_payable", "offered_by", "offered_at" ], "type": "object" }, "refundrequests.AlternativeOfferLine": { "additionalProperties": false, "properties": { "alternative_name": { "type": "string" }, "alternative_sku_code": { "maxLength": 128, "minLength": 1, "type": "string" }, "original_line_ref": { "description": "For a line-based request, the item_id of a line on the request.", "maxLength": 128, "minLength": 1, "type": "string" }, "original_sku_code": { "description": "Filled from the request line when omitted on a line-based request; must match it when sent.", "maxLength": 128, "type": "string" }, "quantity": { "minimum": 1, "type": "integer" }, "unit_price": { "$ref": "#/components/schemas/money.Money" } }, "required": [ "original_line_ref", "alternative_sku_code", "quantity", "unit_price" ], "type": "object" }, "refundrequests.CancelInput": { "additionalProperties": false, "properties": { "idempotency_key": { "description": "Stable retry identity without surrounding whitespace. A replay by the same actor with the exact body returns the cancelled request; a different key or body against a cancelled request conflicts.", "maxLength": 128, "minLength": 1, "type": "string" }, "reason": { "description": "Why the request is withdrawn. Surrounding whitespace is trimmed; a blank reason is refused.", "maxLength": 2000, "minLength": 1, "type": "string" } }, "required": [ "reason", "idempotency_key" ], "type": "object" }, "refundrequests.CompletedEvidenceChunk": { "additionalProperties": false, "properties": { "canonical_sha256": { "pattern": "^[0-9a-f]{64}$", "type": "string" }, "data_base64": { "format": "byte", "type": "string" }, "ordinal": { "pattern": "^(0|[1-9][0-9]*)$", "type": "string" } }, "required": [ "canonical_sha256", "ordinal", "data_base64" ], "type": "object" }, "refundrequests.CompletedEvidenceManifest": { "additionalProperties": false, "properties": { "amount": { "$ref": "#/components/schemas/money.Money" }, "canonical_length": { "pattern": "^(0|[1-9][0-9]*)$", "type": "string" }, "canonical_sha256": { "pattern": "^[0-9a-f]{64}$", "type": "string" }, "chunk_count": { "pattern": "^[1-9][0-9]*$", "type": "string" }, "classification": { "enum": [ "request_linked", "other_source" ], "type": "string" }, "completed_at": { "format": "date-time", "type": "string" }, "full_order_refund": { "description": "Owner-verified full financial completion. Required for a financial-only line with zero physical quantity.", "type": "boolean" }, "order_number": { "type": "string" }, "payment_id": { "type": "string" }, "refund_id": { "type": "string" }, "refund_status": { "enum": [ "completed" ], "type": "string" }, "request_generation": { "description": "Present only for request_linked.", "minimum": 0, "type": "integer" }, "request_id": { "description": "Present only for request_linked.", "type": "string" }, "source": { "type": "string" } }, "required": [ "classification", "source", "order_number", "refund_id", "payment_id", "refund_status", "amount", "completed_at", "full_order_refund", "canonical_sha256", "canonical_length", "chunk_count" ], "type": "object" }, "refundrequests.OfferInput": { "additionalProperties": false, "properties": { "contact_note": { "maxLength": 2000, "type": "string" }, "expected_offer_revision": { "description": "The request's current offer_revision. A stale value conflicts.", "minimum": 0, "type": "integer" }, "idempotency_key": { "description": "Stable retry identity. A replay by the same actor with the exact body returns the stored result; a changed body conflicts.", "maxLength": 128, "minLength": 1, "type": "string" }, "lines": { "items": { "$ref": "#/components/schemas/refundrequests.AlternativeOfferLine" }, "maxItems": 100, "minItems": 1, "type": "array" }, "locale": { "description": "BCP 47 language tag for customer copy.", "maxLength": 35, "type": "string" }, "original_payable": { "$ref": "#/components/schemas/money.Money" }, "proposed_payable": { "$ref": "#/components/schemas/money.Money" } }, "required": [ "idempotency_key", "expected_offer_revision", "lines", "original_payable", "proposed_payable" ], "type": "object" }, "refundrequests.OfferResponseInput": { "additionalProperties": false, "properties": { "decision": { "enum": [ "accepted", "rejected" ], "type": "string" }, "idempotency_key": { "maxLength": 128, "minLength": 1, "type": "string" }, "note": { "maxLength": 2000, "type": "string" }, "order_edit_id": { "description": "Only valid with decision accepted.", "maxLength": 128, "type": "string" } }, "required": [ "idempotency_key", "decision" ], "type": "object" }, "refundrequests.RefundRequest": { "properties": { "amount": { "$ref": "#/components/schemas/money.Money" }, "approval_generation": { "minimum": 0, "type": "integer" }, "cancel_reason": { "description": "Trimmed reason given when cancelling. Present only when status is cancelled.", "type": "string" }, "cancelled_at": { "description": "Present only when status is cancelled.", "format": "date-time", "type": "string" }, "cancelled_by": { "description": "Email of the staff member who cancelled the request. Present only when status is cancelled.", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "lines": { "items": { "$ref": "#/components/schemas/refundrequests.RequestLine" }, "type": "array" }, "offer": { "$ref": "#/components/schemas/refundrequests.AlternativeOffer" }, "offer_revision": { "description": "Latest alternative-offer revision, 0 when none. Send it as expected_offer_revision when making the next offer.", "minimum": 0, "type": "integer" }, "order_number": { "type": "string" }, "packing_review": { "$ref": "#/components/schemas/refunds.PackingRefundReview" }, "refund_id": { "type": "string" }, "reviewed_at": { "format": "date-time", "type": "string" }, "reviewed_by": { "type": "string" }, "schema_version": { "description": "Stored rows are migrated from 22 to 23 at startup; 23 adds offer_revision and offer.", "maximum": 23, "minimum": 23, "type": "integer" }, "status": { "description": "alternative_accepted is terminal. The customer accepted a staff alternative offer, and the request's refund reservation was released in the same transaction. No refund is executed. cancelled is terminal. Staff withdrew the pending staff-raised request through POST /refund-requests/{id}/cancel, and its refund reservation was released in the same transaction. No refund is executed, and it no longer counts against the order's allocation.", "enum": [ "pending", "approved", "rejected", "alternative_accepted", "cancelled" ], "type": "string" }, "terminal_execution": { "$ref": "#/components/schemas/refunds.TerminalHandoff" } }, "required": [ "schema_version", "id", "order_number", "status", "amount", "lines", "approval_generation", "offer_revision", "created_at" ], "type": "object" }, "refundrequests.RequestLine": { "additionalProperties": false, "properties": { "composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "item_id": { "type": "string" }, "product_name": { "type": "string" }, "sku_code": { "type": "string" } }, "required": [ "item_id", "sku_code", "composition" ], "type": "object" }, "refundrequests.StaffCreateInput": { "additionalProperties": false, "properties": { "idempotency_key": { "description": "Stable staff request identity. Replay must use the same actor and exact body; a changed request conflicts. A replay returns the stored request in whatever status it now has, including cancelled. The packing station uses packing-refund_{discrepancyID} (24 lowercase hex). To change the quantity of a station request, cancel it, then raise the replacement with packing-refund_{discrepancyID}_{cancelledRequestID}; the original key would replay the cancelled request. The suffix must name a cancelled or rejected request on the same order that was raised for the same discrepancy; any other suffix returns 409. Approval of a request with either key re-checks the current packing shortage and returns 409 REFUND_REQUEST_SHORTAGE_CHANGED when it no longer covers every requested package component, or when another pending or approved request exists for the same discrepancy.", "maxLength": 128, "minLength": 1, "type": "string" }, "lines": { "items": { "$ref": "#/components/schemas/refundrequests.RequestLine" }, "minItems": 1, "type": "array" }, "order_number": { "minLength": 1, "type": "string" }, "packing_review": { "$ref": "#/components/schemas/refunds.PackingRefundReview" }, "reason": { "type": "string" } }, "required": [ "order_number", "lines", "idempotency_key" ], "type": "object" }, "refunds.AdmissionRecoveryInput": { "additionalProperties": false, "properties": { "idempotency_key": { "format": "uuid", "type": "string" }, "order_number": { "maxLength": 100, "minLength": 1, "type": "string" } }, "required": [ "order_number", "idempotency_key" ], "type": "object" }, "refunds.AdmissionRefusal": { "additionalProperties": false, "properties": { "actor_user_id": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "idempotency_key": { "format": "uuid", "type": "string" }, "order_number": { "type": "string" }, "outcome": { "enum": [ "rejected" ], "type": "string" }, "reason_code": { "enum": [ "REFUND_ADMISSION_CANCELLED" ], "type": "string" } }, "required": [ "order_number", "idempotency_key", "outcome", "reason_code", "actor_user_id", "created_at" ], "type": "object" }, "refunds.CreateInput": { "additionalProperties": false, "description": "Select exactly one refund mode: full=true without an amount or nonempty lines; nonempty lines with an exact positive amount; or a positive amount without lines. The amount currency must match the payment. Full refunds derive the remaining captured amount. Unknown fields are rejected. An optional destination selects where the refunded value goes; absent means the original tender, unchanged.", "properties": { "amount": { "$ref": "#/components/schemas/money.Money" }, "destination": { "$ref": "#/components/schemas/refunds.RefundDestination" }, "full": { "default": false, "type": "boolean" }, "idempotency_key": { "minLength": 1, "type": "string" }, "lines": { "items": { "$ref": "#/components/schemas/refunds.RefundLineReq" }, "type": "array" }, "order_number": { "minLength": 1, "type": "string" }, "payment_id": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "order_number", "idempotency_key" ], "type": "object" }, "refunds.GiftCardIssuanceEvidence": { "description": "Pricing issuance evidence for a new_gift_card refund. Only the masked number is stored or returned by reads.", "properties": { "claim_code": { "description": "Bearer credential returned only by POST /pos/refunds (create or exact replay) while the card awaits its claim. Never persisted or logged; absent when it could not be re-read (retry the same idempotency_key).", "pattern": "^GC[0-9]{12}$", "type": "string" }, "delivery_method": { "enum": [ "customer_wallet", "bearer_claim_code" ], "type": "string" }, "delivery_status": { "enum": [ "notification_queued", "awaiting_claim", "not_delivered" ], "type": "string" }, "issuance_id": { "type": "string" }, "market_code": { "type": "string" }, "masked_code": { "description": "Gift number with only the GC prefix and last four digits visible, e.g. GC********1234.", "type": "string" }, "notification_queued": { "type": "boolean" }, "status": { "description": "requested/unknown keep the refund pending and reserved until the recovery path (replay or the gift-card-refund-recovery maintenance task) confirms the card or fences and releases it. issued, pending_claim and claimed complete the refund; cancelled and refused fail it with the reservation released; conflict needs reconciliation.", "enum": [ "requested", "unknown", "issued", "pending_claim", "claimed", "cancelled", "refused", "conflict" ], "type": "string" } }, "required": [ "status", "market_code", "notification_queued" ], "type": "object" }, "refunds.GiftPurchaseRefundInput": { "additionalProperties": false, "properties": { "idempotency_key": { "minLength": 1, "type": "string" }, "order_number": { "minLength": 1, "type": "string" }, "payment_id": { "minLength": 1, "type": "string" }, "reason": { "description": "Trimmed non-empty staff reason, at most 1000 UTF-8 bytes.", "minLength": 1, "type": "string" } }, "required": [ "order_number", "payment_id", "reason", "idempotency_key" ], "type": "object" }, "refunds.GiftPurchaseRefundResponse": { "properties": { "data": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_modules_refunds.Refund" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "refunds.PackingRefundReview": { "additionalProperties": false, "description": "Staff-entered amount for one recorded converted-CASE shortage. The outer request requires a reason and exactly one physical EACH line covering the current missing quantity. The standard refund.approve review is still required. Quantity and money remain reserved against the original priced component and captured payment.", "properties": { "amount": { "$ref": "#/components/schemas/money.Money" }, "component_index": { "description": "Explicit original priced-component index on the order item.", "minimum": 0, "type": "integer" }, "discrepancy_id": { "minLength": 1, "type": "string" }, "packing_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "substitution_id": { "minLength": 1, "type": "string" } }, "required": [ "packing_revision", "discrepancy_id", "substitution_id", "component_index", "amount" ], "type": "object" }, "refunds.ReconcileProviderRefundInput": { "additionalProperties": false, "properties": { "provider_refund_id": { "maxLength": 128, "pattern": "^re_[A-Za-z0-9]+$", "type": "string" } }, "required": [ "provider_refund_id" ], "type": "object" }, "refunds.RefundDestination": { "additionalProperties": false, "description": "original_tender (the default when destination is absent) refunds the captured tender exactly as before. new_gift_card issues ONE new Pricing gift card for exactly the refund amount Payments computes for the same mode, eligibility, permissions (refund.write; pos.access on the POS route) and geographic scope, consuming the same reserved refund authority. No gateway, terminal or original gift card is ever refunded for such a row. recipient_customer_number, when given, must equal the order's buyer retail customer number and makes the card owned by that customer (delivered to their wallet with a notification); omit it for a bearer card whose claim_code is returned only in the POS response. Refusals carry error.details.reason: refund_destination_invalid (400), gift_card_destination_unsupported_source, gift_card_recipient_not_order_buyer, gift_card_market_unknown, gift_card_destination_gift_funded, gift_card_issuance_refused, gift_card_issuance_conflict (409), gift_card_issuance_unknown, gift_card_issuance_unavailable (503: the refund stays reserved; retry the same idempotency_key).", "properties": { "kind": { "enum": [ "original_tender", "new_gift_card" ], "type": "string" }, "recipient_customer_number": { "maxLength": 256, "type": "string" } }, "required": [ "kind" ], "type": "object" }, "refunds.RefundLineReq": { "additionalProperties": false, "properties": { "composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot", "description": "Positive package composition from the purchased line, with versioned package_option references for every component." }, "item_id": { "minLength": 1, "type": "string" }, "participant_shares": { "items": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_modules_refunds.RefundParticipantShare" }, "type": "array" } }, "required": [ "item_id", "composition" ], "type": "object" }, "refunds.TerminalHandoff": { "additionalProperties": false, "description": "Terminal execution of an approved refund. Amount is only the external leg; the canonical refund retains whole money and gift/benefit restoration. Prepared or unknown is not completed and must not be retried with a new transaction.", "properties": { "amount": { "$ref": "#/components/schemas/money.Money" }, "executed_by": { "description": "Authenticated executor retained at first preparation; replay cannot replace it.", "type": "string" }, "payment_id": { "type": "string" }, "provider": { "type": "string" }, "register_id": { "type": "string" }, "session_id": { "type": "string" }, "state": { "enum": [ "awaiting_terminal", "prepared", "completed", "failed", "cancelled" ], "type": "string" }, "terminal_id": { "type": "string" }, "transaction_id": { "type": "string" } }, "required": [ "state", "amount", "payment_id", "provider" ], "type": "object" }, "refunds.TierBatchAssignment": { "additionalProperties": false, "properties": { "batch_fingerprint": { "description": "Versioned native Payments digest of the complete ordered assignment. A digest alone does not prove Orders unit authority or Pricing proof readiness.", "type": "string" }, "batch_id": { "minLength": 1, "type": "string" }, "final_refund_id": { "description": "Exact last positive leg identity. It does not itself establish selected-unit or NET credit authority.", "type": "string" }, "legs": { "description": "Complete frozen ordered positive legs, unique by RefundID and PaymentID. No pagination or truncation.", "items": { "$ref": "#/components/schemas/refunds.TierBatchLeg" }, "minItems": 1, "type": "array" }, "order_id": { "minLength": 1, "type": "string" }, "order_number": { "minLength": 1, "type": "string" }, "orders_disposition_id": { "minLength": 1, "type": "string" }, "orders_selection_fingerprint": { "minLength": 1, "type": "string" }, "orders_selection_id": { "minLength": 1, "type": "string" }, "prior_completed_refund_ids": { "description": "Reserved protocol field; no prior completed money is attached or rewritten by this foundation.", "items": { "type": "string" }, "type": "array" }, "retry_of_batch_id": { "description": "Reserved protocol field; this foundation refuses retries until confirmed terminal and release journal qualification.", "type": "string" }, "schema_version": { "const": 1, "format": "int64", "type": "integer" } }, "required": [ "schema_version", "batch_id", "batch_fingerprint", "order_id", "order_number", "orders_disposition_id", "orders_selection_id", "orders_selection_fingerprint", "legs", "final_refund_id" ], "type": "object" }, "refunds.TierBatchCompletedContext": { "additionalProperties": false, "description": "Original native completion event and immutable identity/linkage, verified with retained original Orders source and both actual outbox companions. The native event fingerprint covers private source backing omitted here and cannot be recomputed from this projection. It is not a receipt or NET consumption acknowledgement.", "properties": { "event": { "$ref": "#/components/schemas/pubpayments.RefundCompletedEvent" }, "event_fingerprint": { "pattern": "^v1:sha256:[0-9a-f]{64}$", "type": "string" }, "event_id": { "minLength": 1, "type": "string" }, "outcome_fingerprint": { "pattern": "^v1:sha256:[0-9a-f]{64}$", "type": "string" }, "schema_version": { "const": 1, "format": "int64", "type": "integer" } }, "required": [ "schema_version", "event_id", "event_fingerprint", "outcome_fingerprint", "event" ], "type": "object" }, "refunds.TierBatchCompletionLifecycleLegSnapshot": { "additionalProperties": false, "properties": { "applicability_state": { "enum": [ "unverified" ], "type": "string" }, "completed_context": { "$ref": "#/components/schemas/refunds.TierBatchCompletedContext", "description": "Required exactly for actually completed participants, including an intermediate original zero after later failure. Other participants omit this field. Final context requires the native whole completion barrier." }, "dispatch": { "$ref": "#/components/schemas/refunds.TierBatchDispatchReference" }, "dispatch_state": { "enum": [ "not_started", "claimed" ], "type": "string" }, "financial_status": { "enum": [ "pending", "completed", "failed", "cancelled" ], "type": "string" }, "outcome": { "$ref": "#/components/schemas/refunds.TierBatchOutcomeReference" }, "payment_id": { "minLength": 1, "type": "string" }, "prepared": { "$ref": "#/components/schemas/pricing.TierRefundPreparedResult" }, "proof_state": { "enum": [ "absent", "frozen" ], "type": "string" }, "refund_id": { "minLength": 1, "type": "string" }, "release_journal": { "$ref": "#/components/schemas/refunds.TierBatchProofReleaseJournal" }, "schema_version": { "const": 4, "format": "int64", "type": "integer" } }, "required": [ "schema_version", "refund_id", "payment_id", "financial_status", "dispatch_state", "proof_state", "applicability_state" ], "type": "object" }, "refunds.TierBatchCompletionLifecycleSnapshot": { "additionalProperties": false, "description": "Additive complete schema4 local snapshot exposing original completed event context. Assignment1, prepared tuples/proofs, freeze1, original private event digest and native financial barrier are unchanged. Each completed leg validates original source and both actual outbox envelopes. V1/V2/schema3 DTOs and predicates stay unchanged; this read neither consumes NET nor acknowledges receipts or activates effects.", "properties": { "assignment": { "$ref": "#/components/schemas/refunds.TierBatchAssignment" }, "batch_status": { "enum": [ "plan_frozen_unverified", "proof_frozen_unverified", "cancelled_before_dispatch", "dispatch_unresolved", "partially_completed_held", "financial_failure_held", "completed_proof_bound" ], "type": "string" }, "completion": { "$ref": "#/components/schemas/refunds.TierBatchCompletionRecord" }, "legs": { "items": { "$ref": "#/components/schemas/refunds.TierBatchCompletionLifecycleLegSnapshot" }, "minItems": 1, "type": "array" }, "proof_freeze": { "$ref": "#/components/schemas/refunds.TierBatchProofFreeze" }, "schema_version": { "const": 4, "format": "int64", "type": "integer" } }, "required": [ "schema_version", "assignment", "batch_status", "legs" ], "type": "object" }, "refunds.TierBatchCompletionRecord": { "additionalProperties": false, "description": "Whole financial completion barrier over immutable assignment, original freeze/proofs and every ordered actual native outcome. Final actual persisted Refund.ConfirmedAt supplies completed_at and the market-local qualifying year; publication, delivery and provider-created times never substitute. A public digest alone cannot establish private backing.", "properties": { "completed_at": { "format": "date-time", "type": "string" }, "completion_fingerprint": { "pattern": "^v1:sha256:[0-9a-f]{64}$", "type": "string" }, "completion_id": { "minLength": 1, "type": "string" }, "final_refund_id": { "minLength": 1, "type": "string" }, "schema_version": { "const": 1, "format": "int64", "type": "integer" } }, "required": [ "schema_version", "completion_id", "completion_fingerprint", "final_refund_id", "completed_at" ], "type": "object" }, "refunds.TierBatchDispatchReference": { "additionalProperties": false, "description": "Immutable native serial claim observation. An exact replay grants no second provider invocation.", "properties": { "attempt_fingerprint": { "pattern": "^v1:sha256:[0-9a-f]{64}$", "type": "string" }, "attempt_id": { "minLength": 1, "type": "string" }, "claimed_at": { "format": "date-time", "type": "string" }, "schema_version": { "const": 1, "format": "int64", "type": "integer" } }, "required": [ "schema_version", "attempt_id", "attempt_fingerprint", "claimed_at" ], "type": "object" }, "refunds.TierBatchExecutionLegSnapshot": { "additionalProperties": false, "properties": { "applicability_state": { "enum": [ "unverified" ], "type": "string" }, "dispatch": { "$ref": "#/components/schemas/refunds.TierBatchDispatchReference" }, "dispatch_state": { "enum": [ "not_started", "claimed" ], "type": "string" }, "financial_status": { "enum": [ "pending", "completed", "failed", "cancelled" ], "type": "string" }, "outcome": { "$ref": "#/components/schemas/refunds.TierBatchOutcomeReference" }, "payment_id": { "minLength": 1, "type": "string" }, "prepared": { "$ref": "#/components/schemas/pricing.TierRefundPreparedResult", "description": "Exact original tuple and proof required for each frozen participant forever, including zero, completion and failure; no recalculation." }, "proof_state": { "enum": [ "absent", "frozen" ], "type": "string" }, "refund_id": { "minLength": 1, "type": "string" }, "release_journal": { "$ref": "#/components/schemas/refunds.TierBatchProofReleaseJournal", "description": "Supported only for whole original pre-dispatch cancellation. Pending never confirms remote release." }, "schema_version": { "const": 3, "format": "int64", "type": "integer" } }, "required": [ "schema_version", "refund_id", "payment_id", "financial_status", "dispatch_state", "proof_state", "applicability_state" ], "type": "object" }, "refunds.TierBatchExecutionLifecycleSnapshot": { "additionalProperties": false, "description": "Complete local schema3 observation with immutable Assignment1 and all original prepared proofs/native freeze. Every completed leg independently validates its retained original completion event and both actual outbox facts. All-complete final state requires the whole native barrier; missing backing refuses. This does not activate a provider writer or Pricing consumer.", "properties": { "assignment": { "$ref": "#/components/schemas/refunds.TierBatchAssignment" }, "batch_status": { "enum": [ "plan_frozen_unverified", "proof_frozen_unverified", "cancelled_before_dispatch", "dispatch_unresolved", "partially_completed_held", "financial_failure_held", "completed_proof_bound" ], "type": "string" }, "completion": { "$ref": "#/components/schemas/refunds.TierBatchCompletionRecord", "description": "Required only for completed_proof_bound. Final completion, barrier and original selected-proof outbox commit atomically. Earlier zero events may arrive later without weakening this native barrier." }, "legs": { "items": { "$ref": "#/components/schemas/refunds.TierBatchExecutionLegSnapshot" }, "minItems": 1, "type": "array" }, "proof_freeze": { "$ref": "#/components/schemas/refunds.TierBatchProofFreeze" }, "schema_version": { "const": 3, "format": "int64", "type": "integer" } }, "required": [ "schema_version", "assignment", "batch_status", "legs" ], "type": "object" }, "refunds.TierBatchLeg": { "additionalProperties": false, "properties": { "amount": { "$ref": "#/components/schemas/money.Money", "description": "Positive captured-source refund amount in the exact batch currency." }, "payment_id": { "minLength": 1, "type": "string" }, "refund_id": { "minLength": 1, "type": "string" }, "request_fingerprint": { "minLength": 1, "type": "string" } }, "required": [ "refund_id", "payment_id", "amount", "request_fingerprint" ], "type": "object" }, "refunds.TierBatchLegSnapshot": { "additionalProperties": false, "properties": { "applicability_state": { "enum": [ "unverified" ], "type": "string" }, "dispatch_state": { "enum": [ "not_started" ], "type": "string" }, "financial_status": { "enum": [ "pending" ], "type": "string" }, "proof_state": { "enum": [ "absent" ], "type": "string" }, "refund_id": { "type": "string" }, "schema_version": { "const": 1, "format": "int64", "type": "integer" } }, "required": [ "refund_id", "financial_status", "schema_version", "dispatch_state", "proof_state", "applicability_state" ], "type": "object" }, "refunds.TierBatchLifecycleLegSnapshot": { "additionalProperties": false, "properties": { "applicability_state": { "enum": [ "unverified" ], "type": "string" }, "dispatch_state": { "enum": [ "not_started" ], "type": "string" }, "financial_status": { "enum": [ "pending", "cancelled" ], "type": "string" }, "proof_state": { "enum": [ "absent" ], "type": "string" }, "refund_id": { "type": "string" }, "release_journal": { "$ref": "#/components/schemas/refunds.TierBatchReleaseJournal" }, "schema_version": { "const": 1, "format": "int64", "type": "integer" } }, "required": [ "refund_id", "financial_status", "schema_version", "dispatch_state", "proof_state", "applicability_state" ], "type": "object" }, "refunds.TierBatchLifecycleSnapshot": { "additionalProperties": false, "properties": { "assignment": { "$ref": "#/components/schemas/refunds.TierBatchAssignment" }, "batch_status": { "enum": [ "plan_frozen_unverified", "cancelled_before_dispatch" ], "type": "string" }, "legs": { "description": "Complete ordered participant authority. Every cancelled participant carries its own exact native release journal.", "items": { "$ref": "#/components/schemas/refunds.TierBatchLifecycleLegSnapshot" }, "minItems": 1, "type": "array" }, "schema_version": { "const": 1, "format": "int64", "type": "integer" } }, "required": [ "schema_version", "assignment", "batch_status", "legs" ], "type": "object" }, "refunds.TierBatchOutcomeReference": { "additionalProperties": false, "description": "Exact native terminal Stripe economic observation, backed by actual captured Payment and Refund identity/Money. recorded_at is first local durable UTC BSON-millisecond confirmation, never provider-created time.", "properties": { "outcome_fingerprint": { "pattern": "^v1:sha256:[0-9a-f]{64}$", "type": "string" }, "outcome_id": { "minLength": 1, "type": "string" }, "recorded_at": { "format": "date-time", "type": "string" }, "schema_version": { "const": 1, "format": "int64", "type": "integer" }, "state": { "enum": [ "succeeded", "failed", "canceled" ], "type": "string" } }, "required": [ "schema_version", "outcome_id", "outcome_fingerprint", "state", "recorded_at" ], "type": "object" }, "refunds.TierBatchPreparedProof": { "additionalProperties": false, "description": "Exact Contract39.3 quoted_credit reservation projection received from qualified Pricing. Required explicit zero is distinct from absent proof and refunded Money.", "properties": { "allocation_fingerprint": { "minLength": 1, "type": "string" }, "allocation_id": { "minLength": 1, "type": "string" }, "allocation_version": { "const": 1, "format": "int64", "type": "integer" }, "basis": { "enum": [ "quoted_credit" ], "type": "string" }, "net_qualifying_spend_reversal": { "$ref": "#/components/schemas/refunds.TierBatchProofMoney" }, "proof_fingerprint": { "pattern": "^v1:sha256:[0-9a-f]{64}$", "type": "string" }, "proof_id": { "pattern": "^v1:sha256:[0-9a-f]{64}$", "type": "string" }, "quote_fingerprint": { "minLength": 1, "type": "string" }, "quote_key": { "minLength": 1, "type": "string" } }, "required": [ "basis", "proof_id", "proof_fingerprint", "allocation_id", "allocation_version", "allocation_fingerprint", "quote_key", "quote_fingerprint", "net_qualifying_spend_reversal" ], "type": "object" }, "refunds.TierBatchPreparedReleaseJournal": { "additionalProperties": false, "description": "Immutable native prepared-before-dispatch cancellation core. Pending remote release is not confirmed; any future acknowledgement requires separate backing.", "properties": { "batch_fingerprint": { "minLength": 1, "type": "string" }, "batch_id": { "minLength": 1, "type": "string" }, "journal_fingerprint": { "pattern": "^v2:sha256:[0-9a-f]{64}$", "type": "string" }, "journal_id": { "minLength": 1, "type": "string" }, "leg_index": { "minimum": 0, "type": "integer" }, "order_number": { "minLength": 1, "type": "string" }, "proof_fingerprint": { "minLength": 1, "type": "string" }, "proof_freeze_fingerprint": { "minLength": 1, "type": "string" }, "proof_freeze_id": { "minLength": 1, "type": "string" }, "proof_id": { "minLength": 1, "type": "string" }, "recorded_at": { "format": "date-time", "type": "string" }, "refund_id": { "minLength": 1, "type": "string" }, "release_state": { "enum": [ "pending" ], "type": "string" }, "request_fingerprint": { "minLength": 1, "type": "string" }, "reservation_facts_fingerprint": { "minLength": 1, "type": "string" }, "reservation_key": { "minLength": 1, "type": "string" }, "schema_version": { "const": 2, "format": "int64", "type": "integer" }, "selection_fingerprint": { "minLength": 1, "type": "string" }, "terminal_reason": { "enum": [ "cancelled_before_dispatch" ], "type": "string" } }, "required": [ "schema_version", "journal_id", "journal_fingerprint", "batch_id", "batch_fingerprint", "leg_index", "refund_id", "order_number", "request_fingerprint", "selection_fingerprint", "reservation_key", "reservation_facts_fingerprint", "terminal_reason", "release_state", "recorded_at", "proof_freeze_id", "proof_freeze_fingerprint", "proof_id", "proof_fingerprint" ], "type": "object" }, "refunds.TierBatchProofFreeze": { "additionalProperties": false, "properties": { "freeze_fingerprint": { "description": "Native digest binds unchanged complete assignment, all ordered originally received prepared results, retained private commercial backing and the native freeze instant. The public projection alone cannot reconstruct this digest. It grants no dispatch permission.", "pattern": "^v1:sha256:[0-9a-f]{64}$", "type": "string" }, "freeze_id": { "minLength": 1, "type": "string" }, "frozen_at": { "description": "Immutable native freeze instant in UTC at BSON millisecond precision; not financial completion time.", "format": "date-time", "type": "string" }, "schema_version": { "const": 1, "format": "int64", "type": "integer" } }, "required": [ "schema_version", "freeze_id", "freeze_fingerprint", "frozen_at" ], "type": "object" }, "refunds.TierBatchProofLifecycleLegSnapshot": { "additionalProperties": false, "properties": { "applicability_state": { "enum": [ "unverified" ], "type": "string" }, "dispatch_state": { "enum": [ "not_started" ], "type": "string" }, "financial_status": { "enum": [ "pending", "cancelled" ], "type": "string" }, "payment_id": { "minLength": 1, "type": "string" }, "prepared": { "$ref": "#/components/schemas/pricing.TierRefundPreparedResult", "description": "Required for every frozen proof participant, including after cancellation; never a partial staged response." }, "proof_state": { "enum": [ "absent", "frozen" ], "type": "string" }, "refund_id": { "minLength": 1, "type": "string" }, "release_journal": { "$ref": "#/components/schemas/refunds.TierBatchProofReleaseJournal" }, "schema_version": { "const": 2, "format": "int64", "type": "integer" } }, "required": [ "schema_version", "refund_id", "payment_id", "financial_status", "dispatch_state", "proof_state", "applicability_state" ], "type": "object" }, "refunds.TierBatchProofLifecycleSnapshot": { "additionalProperties": false, "description": "One complete native schema2 snapshot. All ordered legs and original prepared results bind immutable assignment1; proof-bearing V1 reads refuse. No provider completion, consume, failure, retry or dispatch permission is supported.", "properties": { "assignment": { "$ref": "#/components/schemas/refunds.TierBatchAssignment" }, "batch_status": { "enum": [ "plan_frozen_unverified", "proof_frozen_unverified", "cancelled_before_dispatch" ], "type": "string" }, "legs": { "items": { "$ref": "#/components/schemas/refunds.TierBatchProofLifecycleLegSnapshot" }, "minItems": 1, "type": "array" }, "proof_freeze": { "$ref": "#/components/schemas/refunds.TierBatchProofFreeze", "description": "Required with all frozen proofs, permanently retained through prepared cancellation." }, "schema_version": { "const": 2, "format": "int64", "type": "integer" } }, "required": [ "schema_version", "assignment", "batch_status", "legs" ], "type": "object" }, "refunds.TierBatchProofMoney": { "additionalProperties": false, "properties": { "amount_minor": { "format": "int64", "minimum": 0, "type": "integer" }, "currency": { "pattern": "^[A-Z]{3}$", "type": "string" } }, "required": [ "amount_minor", "currency" ], "type": "object" }, "refunds.TierBatchProofReleaseJournal": { "oneOf": [ { "$ref": "#/components/schemas/refunds.TierBatchReleaseJournal" }, { "$ref": "#/components/schemas/refunds.TierBatchPreparedReleaseJournal" } ] }, "refunds.TierBatchReleaseJournal": { "additionalProperties": false, "properties": { "batch_fingerprint": { "minLength": 1, "type": "string" }, "batch_id": { "minLength": 1, "type": "string" }, "journal_fingerprint": { "description": "Native versioned digest of the exact durable journal. A caller digest is not authority.", "minLength": 1, "type": "string" }, "journal_id": { "minLength": 1, "type": "string" }, "leg_index": { "minimum": 0, "type": "integer" }, "order_number": { "minLength": 1, "type": "string" }, "recorded_at": { "format": "date-time", "type": "string" }, "refund_id": { "minLength": 1, "type": "string" }, "release_state": { "description": "Local cancellation is durable; Pricing release or unknown-proof tombstone confirmation has not occurred.", "enum": [ "pending" ], "type": "string" }, "request_fingerprint": { "minLength": 1, "type": "string" }, "reservation_facts_fingerprint": { "minLength": 1, "type": "string" }, "reservation_key": { "minLength": 1, "type": "string" }, "schema_version": { "const": 1, "format": "int64", "type": "integer" }, "selection_fingerprint": { "minLength": 1, "type": "string" }, "terminal_reason": { "enum": [ "cancelled_before_dispatch" ], "type": "string" } }, "required": [ "schema_version", "journal_id", "journal_fingerprint", "batch_id", "batch_fingerprint", "leg_index", "refund_id", "order_number", "request_fingerprint", "selection_fingerprint", "reservation_key", "reservation_facts_fingerprint", "terminal_reason", "release_state", "recorded_at" ], "type": "object" }, "refunds.TierBatchSnapshot": { "additionalProperties": false, "properties": { "assignment": { "$ref": "#/components/schemas/refunds.TierBatchAssignment" }, "batch_status": { "enum": [ "plan_frozen_unverified" ], "type": "string" }, "legs": { "items": { "$ref": "#/components/schemas/refunds.TierBatchLegSnapshot" }, "minItems": 1, "type": "array" } }, "required": [ "assignment", "batch_status", "legs" ], "type": "object" }, "register.MethodTotal": { "properties": { "amount": { "$ref": "#/components/schemas/money.Money" }, "count": { "type": "integer" }, "method": { "$ref": "#/components/schemas/payment_enums.PaymentMethod" }, "provider": { "type": "string" } }, "type": "object" }, "register_enums.CashMovementKind": { "enum": [ "cash_in", "cash_out", "float_adjustment", "drop" ], "type": "string", "x-enum-varnames": [ "CashMovementKindCashIn", "CashMovementKindCashOut", "CashMovementKindFloatAdjustment", "CashMovementKindDrop" ] }, "register_enums.SessionStatus": { "enum": [ "open", "closed" ], "type": "string", "x-enum-varnames": [ "SessionStatusOpen", "SessionStatusClosed" ] }, "retail_enums.BuyerType": { "enum": [ "guest_retail", "retail_customer", "wholesale_organisation" ], "type": "string", "x-enum-varnames": [ "BuyerTypeGuestRetail", "BuyerTypeRetailCustomer", "BuyerTypeWholesaleOrganisation" ] }, "sales.RefundItemFact": { "additionalProperties": false, "description": "Shared-v41.0 item shape. Items are absent in the supported native amount-only completion context; this model does not qualify line associations.", "properties": { "amount": { "$ref": "#/components/schemas/money.Money" }, "brand_code": { "type": "string" }, "category_tag_codes": { "items": { "type": "string" }, "type": "array" }, "collection_code": { "type": "string" }, "country_code": { "type": "string" }, "market_code": { "type": "string" }, "package_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "production": { "type": "string" }, "sku_code": { "type": "string" }, "storage_type": { "type": "string" } }, "required": [ "sku_code", "market_code", "package_composition", "amount" ], "type": "object" }, "security.HistoryChange": { "properties": { "field": { "type": "string" }, "from_value": { "type": "string" }, "to_value": { "type": "string" } }, "required": [ "field" ], "type": "object" }, "security.HistoryEntry": { "properties": { "actor_domain": { "$ref": "#/components/schemas/security_enums.IdentityDomain" }, "actor_email": { "type": "string" }, "actor_id": { "type": "string" }, "actor_role": { "type": "string" }, "changes": { "items": { "$ref": "#/components/schemas/security.HistoryChange" }, "type": "array", "uniqueItems": false }, "id": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/metadata.Metadata" }, "note": { "type": "string" }, "occurred_at": { "type": "string" }, "reason_code": { "type": "string" }, "related_resource": { "type": "string" }, "related_resource_id": { "type": "string" }, "risk_flags": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "risk_level": { "$ref": "#/components/schemas/security_enums.SecurityRiskLevel" }, "sequence": { "type": "integer" }, "source": { "type": "string" }, "summary": { "type": "string" }, "type": { "type": "string" } }, "required": [ "occurred_at", "type" ], "type": "object" }, "security.ObjectMedia": { "properties": { "code": { "type": "string" }, "url": { "type": "string" } }, "required": [ "code" ], "type": "object" }, "security_enums.DataClassification": { "enum": [ "public", "internal", "confidential", "restricted" ], "type": "string", "x-enum-varnames": [ "DataClassificationPublic", "DataClassificationInternal", "DataClassificationConfidential", "DataClassificationRestricted" ] }, "security_enums.DataProtectionBasis": { "enum": [ "not_applicable", "consent", "contract", "legal_obligation", "legitimate_interest" ], "type": "string", "x-enum-varnames": [ "DataProtectionBasisNotApplicable", "DataProtectionBasisConsent", "DataProtectionBasisContract", "DataProtectionBasisLegalObligation", "DataProtectionBasisLegitimateInterest" ] }, "security_enums.IdentityDomain": { "enum": [ "customer", "workforce", "service" ], "type": "string", "x-enum-varnames": [ "IdentityDomainCustomer", "IdentityDomainWorkforce", "IdentityDomainService" ] }, "security_enums.SecurityRiskLevel": { "enum": [ "low", "medium", "high", "critical" ], "type": "string", "x-enum-varnames": [ "SecurityRiskLevelLow", "SecurityRiskLevelMedium", "SecurityRiskLevelHigh", "SecurityRiskLevelCritical" ] }, "shipping.FulfilmentLocationSnapshot": { "properties": { "captured_at": { "type": "string" }, "delivery_address": { "$ref": "#/components/schemas/party.ContactAddress" }, "geographic_context": { "$ref": "#/components/schemas/geography.GeographicContext" }, "intent": { "$ref": "#/components/schemas/shipping_enums.FulfilmentIntent" }, "location_fingerprint": { "type": "string" }, "selected_depot_code": { "type": "string" } }, "type": "object" }, "shipping_enums.DeliveryMethod": { "enum": [ "delivery", "pickup", "outsourced" ], "type": "string", "x-enum-varnames": [ "DeliveryMethodDelivery", "DeliveryMethodPickup", "DeliveryMethodOutsourced" ] }, "shipping_enums.FulfilmentIntent": { "enum": [ "delivery", "pickup", "in_store_carry", "digital" ], "type": "string", "x-enum-varnames": [ "FulfilmentIntentDelivery", "FulfilmentIntentPickup", "FulfilmentIntentInStoreCarry", "FulfilmentIntentDigital" ] }, "shipping_enums.ShippingRateName": { "enum": [ "standard", "express", "pickup" ], "type": "string", "x-enum-varnames": [ "ShippingRateNameStandard", "ShippingRateNameExpress", "ShippingRateNamePickup" ] }, "terminal.Amounts": { "properties": { "authorized_minor": { "format": "int64", "type": "integer" }, "cashout_minor": { "format": "int64", "type": "integer" }, "currency": { "type": "string" }, "moto_minor": { "format": "int64", "type": "integer" }, "purchase_minor": { "format": "int64", "type": "integer" }, "refund_minor": { "format": "int64", "type": "integer" }, "surcharge_minor": { "format": "int64", "type": "integer" }, "tip_minor": { "format": "int64", "type": "integer" } }, "required": [ "currency" ], "type": "object" }, "terminal.TerminalProviderDetails": { "properties": { "device_id": { "type": "string" }, "merchant_id": { "type": "string" }, "nickname": { "type": "string" }, "store_id": { "type": "string" }, "terminal_id": { "type": "string" } }, "type": "object" }, "terminals.ProviderOperationContext": { "properties": { "idempotency_key": { "type": "string" }, "merchant_reference": { "type": "string" }, "request_id": { "type": "string" } }, "type": "object" }, "terminals.ProviderPayloads": { "properties": { "display_notification": {}, "notification": {}, "request": {}, "response": {} }, "type": "object" }, "terminals.ReceiptOptions": { "properties": { "pos_auto_print_signature_receipt": { "type": "boolean" }, "print_merchant_receipt": { "type": "boolean" }, "prompt_customer_receipt": { "type": "boolean" }, "verify_signature_on_terminal": { "type": "boolean" } }, "type": "object" }, "terminals.TerminalTransaction": { "description": "Staff terminal transaction history record. Provider identity is owned by Payments and retained with refund preparation, outcomes and recovery; missing or conflicting identity cannot authorize provider execution.", "properties": { "classification": { "$ref": "#/components/schemas/security_enums.DataClassification" }, "contains_pii": { "type": "boolean" }, "contains_sensitive_pii": { "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "created_by": { "type": "string" }, "customer_receipt": { "type": "string" }, "data_owner_id": { "type": "string" }, "deleted_at": { "format": "date-time", "type": "string" }, "deleted_by": { "type": "string" }, "deletion_completed_at": { "format": "date-time", "type": "string" }, "deletion_requested_at": { "format": "date-time", "type": "string" }, "finalised_at": { "format": "date-time", "type": "string" }, "financial_status": { "enum": [ "approved", "declined", "cancelled", "unknown" ], "type": "string" }, "history": { "items": { "$ref": "#/components/schemas/security.HistoryEntry" }, "type": "array" }, "id": { "type": "string" }, "last_status_checked_at": { "format": "date-time", "type": "string" }, "legal_hold": { "type": "boolean" }, "merchant_receipt": { "type": "string" }, "message": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/metadata.Metadata" }, "operation_context": { "$ref": "#/components/schemas/terminals.ProviderOperationContext" }, "order_number": { "type": "string" }, "payment_id": { "type": "string" }, "protection_basis": { "$ref": "#/components/schemas/security_enums.DataProtectionBasis" }, "provider": { "enum": [ "LINKLY_POS", "MX51_POS" ], "type": "string" }, "provider_data": { "$ref": "#/components/schemas/metadata.Metadata" }, "provider_details": { "$ref": "#/components/schemas/terminal.TerminalProviderDetails" }, "provider_error_condition": { "type": "string" }, "provider_payloads": { "$ref": "#/components/schemas/terminals.ProviderPayloads" }, "provider_reference": { "$ref": "#/components/schemas/payment.PaymentReference" }, "provider_result": { "type": "string" }, "receipt_options": { "$ref": "#/components/schemas/terminals.ReceiptOptions" }, "recovery_decision": { "$ref": "#/components/schemas/payment_enums.RecoveryDecision" }, "requested": { "$ref": "#/components/schemas/terminal.Amounts" }, "result": { "$ref": "#/components/schemas/terminal.Amounts" }, "retention_policy_key": { "type": "string" }, "retention_until": { "format": "date-time", "type": "string" }, "status": { "enum": [ "unknown", "pending", "awaiting_action", "finalised", "override_pending", "override_resolved" ], "type": "string" }, "terminal_id": { "type": "string" }, "type": { "enum": [ "purchase", "refund", "reversal", "cashout", "purchase_with_cashout", "moto", "settlement", "settlement_enquiry" ], "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "updated_by": { "type": "string" } }, "required": [ "id", "terminal_id", "provider", "type", "requested", "status", "result", "created_at", "updated_at" ], "type": "object" }, "wallet_enums.PointAwardStatus": { "enum": [ "ineligible", "disabled", "pending", "awarded", "failed", "held", "released", "dropped" ], "type": "string", "x-enum-varnames": [ "PointAwardStatusIneligible", "PointAwardStatusDisabled", "PointAwardStatusPending", "PointAwardStatusAwarded", "PointAwardStatusFailed", "PointAwardStatusHeld", "PointAwardStatusReleased", "PointAwardStatusDropped" ] }, "wallet_enums.RewardType": { "enum": [ "ORDER_DISCOUNT", "PRODUCT", "FREE_SHIPPING", "COUPON", "GIFT_CARD", "EXTERNAL" ], "type": "string", "x-enum-varnames": [ "RewardTypeOrderDiscount", "RewardTypeProduct", "RewardTypeFreeShipping", "RewardTypeCoupon", "RewardTypeGiftCard", "RewardTypeExternal" ] }, "warehouse.InventoryDateMark": { "properties": { "date_mark_at": { "type": "string" }, "kind": { "$ref": "#/components/schemas/warehouse_enums.InventoryDateMarkKind" }, "timezone": { "type": "string" } }, "required": [ "date_mark_at", "kind", "timezone" ], "type": "object" }, "warehouse.StockLocationRef": { "properties": { "depot_code": { "type": "string" }, "location_code": { "type": "string" } }, "required": [ "depot_code", "location_code" ], "type": "object" }, "warehouse_enums.DamageSaleTier": { "enum": [ "tier_30", "tier_50", "tier_80" ], "type": "string", "x-enum-varnames": [ "DamageSaleTier30", "DamageSaleTier50", "DamageSaleTier80" ] }, "warehouse_enums.InventoryCondition": { "enum": [ "GOOD", "PACKAGING_DAMAGED_MINOR", "PACKAGING_DAMAGED_MAJOR", "PRODUCT_DAMAGED", "OPENED", "CONTAMINATED", "SPOILED" ], "type": "string", "x-enum-varnames": [ "InventoryConditionGood", "InventoryConditionPackagingDamagedMinor", "InventoryConditionPackagingDamagedMajor", "InventoryConditionProductDamaged", "InventoryConditionOpened", "InventoryConditionContaminated", "InventoryConditionSpoiled" ] }, "warehouse_enums.InventoryDateMarkKind": { "enum": [ "BEST_BEFORE", "EXPIRY" ], "type": "string", "x-enum-varnames": [ "InventoryDateMarkBestBefore", "InventoryDateMarkExpiry" ] }, "warehouse_enums.InventoryDisposition": { "enum": [ "STANDARD_SELLABLE", "REDUCED_SELLABLE", "QUALITY_HOLD", "QUARANTINED", "BLOCKED", "RECALLED", "RETURN_TO_VENDOR", "SCRAP" ], "type": "string", "x-enum-varnames": [ "InventoryDispositionStandardSellable", "InventoryDispositionReducedSellable", "InventoryDispositionQualityHold", "InventoryDispositionQuarantined", "InventoryDispositionBlocked", "InventoryDispositionRecalled", "InventoryDispositionReturnToVendor", "InventoryDispositionScrap" ] }, "warehouse_enums.PackingDamageHandling": { "enum": [ "replace_from_stock", "short_ship_refund" ], "type": "string", "x-enum-varnames": [ "PackingDamageReplaceFromStock", "PackingDamageShortShipRefund" ] }, "warehouse_enums.PackingDiscrepancyKind": { "enum": [ "shortage", "overweight", "damaged", "pending" ], "type": "string", "x-enum-varnames": [ "PackingDiscrepancyKindShortage", "PackingDiscrepancyKindOverweight", "PackingDiscrepancyKindDamaged", "PackingDiscrepancyKindPending" ] } }, "securitySchemes": { "BearerAuth": { "description": "Backend-Identity-issued HS256 user JWT whose session_id is introspected with Identity on every protected request. Send as: `Bearer \u003ctoken\u003e`.", "in": "header", "name": "Authorization", "type": "apiKey" }, "ServiceBearerAuth": { "bearerFormat": "JWT", "description": "Service access token issued by Backend-Identity's client-credentials flow (aud=internal, route-specific scope).", "scheme": "bearer", "type": "http" } } }, "externalDocs": { "description": "", "url": "" }, "info": { "contact": { "name": "Potato Mart Platform Team" }, "description": "Potato Mart Backend-Payments service (money path, split from\nBackend-Orders). Owns payments, provider sessions, refunds and\nthe over-refund reservation guard, refund requests, invoices,\nEFTPOS terminals and settlements, and buyer-finance projections.\nOrder/refund state changes are published to Pub/Sub. Every\nresponse uses the shared envelope\n`{ \"success\": bool, \"data\": ..., \"error\": ... }`.", "license": { "name": "Proprietary" }, "title": "Backend-Payments API", "version": "46.6.0" }, "openapi": "3.1.0", "paths": { "/audit-logs": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "List audit log entries", "tags": [ "audit" ] } }, "/invoices": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "List invoices", "tags": [ "invoices" ] }, "post": { "description": "Generates an invoice for a paid order. An order paid in the legacy system (Orders import tagged legacy-external-payment) already has its legacy documents and is refused 409 with details.reason legacy_external_payment.", "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "Generate an invoice", "tags": [ "invoices" ] } }, "/invoices/adjustment-notes/by-refund/{refundID}": { "get": { "parameters": [ { "description": "refundID", "in": "path", "name": "refundID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "Get the adjustment note issued for a refund", "tags": [ "invoices" ] } }, "/invoices/by-order/{orderNumber}": { "get": { "parameters": [ { "description": "orderNumber", "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "List an order's invoices", "tags": [ "invoices" ] } }, "/invoices/{invoiceNumber}": { "get": { "parameters": [ { "description": "invoiceNumber", "in": "path", "name": "invoiceNumber", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "Get an invoice by number", "tags": [ "invoices" ] } }, "/invoices/{invoiceNumber}/issue": { "post": { "parameters": [ { "description": "invoiceNumber", "in": "path", "name": "invoiceNumber", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "Issue a draft invoice", "tags": [ "invoices" ] } }, "/invoices/{invoiceNumber}/void": { "post": { "parameters": [ { "description": "invoiceNumber", "in": "path", "name": "invoiceNumber", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "Void an invoice", "tags": [ "invoices" ] } }, "/me/account-balance": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "Get the caller's account balance", "tags": [ "buyer-finance" ] } }, "/me/account-ledger": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "Get the caller's account ledger", "tags": [ "buyer-finance" ] } }, "/me/invoices": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "List the caller's invoices", "tags": [ "invoices" ] } }, "/me/invoices/{invoiceNumber}/pay-card": { "post": { "parameters": [ { "description": "invoiceNumber", "in": "path", "name": "invoiceNumber", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "idempotency_key": { "maxLength": 200, "type": "string" } }, "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_invoices.InvoiceCardPaymentResult" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Conflict" }, "503": { "content": { "application/json": { "schema": { "properties": { "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "required": [ "success", "error" ], "type": "object" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Start a card payment for the caller's invoice", "tags": [ "invoices" ] } }, "/me/orders/{orderNumber}/invoice": { "get": { "parameters": [ { "description": "orderNumber", "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "Get the caller's order invoice", "tags": [ "invoices" ] }, "post": { "parameters": [ { "description": "orderNumber", "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "Generate the caller's order invoice", "tags": [ "invoices" ] } }, "/me/orders/{orderNumber}/payment-summary": { "get": { "description": "Customers require order ownership or the applicable wholesale order visibility permission. Staff require payment.read and matching authoritative order geography.", "parameters": [ { "description": "orderNumber", "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payment.CustomerPaymentSummary" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "Get the caller's order payment summary", "tags": [ "payments" ] } }, "/me/payment-methods": { "get": { "description": "Returns Stripe-owned display summaries only: opaque id, brand, last four, expiry and default state.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_paymentmethods.List" } } }, "description": "OK" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_apiresponse.Error" } } }, "description": "Forbidden" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_apiresponse.Error" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "List my saved payment methods", "tags": [ "payment-methods" ] } }, "/me/payment-methods/bootstrap": { "post": { "description": "Returns short-lived Stripe CustomerSession and SetupIntent client secrets for the authenticated account. No PAN or CVC is handled by Potato Mart.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_paymentmethods.Bootstrap" } } }, "description": "OK" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_apiresponse.Error" } } }, "description": "Forbidden" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_apiresponse.Error" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create saved-payment bootstrap secrets", "tags": [ "payment-methods" ] } }, "/me/payment-methods/{id}": { "delete": { "parameters": [ { "description": "Stripe payment method id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_apiresponse.Error" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Delete my saved payment method", "tags": [ "payment-methods" ] } }, "/me/payment-methods/{id}/default": { "put": { "parameters": [ { "description": "Stripe payment method id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_apiresponse.Error" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Set my default saved payment method", "tags": [ "payment-methods" ] } }, "/me/refund-requests": { "post": { "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "Raise a self-service refund request", "tags": [ "refund-requests" ] } }, "/me/statements/current": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "Get the caller's current statement", "tags": [ "buyer-finance" ] } }, "/payments": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "List payments", "tags": [ "payments" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payments.RecordManualInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "Record a manual (cash/bank-transfer) payment", "tags": [ "payments" ] } }, "/payments/bank-transfer": { "post": { "description": "Requires payment.capture and the order within the caller's geographic scope. Records one completed BANK_TRANSFER payment (method bank_transfer) that settles the order's full remaining amount due: transfer_amount must equal it exactly. confirmed_partial still completes the payment for the full amount and only flags it for finance follow-up. Every evidence code must be finalized for the same order and not attached to another payment; the codes are attached in the payment's own transaction. Cash and bank transfer never mix on one order. idempotency_key is required; an exact retry returns the original payment and a changed retry conflicts. POST /payments keeps accepting method bank_transfer (provider MANUAL_ADJUSTMENT) for older POS builds. Refunds of a BANK_TRANSFER payment execute as manual adjustments.", "operationId": "recordBankTransferPayment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payments.RecordBankTransferInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/payment.Payment" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Recorded payment, including an exact replay of the original" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR (unknown field, missing order_number or idempotency_key, non-positive transfer_amount, unknown confirmation_status, 0 or more than 5 or repeated evidence codes, over-long payer_reference or customer fields)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "FORBIDDEN without payment.capture, a usable scope, an identified staff user, or with the order outside the caller's scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "NOT_FOUND when the order does not exist" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT. details.reason amount_not_remaining_due (with details.remaining_due_minor and details.currency) or evidence_unavailable (with details.code when known); also a changed retry, an already-paid order, a cash tender on the order, or capture headroom lost to a concurrent payment." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "EVIDENCE_STORAGE_UNAVAILABLE while no private evidence bucket is configured" } }, "security": [ { "BearerAuth": [] } ], "summary": "Record a staff-confirmed bank transfer with photo evidence", "tags": [ "payments" ] } }, "/payments/bank-transfer/evidence/upload-url": { "post": { "description": "Requires payment.capture and the order within the caller's geographic scope. Records a pending evidence object bound to the order and returns a V4 signed PUT URL to the private evidence bucket. The uploader must PUT the raw bytes with exactly the returned headers (Content-Type is bound into the signature) before expires_at, then finalize. Accepts image/jpeg, image/png, image/webp, image/heic and application/pdf up to 10 MiB.", "operationId": "requestBankTransferEvidenceUpload", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/media.UploadRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/media.UploadURL" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Signed upload grant, with Cache-Control no-store" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR (unknown field, missing order_number, details.reason mime_type_not_allowed or size_out_of_range, over-long filename)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "FORBIDDEN without payment.capture, an identified staff user, or with the order outside the caller's scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "NOT_FOUND when a scoped caller names an order that does not exist" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "EVIDENCE_STORAGE_UNAVAILABLE while no private evidence bucket is configured or URL signing fails" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a signed upload URL for bank-transfer evidence", "tags": [ "payments" ] } }, "/payments/bank-transfer/evidence/{code}/finalize": { "post": { "description": "Requires payment.capture and the evidence's order within the caller's geographic scope. Heads the uploaded object, enforces the 10 MiB limit and the requested content type, streams that exact generation through SHA-256 and activates the evidence when it equals the submitted digest. A rejected upload is deleted; request a new upload URL. Finalizing an active object again with the same digest returns it unchanged.", "operationId": "finalizeBankTransferEvidence", "parameters": [ { "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/media.FinalizeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/media.Evidence" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Active evidence" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR with details.reason sha256_invalid, evidence_empty, evidence_too_large (details.max_bytes), evidence_content_type_mismatch, evidence_size_mismatch or evidence_sha256_mismatch; the rejected object is deleted" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "FORBIDDEN without payment.capture, an identified staff user, or with the order outside the caller's scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "NOT_FOUND for an unknown evidence code" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT with details.reason evidence_not_uploaded, evidence_expired (rejected or reaped; request a new upload URL) or evidence_already_finalized (a different digest)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "EVIDENCE_STORAGE_UNAVAILABLE while no private evidence bucket is configured or the bucket cannot be read" } }, "security": [ { "BearerAuth": [] } ], "summary": "Verify an uploaded evidence object", "tags": [ "payments" ] } }, "/payments/by-order/{orderNumber}": { "get": { "parameters": [ { "description": "orderNumber", "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "List an order's payments", "tags": [ "payments" ] } }, "/payments/eftpos": { "post": { "description": "Records a completed Linkly or mx51 terminal payment. The optional provider selector defaults to Linkly when omitted or empty. Payment.provider is LINKLY_POS or MX51_POS; provider_reference.mx51 retains the terminal reference fields for either provider. Cashout remains a separate withdrawal. POS tills accept neither tips nor card surcharges: a non-zero tip_minor or surcharge_minor is refused with 400 VALIDATION and details.reason tip_not_accepted or surcharge_not_accepted, before any lookup or write. Exact retries return the original payment; changed capture identity conflicts. Terminal provider operations remain unavailable while TERMINAL_PROVIDER_ENABLED is false.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payments.RecordEFTPOSInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/payment.Payment" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Recorded payment, including an exact replay of the original capture" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "Invalid provider, method or capture input, or a refused tip or surcharge (details.reason tip_not_accepted or surcharge_not_accepted)" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "Changed capture identity or conflicting order balance" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "Terminal provider disabled or authoritative dependency unavailable" } }, "summary": "Record an EFTPOS terminal payment", "tags": [ "payments" ] } }, "/payments/payto/return": { "get": { "parameters": [ { "description": "Stripe Checkout Session id", "in": "query", "name": "session_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "text/html": { "schema": { "type": "string" } } }, "description": "return page" }, "400": { "content": { "text/html": { "schema": { "type": "string" } } }, "description": "invalid callback" }, "503": { "content": { "text/html": { "schema": { "type": "string" } } }, "description": "Stripe could not be reached; the shopper can retry" } }, "summary": "Return from Stripe-hosted PayTo", "tags": [ "payments" ] } }, "/payments/recovery/lookup": { "post": { "description": "Read-only recovery lookup requiring payment.read and staff geographic scope. Both order_number and idempotency_key must match the same stored payment within that scope. No charge, retry, reconciliation write, or key in URL logs. The returned identity is not proof of settlement; read authoritative payment and order outcomes before unlocking. A 404 never proves a payment was not attempted.", "operationId": "lookupPaymentRecovery", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payments.RecoveryLookupInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payments.RecoveryLookupResponse" } } }, "description": "Exact scoped identity, with Cache-Control no-store." }, "400": { "description": "Invalid or incomplete identity" }, "401": { "description": "Authentication required" }, "403": { "description": "Missing payment.read or unusable staff scope" }, "404": { "description": "No exact scoped match" }, "500": { "description": "Recovery authority unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Read payment identity by original key and order", "tags": [ "payments" ] } }, "/payments/settings/payto": { "get": { "description": "Requires payment.read. A setting that has never been written reads as enabled. This is the stored value; other instances can keep serving their cached value for up to a minute after a change.", "operationId": "getPayToSettings", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/payments.PayToSettings" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Current switch state" }, "401": { "description": "Authentication required" }, "403": { "description": "Missing payment.read or unusable staff scope" }, "503": { "description": "Setting cannot be read; PayTo is hidden until it can" } }, "security": [ { "BearerAuth": [] } ], "summary": "Read the PayTo off-switch", "tags": [ "payments" ] }, "put": { "description": "Requires commerce.config. New PayTo sessions stop within about a minute of switching off, and sessions already open can still complete. Card and Link are unaffected. STRIPE_PAYTO_ENABLED must also be on for PayTo to be offered.", "operationId": "putPayToSettings", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payments.PayToSettingsInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/payments.PayToSettings" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Saved switch state" }, "400": { "description": "Missing enabled", "or a missing or over-long reason": null }, "401": { "description": "Authentication required" }, "403": { "description": "Missing commerce.config or unusable staff scope" }, "503": { "description": "Setting cannot be saved" } }, "security": [ { "BearerAuth": [] } ], "summary": "Switch PayTo on or off", "tags": [ "payments" ] } }, "/payments/stats/stripe": { "get": { "description": "Requires payment.read. Totals include only payments within the caller's geographic scope, before aggregation.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "Aggregate Stripe fee statistics", "tags": [ "payments" ] } }, "/payments/{id}": { "get": { "parameters": [ { "description": "id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "Get a payment by id", "tags": [ "payments" ] } }, "/payments/{id}/bank-transfer/evidence/{code}/download-url": { "get": { "description": "Requires payment.read and the payment within the caller's geographic scope. The payment must cite the evidence code in provider_reference.bank_transfer.evidence. Returns a V4 signed GET for the exact verified object generation, valid for GCS_DOWNLOAD_URL_TTL (default 5 minutes).", "operationId": "getBankTransferEvidenceDownloadURL", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/media.DownloadURL" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Signed download URL, with Cache-Control no-store" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "FORBIDDEN without payment.read or a usable scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "NOT_FOUND when the payment is missing or outside scope, or does not cite the evidence" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "EVIDENCE_STORAGE_UNAVAILABLE while no private evidence bucket is configured or URL signing fails" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a short-lived signed URL to view saved evidence", "tags": [ "payments" ] } }, "/payments/{id}/events": { "get": { "parameters": [ { "description": "id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "List a payment's event timeline", "tags": [ "payments" ] } }, "/payments/{id}/resolution": { "post": { "description": "Requires refund.approve and the caller's geographic scope. Finalizes a pending, processing, awaiting_action or unknown record as failed or cancelled, releases its capture headroom, and appends an immutable payment.resolved event with actor, reason, evidence_ref, prior_status and resolution_outcome, visible through GET /payments/{id}/events. The unpaid-cancellation and amendment fences then stop treating the record as unresolved. Refused when any evidence shows a capture or an unconfirmed terminal or provider result; a Stripe record needs Stripe to report it canceled or expired. An identical retry returns the record. A provider capture arriving after resolution is not applied; it is recorded as an unsuccessful event and refunded.", "parameters": [ { "description": "id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payments.resolvePaymentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "additionalProperties": true, "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Record resolved, or an identical earlier resolution returned unchanged" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR (unknown field, malformed JSON, outcome other than failed or cancelled, missing or over-long reason or evidence_ref, missing expected_updated_at)" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "FORBIDDEN without refund.approve or a usable geographic scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "NOT_FOUND when the record is missing or outside the caller's geographic scope" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT with details.reason naming the refusal. payment_not_resolvable, payment_changed, resolution_differs, order_payment_state_busy, capture_evidence, provider_reference_unverifiable, terminal_outcome_unresolved or provider_payment_not_cancelled" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "SERVICE_UNAVAILABLE when Stripe cannot confirm a Stripe record's status" } }, "summary": "Resolve a stuck payment record", "tags": [ "payments" ] } }, "/pos/orders/{orderNumber}/receipt": { "get": { "description": "Requires pos.access. Restricted staff must match the receipt's original register session and frozen market, depot and register attribution. Closed sessions remain valid; missing or contradictory evidence is not found. Global staff retain access without a session lookup.", "parameters": [ { "description": "orderNumber", "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "receipt not found" } }, "summary": "Read the immutable POS receipt for an order", "tags": [ "pos" ] } }, "/pos/orders/{orderNumber}/receipt/deliveries": { "post": { "description": "Requires pos.access and admits exactly the callers that may read the receipt (GET /pos/orders/{orderNumber}/receipt); restricted staff outside the receipt's original session get 404. Email only. A typed email wins and is used for this receipt only; Payments passes it to Notification and stores it nowhere. Without one, the retail customer frozen with the receipt is the destination, and Notification resolves the address. A walk-in sale without a typed email is refused with details.reason destination_required. Payments renders nothing and stores nothing; it hands the stored receipt snapshot to Backend-Notification, which owns idempotency on idempotency_key and the per-order send limit, and answers once the email is queued. Until NOTIFICATION_BASE_URL is configured (and Identity grants svc-payments notifications:dispatch:receipt) the route answers 503 receipt_delivery_unavailable without reading or sending anything.", "operationId": "deliverPOSReceipt", "parameters": [ { "description": "orderNumber", "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/receipts.DeliverReceiptInput" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/receipts.ReceiptDelivery" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Notification accepted the receipt and queued the email. Repeating the same idempotency_key and body returns the same delivery." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR for an unknown field, malformed JSON, an invalid email, a missing or non-UUID idempotency_key, or an unsupported locale. details.reason is unsupported_channel for any channel other than email, and destination_required for a walk-in sale without a typed email." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "Missing pos.access or unusable staff scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "NOT_FOUND \"receipt not found\" when the order has no receipt or the caller may not read it" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT with details.reason idempotency_conflict when the idempotency_key was already used with a different request" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR with details.reason customer_email_unavailable when the bound customer cannot be emailed; details.upstream_reason is Notification's reason (retail_customer_not_found, customer_identity_not_found, customer_identity_inactive or no_deliverable_email). Ask for an address and send it as email." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "TOO_MANY_REQUESTS with details.reason receipt_delivery_rate_limited when the order reached Notification's send limit (5 per order per hour). details.retry_after_seconds is Notification's wait rounded up to whole seconds and matches Retry-After when present.", "headers": { "Retry-After": { "description": "Seconds to wait, when Notification gave a usable wait", "schema": { "type": "integer" } } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "INTERNAL_ERROR with details.reason receipt_delivery_rejected when Notification rejected the request Payments built, or the receipt lookup failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "SERVICE_UNAVAILABLE with details.reason receipt_delivery_unavailable when delivery is not configured, Payments' service token is missing or lacks the scope (401/403 from Notification), Notification or its Customers/Identity lookups are unavailable, or no definitive answer came back. The outcome is unknown; retry with the same idempotency_key." } }, "security": [ { "BearerAuth": [] } ], "summary": "Email the POS receipt for an order", "tags": [ "pos" ] } }, "/pos/refund-recovery/refusal": { "get": { "description": "Requires staff pos.access and refund.read plus authoritative order geography. Missing proof does not establish financial failure and must never unlock a refund journal.", "parameters": [ { "in": "query", "name": "order_number", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "idempotency_key", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/refunds.AdmissionRefusal" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Immutable cancellation proof" }, "400": { "description": "Invalid input" }, "403": { "description": "Permission or geography denied" }, "404": { "description": "No matching cancellation proof" }, "503": { "description": "Authoritative evidence unavailable" } }, "summary": "Read exact refund admission cancellation evidence", "tags": [ "pos" ] }, "post": { "description": "Requires staff pos.access and refund.write plus authoritative order geography. Atomically prevents any future refund admission using this key. Does not assert a historical provider outcome, move money, or clear an existing refund. Only exclusively terminal captured sources qualify. Existing financial admission or a different actor/order binding returns 409. All active writer versions must enforce admission fences before this operation is enabled operationally.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refunds.AdmissionRecoveryInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/refunds.AdmissionRefusal" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Durable cancellation proof, including identical replay" }, "400": { "description": "Invalid canonical order or UUID" }, "403": { "description": "Permission or geography denied" }, "409": { "description": "Identity already admitted, incompatible recovery binding, or source is not exclusively terminal" }, "503": { "description": "Recovery unavailable or outcome uncertain; read proof before further action" } }, "summary": "Cancel admission of an unadmitted generic terminal refund identity", "tags": [ "pos" ] } }, "/pos/refunds": { "post": { "description": "Reverses an in-person payment (cash, manual record, or a terminal transaction) from a register. Payments taken through the online gateway - card, QR, Apple Pay, Google Pay, PayTo and Link - are refused with 403; refund those through POST /refunds and the refund request/approval flow. Immediate POS execution requires both pos.access and refund.write. With destination.kind=new_gift_card the same amount is instead issued as a new gift card (see refunds.RefundDestination); the in-person payment rule still applies, no terminal or gateway is called, and a bearer card's claim_code is returned in data.gift_card_issuance. An exact replay of the idempotency_key returns the same refund and, while the bearer card is unclaimed, its claim_code again. An order paid in the legacy system (Orders import tagged legacy-external-payment) is refunded manually through POST /refunds; here it is refused 409 with details.reason legacy_external_payment.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refunds.CreateInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_modules_refunds.Refund" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" }, "403": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "the target payment is an online payment and cannot be refunded from the point of sale" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "Idempotency, authority or gift-card destination conflict; see error.details.reason" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "Gift-card issuance outcome unknown or unavailable; the refund stays reserved, retry the same idempotency_key" } }, "summary": "Create a refund from the point of sale", "tags": [ "pos" ] } }, "/pos/registers": { "get": { "description": "Returns only registers matching the complete authenticated geographic path, including state. Unresolved legacy geography remains inaccessible to narrower grants. Archived registers are omitted unless include_archived=true.", "parameters": [ { "description": "Include archived registers (audit view). Archived registers are excluded by default.", "in": "query", "name": "include_archived", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/internal_modules_posregisters.registerResponse" }, "type": "array" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR when include_archived is not true or false" } }, "summary": "List POS registers", "tags": [ "pos" ] }, "post": { "description": "Resolves complete depot geography through Supply before authorization. Client country must agree with Supply; state is never inferred from the depot code.", "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "Create a POS register", "tags": [ "pos" ] } }, "/pos/registers/{registerId}/archive": { "post": { "description": "Requires pos.access (the same permission as register creation) and the caller's geographic scope. Sets status archived with archived_at, archived_by and archive_reason. Idempotent. Archived registers are hidden from GET /pos/registers unless include_archived=true and cannot open sessions (409 REGISTER_ARCHIVED); their sessions, cash movements and X/Z totals remain readable. Terminal connections bound to the register are left unchanged and can be moved with terminal-connection reassignment.", "parameters": [ { "description": "registerId", "in": "path", "name": "registerId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posregisters.archiveRegisterReq" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_posregisters.registerResponse" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Register archived, or the already-archived register returned unchanged" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR (unknown field, malformed JSON, reason longer than 500 characters)" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "NOT_FOUND when the register is missing or outside the caller's geographic scope" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "REGISTER_HAS_OPEN_SESSION (details.session_id names the open session) or TERMINAL_BUSY (an unresolved cloud terminal transaction or hold on the register)" } }, "summary": "Archive a POS register", "tags": [ "pos" ] } }, "/pos/registers/{registerId}/sessions": { "get": { "description": "Requires pos.access and the caller's geographic scope. A register runs several sequential sessions per business date, at most one open at a time; this lists every session (open or closed) of one business date.", "operationId": "listRegisterSessions", "parameters": [ { "description": "registerId", "in": "path", "name": "registerId", "required": true, "schema": { "type": "string" } }, { "description": "Business date (YYYY-MM-DD) whose sessions are listed", "in": "query", "name": "business_date", "required": true, "schema": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/internal_modules_posregisters.registerSessionResponse" }, "type": "array" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "The register's sessions on the business date ordered by sequence ascending; an empty array when there are none" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR when business_date is missing or not YYYY-MM-DD" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "FORBIDDEN without pos.access or when the caller scope cannot be applied to point-of-sale records" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "NOT_FOUND when the register is missing or outside the caller's geographic scope" } }, "summary": "List a register's sessions for a business date", "tags": [ "pos" ] }, "post": { "description": "Requires pos.session.manage. Opens the register's next session for the business date (default today in Melbourne, Australia/Melbourne). A register has at most one open session; after it closes, another session may open on the same business date with the next sequence. The new session opens at the later of now and the register's latest close, and a closed session's X/Z window ends exclusively at its closed_at, so sequential windows never overlap and an activity stamped exactly at the previous closed_at is never counted in the closed session.", "parameters": [ { "description": "registerId", "in": "path", "name": "registerId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posregisters.openSessionReq" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "REGISTER_HAS_OPEN_SESSION when the register already has an open session (details.session_id names it when visible); REGISTER_ARCHIVED when the register is archived; CONFLICT \"register already has a session for this business date\" only while the retired one-session-per-business-date index is still present in the database" } }, "summary": "Open the register's next session for a business date", "tags": [ "pos" ] } }, "/pos/registers/{registerId}/sessions/current": { "get": { "parameters": [ { "description": "registerId", "in": "path", "name": "registerId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "summary": "Get the current open session for a register", "tags": [ "pos" ] } }, "/pos/sessions/{sessionId}": { "delete": { "description": "Requires pos.session.manage and the caller's geographic scope. Hard-deletes an open or closed session only when no cash movement, cloud terminal transaction or hold, POS payment, terminal refund or receipt references it; the checks and the delete run in one transaction. Deleting frees the register's business date, so a new session can be opened for the same date.", "parameters": [ { "description": "sessionId", "in": "path", "name": "sessionId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_posregisters.DeletedSession" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Session deleted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "NOT_FOUND when the session is missing or outside the caller's geographic scope" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "SESSION_NOT_EMPTY; details.references is a comma-separated list of cloud_terminal_active, cash_movements, cloud_terminal_transactions, payments, terminal_refunds, receipts" } }, "summary": "Delete an empty register session", "tags": [ "pos" ] }, "get": { "parameters": [ { "description": "sessionId", "in": "path", "name": "sessionId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "summary": "Get a register session", "tags": [ "pos" ] } }, "/pos/sessions/{sessionId}/cash-movements": { "get": { "parameters": [ { "description": "sessionId", "in": "path", "name": "sessionId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "summary": "List cash-drawer movements for a session", "tags": [ "pos" ] }, "post": { "parameters": [ { "description": "sessionId", "in": "path", "name": "sessionId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posregisters.cashMovementReq" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "Record a cash-drawer movement", "tags": [ "pos" ] } }, "/pos/sessions/{sessionId}/close": { "post": { "description": "After the close commits, the register's idle cloud terminal connections (Stripe Terminal and Linkly Cloud) are released so another register in the depot can claim them, audited with the closing user. A connection with an active or unresolved transaction stays assigned, and a failed release is logged without failing the close. A POS that keeps trading on the register after opening its next session claims its terminal again.", "parameters": [ { "description": "sessionId", "in": "path", "name": "sessionId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posregisters.closeSessionReq" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "409": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "unresolved terminal transactions" } }, "summary": "Close a register session", "tags": [ "pos" ] } }, "/pos/sessions/{sessionId}/totals/x": { "get": { "parameters": [ { "description": "sessionId", "in": "path", "name": "sessionId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "session not found" } }, "summary": "Read a session X/Z totals snapshot", "tags": [ "pos" ] } }, "/pos/sessions/{sessionId}/totals/z": { "get": { "parameters": [ { "description": "sessionId", "in": "path", "name": "sessionId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Payments_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "session not found" } }, "summary": "Read a session X/Z totals snapshot", "tags": [ "pos" ] } }, "/pos/terminal-connections": { "get": { "description": "Lists the register's own connections followed by the shared readers (shared true, with reader_state) of the register's depot, market and country that the caller's scope covers. Every register of the depot may use a shared reader without claiming it.", "operationId": "listPOSTerminalConnections", "parameters": [ { "in": "query", "name": "register_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.ConnectionsResponse" } } }, "description": "Authoritative terminal state" }, "400": { "description": "Malformed request" }, "401": { "description": "Authentication required" }, "403": { "description": "POS and terminal permission required; refunds additionally require refund.write" }, "404": { "description": "Resource unavailable in caller geography" }, "409": { "description": "Identity, occupancy, authority or revision conflict" }, "503": { "description": "Recovery required; do not start a replacement transaction" } }, "security": [ { "BearerAuth": [] } ], "summary": "listPOSTerminalConnections", "tags": [ "POSTerminals" ] }, "post": { "operationId": "createPOSTerminalConnection", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.ConnectionInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.ConnectionResponse" } } }, "description": "Authoritative terminal state" }, "400": { "description": "Malformed request" }, "401": { "description": "Authentication required" }, "403": { "description": "POS and terminal permission required; refunds additionally require refund.write" }, "404": { "description": "Resource unavailable in caller geography" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.ConnectionConflictResponse" } } }, "description": "CONFLICT with error.details.reason naming the refusal. stripe_terminal_disabled, linkly_cloud_disabled, reader_busy, reader_already_assigned, register_provider_occupied or invalid_connection_request. reader_already_assigned and register_provider_occupied add register_id, connection_id and retired for an occupant inside the caller's geographic scope" }, "503": { "description": "Recovery required; do not start a replacement transaction" } }, "security": [ { "BearerAuth": [] } ], "summary": "createPOSTerminalConnection", "tags": [ "POSTerminals" ] } }, "/pos/terminal-connections/available": { "get": { "description": "Lists connections released by any register in the given register's depot, market and country and visible to the caller's geographic scope, with live readiness and takeover_eligible false. It also lists connections still assigned to another register of that depot that may be claimed with takeover true, with owner_register_id and takeover_eligible true; such a connection's owner register has no open session, and the connection holds no active or unresolved transaction or utility lease and its reader is not busy. The register's own connections are never listed. The depot's shared readers are listed too, with shared true, reader_state and takeover_eligible false; they are used without a claim (a claim is refused with connection_shared). A claim can still be refused, for example register_provider_occupied when the register already holds a connection for that provider, or stale_revision. Requires pos.access and terminal.transact. Returns an empty array when none qualify.", "operationId": "listAvailablePOSTerminalConnections", "parameters": [ { "description": "Active register that would claim a terminal", "in": "query", "name": "register_id", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.ConnectionsResponse" } } }, "description": "Released and takeover-eligible connections in the register's depot" }, "400": { "description": "VALIDATION_ERROR when register_id is missing" }, "401": { "description": "Authentication required" }, "403": { "description": "POS and terminal permission required" }, "404": { "archived or outside the caller's geography": null, "description": "Register missing" }, "503": { "description": "Terminal storage unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "List cloud terminals a register may claim, including takeover candidates", "tags": [ "POSTerminals" ] } }, "/pos/terminal-connections/{id}": { "patch": { "operationId": "updatePOSTerminalConnection", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.ConnectionPatch" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.ConnectionResponse" } } }, "description": "Authoritative terminal state" }, "400": { "description": "Malformed request" }, "401": { "description": "Authentication required" }, "403": { "description": "POS and terminal permission required; refunds additionally require refund.write" }, "404": { "description": "Resource unavailable in caller geography" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.SharedReaderConflictResponse" } } }, "description": "Identity, occupancy, authority or revision conflict. A change of shared names its refusal in error.details.reason (transaction_active, reader_busy, reader_held, reader_queue_not_empty, stale_revision, sandbox_retired or invalid_connection_request)." }, "503": { "description": "Recovery required; do not start a replacement transaction" } }, "security": [ { "BearerAuth": [] } ], "summary": "updatePOSTerminalConnection", "tags": [ "POSTerminals" ] } }, "/pos/terminal-connections/{id}/claim": { "post": { "description": "Assigns a released connection to register_id. The register must be\nactive, visible to the caller and in the connection's depot, market and\ncountry, and must not already hold a connection for the same provider.\nA Stripe reader must be idle. The write is a compare-and-swap on\nexpected_revision, so two registers claiming one terminal produce one\nowner and one conflict. Requires pos.access and terminal.transact.\n\nWith takeover true the connection may instead still be assigned to\nanother register (its owner), for example one whose session was never\nclosed with a sign-off. The same depot, occupancy, revision and reader\nrules apply, and in addition the owner register must have no open\nsession (owner_session_open) and the connection must hold no active or\nunresolved transaction, reprint or pairing lease (transaction_active).\nThe owner check and the move commit in one transaction that serializes\nwith the owner opening a session. The audit records the actor, the\nprevious register and takeover. Retrying a takeover that already moved\nthe connection to register_id returns it unchanged. takeover true on a\nreleased connection is an ordinary claim. Without takeover the claim\nbehaves as before.\n", "operationId": "claimPOSTerminalConnection", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.AssignmentInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.ConnectionResponse" } } }, "description": "Claimed connection with incremented revision and live readiness" }, "400": { "a non-positive expected_revision or a non-boolean takeover; unknown fields are rejected": null, "description": "VALIDATION_ERROR for a blank register_id" }, "401": { "description": "Authentication or audit actor required" }, "403": { "description": "POS and terminal permission required" }, "404": { "archived or outside the caller's geography": null, "description": "Connection or register missing" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.AssignmentConflictResponse" } } }, "description": "CONFLICT with error.details.reason not_released (assigned and takeover not requested), owner_session_open (takeover only), depot_mismatch, register_provider_occupied, stale_revision, reader_busy, transaction_active, connection_shared or sandbox_retired" }, "503": { "description": "Stripe Terminal unavailable or terminal storage unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Claim a released cloud terminal, or take over an idle one, for a register in the same depot", "tags": [ "POSTerminals" ] } }, "/pos/terminal-connections/{id}/last-transaction": { "get": { "description": "Retrieves provider status by the last persisted session UUID without a TxnRef. Does not discover activity outside this integration or dispatch a new financial transaction.", "operationId": "getPOSLinklyLastTransaction", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.TransactionResponse" } } }, "description": "Authoritative transaction snapshot" }, "401": { "description": "Authentication required" }, "403": { "description": "POS and terminal permission required" }, "404": { "description": "No dispatched transaction or unavailable in caller geography" }, "409": { "description": "Provider identity or result conflict" }, "503": { "description": "Provider status unavailable; retain original identity" } }, "security": [ { "BearerAuth": [] } ], "summary": "Read the last Linkly session dispatched by this POS connection", "tags": [ "POSTerminals" ] } }, "/pos/terminal-connections/{id}/pairing": { "post": { "operationId": "pairPOSLinklyConnection", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.PairingInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.ConnectionResponse" } } }, "description": "Authoritative terminal state" }, "401": { "description": "Authentication required" }, "403": { "description": "POS and terminal permission required" }, "404": { "description": "Resource unavailable in caller geography" }, "409": { "description": "Occupancy or identity conflict" }, "503": { "description": "Uncertain provider outcome; retain original identity" } }, "security": [ { "BearerAuth": [] } ], "summary": "pairPOSLinklyConnection", "tags": [ "POSTerminals" ] } }, "/pos/terminal-connections/{id}/queue": { "post": { "description": "Appends register_id to the shared reader's queue. Idempotent: a register\nalready queued keeps its place and the call returns the state\nunchanged. The register must have the open session session_id and be\nin the reader's depot, market and country. Waiting has no time limit;\nwhen the reader is free the queue head gets a 10 second turn (see\nReaderState). Requires pos.access and terminal.transact.\n", "operationId": "joinPOSSharedReaderQueue", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.ReaderQueueJoin" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.ReaderStateResponse" } } }, "description": "Shared reader state after the join" }, "400": { "description": "VALIDATION_ERROR for a blank register_id or session_id; unknown fields are rejected" }, "401": { "description": "Authentication required" }, "403": { "description": "POS and terminal permission required" }, "404": { "description": "Connection", "register or session missing or outside the caller's geography": null }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.SharedReaderConflictResponse" } } }, "description": "CONFLICT with error.details.reason connection_not_shared, depot_mismatch, session_not_open, invalid_connection_request (a session of another register) or sandbox_retired" }, "503": { "description": "Terminal storage unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Queue a register for a shared reader", "tags": [ "POSTerminals" ] } }, "/pos/terminal-connections/{id}/queue/leave": { "post": { "description": "Removes register_id from the shared reader's queue and gives up its turn\nor hold, if it has one; the next queued register then gets the turn.\nIdempotent: leaving when not queued returns the state unchanged. A\nregister session close does the same for every shared reader.\nRequires pos.access and terminal.transact.\n", "operationId": "leavePOSSharedReaderQueue", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.ReaderQueueLeave" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.ReaderStateResponse" } } }, "description": "Shared reader state after the leave" }, "400": { "description": "VALIDATION_ERROR for a blank register_id; unknown fields are rejected" }, "401": { "description": "Authentication required" }, "403": { "description": "POS and terminal permission required" }, "404": { "description": "Connection or register missing or outside the caller's geography" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.SharedReaderConflictResponse" } } }, "description": "CONFLICT with error.details.reason connection_not_shared, depot_mismatch or sandbox_retired" }, "503": { "description": "Terminal storage unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Remove a register from a shared reader's queue", "tags": [ "POSTerminals" ] } }, "/pos/terminal-connections/{id}/reassignment": { "post": { "description": "Requires terminal-management permission and geographic access to source and target. Preserves pairing identity and all historical transactions. Unresolved transactions and utility or pairing occupancy block reassignment.", "operationId": "reassignPOSLinklyConnection", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.ReassignmentInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.ConnectionResponse" } } }, "description": "Reassigned connection with incremented revision" }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "POS and terminal-management permission required" }, "404": { "description": "Source or target unavailable in caller geography" }, "409": { "description": "Stale revision, unresolved occupancy or unsupported provider; details.reason connection_released for a released connection, connection_shared for a shared reader" }, "503": { "description": "Authoritative storage unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Reassign an idle Linkly connection to another authorized active register", "tags": [ "POSTerminals" ] } }, "/pos/terminal-connections/{id}/release": { "post": { "description": "Used at sign-off so another register in the same depot can claim the\nterminal. The connection keeps its identity, reader, pairing and\nhistory, stops accepting transactions, and its register_id is omitted\nuntil it is claimed. Requires pos.access and terminal.transact plus\ngeographic access to the connection. Refused while the connection holds\nan active transaction, a reprint or pairing lease, or any terminal\ntransaction that is not completed. Releasing an already released\nconnection from the same register returns it unchanged (safe retry).\nThe write is a compare-and-swap on expected_revision. Closing a\nregister session also releases that register's idle cloud terminal\nconnections, so an explicit release is only needed at sign-off\nwithout a close.\n", "operationId": "releasePOSTerminalConnection", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.AssignmentInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.ConnectionResponse" } } }, "description": "Released connection with incremented revision, or the unchanged released connection on retry" }, "400": { "a non-positive expected_revision or takeover true; unknown fields are rejected": null, "description": "VALIDATION_ERROR for a blank register_id" }, "401": { "description": "Authentication or audit actor required" }, "403": { "description": "POS and terminal permission required" }, "404": { "description": "Connection missing or outside the caller's geography" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.AssignmentConflictResponse" } } }, "description": "CONFLICT with error.details.reason transaction_active, stale_revision, register_mismatch, connection_shared or sandbox_retired" }, "503": { "description": "Terminal storage unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Release a cloud terminal from the register that holds it", "tags": [ "POSTerminals" ] } }, "/pos/terminal-connections/{id}/state": { "get": { "description": "Applies every elapsed deadline of the shared reader (hold, turn, and the\ncard wait of its active purchase, which may cancel it) and returns the\nstored result. Tills waiting for the reader poll this about once per\nsecond. register_id must be a register of the reader's depot, market\nand country. Requires pos.access and terminal.transact.\n", "operationId": "getPOSSharedReaderState", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "The asking register", "in": "query", "name": "register_id", "required": true, "schema": { "maxLength": 128, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.ReaderStateResponse" } } }, "description": "Shared reader state" }, "400": { "description": "VALIDATION_ERROR when register_id is missing" }, "401": { "description": "Authentication required" }, "403": { "description": "POS and terminal permission required" }, "404": { "description": "Connection or register missing or outside the caller's geography" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.SharedReaderConflictResponse" } } }, "description": "CONFLICT with error.details.reason connection_not_shared, depot_mismatch or sandbox_retired" }, "503": { "description": "Terminal storage unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Read a shared reader's state after applying its deadlines", "tags": [ "POSTerminals" ] } }, "/pos/terminal-refunds/outcome": { "post": { "description": "Records an approved Linkly or mx51 refund against its prepared reservation, or releases the reservation after a declined or cancelled terminal outcome. The optional provider defaults to Linkly when omitted or empty and must match both the prepared reservation and captured payment. Provider identity is retained through replay, cancellation and recovery; mismatches conflict. An approved outcome requires provider_transaction_id. The caller must hold both pos.access and refund.write; refund.request alone never moves money.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posTerminalRefundOutcomeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Outcome recorded idempotently" }, "400": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Invalid terminal evidence" }, "409": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Reservation or idempotency conflict" }, "503": { "description": "Terminal provider disabled or authority unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Finalize a prepared POS terminal refund", "tags": [ "pos" ] } }, "/pos/terminal-refunds/prepare": { "post": { "description": "Reserves the exact refundable payment and amount before the local Linkly or mx51 terminal is allowed to move money. The optional provider defaults to Linkly when omitted or empty and must match the captured payment. The canonical provider is frozen into the refund fingerprint and reservation for outcomes and recovery. The caller must hold both pos.access and refund.write; refund.request alone never moves money.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posTerminalRefundPrepareInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Refund authority reserved idempotently" }, "400": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Invalid terminal refund request" }, "409": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Refund is not reservable" }, "503": { "description": "Terminal provider disabled or authority unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Prepare a POS terminal refund", "tags": [ "pos" ] } }, "/pos/terminal-transactions": { "post": { "description": "Client UUID and idempotency identity are immutable. A definitive scoped\nadmission refusal is persisted and returned as completed/cancelled with\nTERMINAL_ADMISSION_REJECTED. A deterministic refund refusal additionally\nproves no reservation before returning TERMINAL_REFUND_REJECTED.\nRefund snapshots expose original_payment_id and preserve requested amount.\nHTTP errors or GET 404 are not proof that an uncertain attempt is absent.\n\nOn a shared reader (Connection.shared) any register of the reader's\ndepot, market and country with an open session may start a purchase\nor refund, when the reader state (evaluated at this request) is free;\nor turn and register_id is turn_register_id; or holding and\nregister_id is holder_register_id and order_number is\nhold_order_number. Otherwise the start is refused with 409\nreader_busy, reader_held or reader_turn_not_yours and no attempt is\nrecorded, so the same transaction_id may be retried. The rule is\nre-checked in the admission transaction with a compare-and-swap on\nthe reader state, so concurrent starts admit exactly one. A started\nregister leaves the queue. A register of another depot gets 409\ndepot_mismatch.\n", "operationId": "startPOSTerminalTransaction", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.StartInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.TransactionResponse" } } }, "description": "Authoritative terminal state" }, "400": { "description": "Malformed request" }, "401": { "description": "Authentication required" }, "403": { "description": "POS and terminal permission required; refunds additionally require refund.write" }, "404": { "description": "Resource unavailable in caller geography" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.SharedReaderConflictResponse" } } }, "description": "Identity, occupancy, authority or revision conflict. On a shared reader error.details.reason is reader_busy, reader_held, reader_turn_not_yours or depot_mismatch." }, "503": { "description": "Recovery required; do not start a replacement transaction" } }, "security": [ { "BearerAuth": [] } ], "summary": "startPOSTerminalTransaction", "tags": [ "POSTerminals" ] } }, "/pos/terminal-transactions/{id}": { "get": { "operationId": "getPOSTerminalTransaction", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.TransactionResponse" } } }, "description": "Authoritative terminal state" }, "400": { "description": "Malformed request" }, "401": { "description": "Authentication required" }, "403": { "description": "POS and terminal permission required; refunds additionally require refund.write" }, "404": { "description": "Resource unavailable in caller geography" }, "409": { "description": "Identity, occupancy, authority or revision conflict" }, "503": { "description": "Recovery required; do not start a replacement transaction" } }, "security": [ { "BearerAuth": [] } ], "summary": "getPOSTerminalTransaction", "tags": [ "POSTerminals" ] } }, "/pos/terminal-transactions/{id}/cancel": { "post": { "operationId": "cancelPOSTerminalTransaction", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.TransactionResponse" } } }, "description": "Authoritative terminal state" }, "400": { "description": "Malformed request" }, "401": { "description": "Authentication required" }, "403": { "description": "POS and terminal permission required; refunds additionally require refund.write" }, "404": { "description": "Resource unavailable in caller geography" }, "409": { "description": "Identity, occupancy, authority or revision conflict" }, "503": { "description": "Recovery required; do not start a replacement transaction" } }, "security": [ { "BearerAuth": [] } ], "summary": "cancelPOSTerminalTransaction", "tags": [ "POSTerminals" ] } }, "/pos/terminal-transactions/{id}/events": { "get": { "operationId": "streamPOSTerminalTransaction", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "after", "schema": { "format": "int64", "type": "integer" } }, { "in": "header", "name": "Last-Event-ID", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "text/event-stream": { "schema": { "type": "string" } } }, "description": "Bounded authenticated SSE stream. event: transaction; id: durable sequence; data: ProgressEvent JSON. Reconnect with Last-Event-ID; GET status after disconnect." }, "400": { "description": "Malformed request" }, "401": { "description": "Authentication required" }, "403": { "description": "POS and terminal permission required; refunds additionally require refund.write" }, "404": { "description": "Resource unavailable in caller geography" }, "409": { "description": "Identity, occupancy, authority or revision conflict" }, "503": { "description": "Recovery required; do not start a replacement transaction" } }, "security": [ { "BearerAuth": [] } ], "summary": "streamPOSTerminalTransaction", "tags": [ "POSTerminals" ] } }, "/pos/terminal-transactions/{id}/receipts/reprint": { "post": { "operationId": "reprintPOSTerminalReceipt", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.TransactionResponse" } } }, "description": "Authoritative terminal state" }, "401": { "description": "Authentication required" }, "403": { "description": "POS and terminal permission required" }, "404": { "description": "Resource unavailable in caller geography" }, "409": { "description": "Occupancy or identity conflict" }, "503": { "description": "Uncertain provider outcome; retain original identity" } }, "security": [ { "BearerAuth": [] } ], "summary": "reprintPOSTerminalReceipt", "tags": [ "POSTerminals" ] } }, "/pos/terminal-transactions/{id}/responses": { "post": { "operationId": "respondPOSTerminalTransaction", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.ResponseInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posterminals.TransactionResponse" } } }, "description": "Authoritative terminal state" }, "400": { "description": "Malformed request" }, "401": { "description": "Authentication required" }, "403": { "description": "POS and terminal permission required; refunds additionally require refund.write" }, "404": { "description": "Resource unavailable in caller geography" }, "409": { "description": "Identity, occupancy, authority or revision conflict" }, "503": { "description": "Recovery required; do not start a replacement transaction" } }, "security": [ { "BearerAuth": [] } ], "summary": "respondPOSTerminalTransaction", "tags": [ "POSTerminals" ] } }, "/refund-requests": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "List refund requests", "tags": [ "refund-requests" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refundrequests.StaffCreateInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "Created or exact replay of the existing request" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" }, "409": { "description": "Retry key is bound to a different staff request, or a packing-station replacement key does not name a cancelled or rejected request for the same order and discrepancy" } }, "summary": "Raise a refund request (staff)", "tags": [ "refund-requests" ] } }, "/refund-requests/{id}": { "get": { "parameters": [ { "description": "id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/refundrequests.RefundRequest" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "Get a refund request", "tags": [ "refund-requests" ] } }, "/refund-requests/{id}/approve": { "post": { "description": "Requires refund.approve. Returns 409 REFUND_ALTERNATIVE_OFFER_OPEN while an alternative offer is offered. A packing-station request (staff idempotency_key packing-refund_{discrepancyID} or packing-refund_{discrepancyID}_{cancelledRequestID}, without packing_review) is re-checked first against Orders' current packing revision, unless a refund for the current approval_generation already exists (then approval finishes that refund). No other pending or approved request may exist for the same discrepancy, and each line's package composition must not exceed the shortage's current missing composition for the same package option, handling unit and units per package. Otherwise, or when the evidence cannot be read, approval returns 409 REFUND_REQUEST_SHORTAGE_CHANGED, the request stays pending and no money moves; cancel it and raise a replacement for the current shortage. Online requests retain existing execution behavior. Terminal requests return approved with terminal_execution awaiting_terminal and move no money. An exact approved request replays its binding; a definitively failed/cancelled attempt may be approved again only after reservation release, advancing approval_generation. Execution separately requires refund.write and POS/terminal permissions. Unknown or successful attempts cannot advance generation.", "parameters": [ { "description": "id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/refundrequests.RefundRequest" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "Approve a refund request", "tags": [ "refund-requests" ] } }, "/refund-requests/{id}/cancel": { "post": { "description": "Requires refund.request and geographic scope over the request's order. Any staff member with both may cancel, not only the original requester. Withdraws a pending staff-raised request. It sets status cancelled, records cancelled_by, cancelled_at and cancel_reason, and releases the request's refund reservation in the same transaction. No money moves. The cancelled request stops counting against the order's allocation. To change the quantity, cancel and raise a replacement through POST /refund-requests. A packing-station replacement must use idempotency_key packing-refund_{discrepancyID}_{cancelledRequestID}, because the original key replays the cancelled request; the suffix must name this cancelled request.", "parameters": [ { "description": "id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refundrequests.CancelInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/refundrequests.RefundRequest" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Request cancelled, or exact replay of the same command" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "Validation error" }, "403": { "description": "Missing refund.request, or the request was raised by a customer rather than staff" }, "404": { "description": "Not found or outside the caller's geography" }, "409": { "description": "The request is not pending, its approval is in progress, an alternative offer is open (REFUND_ALTERNATIVE_OFFER_OPEN), or it was already cancelled by a different idempotency_key or body" } }, "summary": "Cancel a pending staff refund request", "tags": [ "refund-requests" ] } }, "/refund-requests/{id}/offers": { "post": { "description": "Requires refund.approve. Records offer revision offer_revision+1 on a pending request and withdraws any previous revision. No refund or provider call is made. Money must use the request currency. For a line-based request each original_line_ref must name a request line. When REFUND_ALTERNATIVE_OFFERS_ENABLED is true, refund.alternative_offered v1 is written to the outbox in the same transaction.", "parameters": [ { "description": "id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refundrequests.OfferInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/refundrequests.RefundRequest" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Offer recorded, or exact replay of the same command" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "Validation error, or the request is no longer pending" }, "409": { "description": "Stale expected_offer_revision, a live approval claim, or idempotency_key bound to a different command" } }, "summary": "Offer an alternative instead of a refund", "tags": [ "refund-requests" ] } }, "/refund-requests/{id}/offers/{revision}/response": { "post": { "description": "Requires refund.approve. Staff record the customer's answer. accepted sets the request to alternative_accepted and records order_edit_id. It also releases the request's refund reservation in the same transaction, so an Orders amendment can use the headroom. rejected leaves the request pending, so Approve or Reject apply as usual.", "parameters": [ { "description": "id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Offer revision being answered", "in": "path", "name": "revision", "required": true, "schema": { "minimum": 1, "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refundrequests.OfferResponseInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/refundrequests.RefundRequest" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Response recorded, or exact replay of the same command" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "Validation error" }, "409": { "description": "Stale revision, offer already answered, or idempotency_key bound to a different command" } }, "summary": "Record the customer's response to an alternative offer", "tags": [ "refund-requests" ] } }, "/refund-requests/{id}/reject": { "post": { "description": "Requires refund.approve. Returns 409 REFUND_ALTERNATIVE_OFFER_OPEN while an alternative offer is offered.", "parameters": [ { "description": "id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "Reject a refund request", "tags": [ "refund-requests" ] } }, "/refunds": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "List refunds", "tags": [ "refunds" ] }, "post": { "description": "Gift-card purchases must use POST /refunds/gift-purchases; supplying payment_id does not bypass value recovery. Mixed refunds allocate external captured value first, then restore gift value through existing completion events, with independent captured-source caps. An unresolved Stripe attempt without a provider reference may be reissued only while its durable creation time is valid and less than 24 hours old. At or beyond 24 hours, or when that evidence is missing or invalid, pending state and reservations are retained; recover the existing attempt through POST /refunds/{id}/reconcile with verified provider evidence. Never create another attempt merely because the provider outcome is unknown. Rounded full cash refunds require compatible owner authority and otherwise remain blocked. An order paid in the legacy system (Orders import tagged legacy-external-payment) is refunded manually: the first refund writes one bookkeeping MANUAL_ADJUSTMENT payment for the order total at the legacy paid_at (no payment.captured), the refund settles through the manual provider, and refund events go out without analytics.refund_fact.", "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" }, "409": { "description": "Changed retry input, exhausted or incompatible source authority, or expired/invalid providerless Stripe retry evidence" }, "500": { "description": "Provider outcome unresolved; preserve the existing attempt and apply the bounded retry or reconciliation rules" } }, "summary": "Create a refund", "tags": [ "refunds" ] } }, "/refunds/by-order/{orderNumber}": { "get": { "parameters": [ { "description": "orderNumber", "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "List an order's refunds", "tags": [ "refunds" ] } }, "/refunds/gift-purchases": { "post": { "description": "Requires refund.write and canonical order geographic scope. The service derives the full original captured amount. Pricing must hold the original unspent, unreserved face and bonus before the payment provider is called. Orders must first show a settled paid projection with the same payment_id, preventing a remedy from overtaking capture reconciliation. Used, replaced, previously refunded, missing or mismatched issuance is refused. Retry uncertain outcomes with the identical idempotency_key and body; never create a second attempt merely because a request timed out. Providerless Stripe retries require a valid durable creation time less than 24 hours old. Older attempts retain pending state and value holds and require settled-provider reconciliation.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refunds.GiftPurchaseRefundInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refunds.GiftPurchaseRefundResponse" } } }, "description": "Durable refund, which may still be pending at the provider" }, "400": { "description": "Invalid body or missing required identity/reason" }, "401": { "description": "Authentication required" }, "403": { "description": "Missing refund.write or order outside geographic scope" }, "404": { "description": "Order or payment not found" }, "409": { "description": "Ineligible gift value, identity conflict, changed retry input, expired providerless Stripe retry, or definitive provider failure" }, "500": { "description": "Outcome unresolved; retry identical request and key only within the providerless Stripe retry window" }, "503": { "description": "Pricing unavailable or outcome unresolved; preserve the existing attempt and apply the providerless Stripe retry window" } }, "security": [ { "BearerAuth": [] } ], "summary": "Refund an untouched gift-card purchase after reserving its issued value", "tags": [ "refunds" ] } }, "/refunds/{id}": { "get": { "parameters": [ { "description": "id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "Get a refund by id", "tags": [ "refunds" ] } }, "/refunds/{id}/reconcile": { "post": { "description": "Requires refund.write and refund/order geographic scope. Reads Stripe refund and payment evidence using the configured provider account; never creates a provider refund. Only existing service-created merchandise refunds or full gift_purchase_remedy records with STRIPE_ONLINE provider, intact reserved authority and pending, processing or completed status are eligible. Merchandise refunds require exact refund_reference metadata and unchanged frozen source authority. Requires succeeded provider status, exact local payment/order, external refund amount/currency, payment intent/charge and test/live mode. The original payment's captured value must match the Stripe payment's amount received; a partial refund need not equal that original capture. Provider metadata naming another local refund, missing merchandise metadata, reused provider references and incompatible terminal states are rejected. The local ID plus provider_refund_id define replay identity; no new idempotency key is accepted. Financial completion, immutable staff association evidence and existing refund.completed v3 outbox facts commit together. Merchandise gift restoration uses the existing completion event. Purchased gift value recovery uses Pricing's eligibility-checked prepare/complete operation. A 200 response can have financial status completed while gift_remedy_state remains pending or prepared; retry this same association to recover value, never create another monetary refund. Provider failures or mismatched evidence leave financial status unchanged.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refunds.ReconcileProviderRefundInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refunds.GiftPurchaseRefundResponse" } } }, "description": "Verified financial completion with independently reported gift value recovery" }, "400": { "description": "Invalid provider refund ID or unexpected request fields" }, "401": { "description": "Authentication required" }, "403": { "description": "Missing refund.write or order outside geographic scope" }, "404": { "description": "Refund not found within caller geography" }, "409": { "description": "Ineligible local record, mismatched evidence, bound reference or concurrent outcome conflict" }, "503": { "description": "Authoritative Stripe evidence or reconciliation storage unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Reconcile an existing merchandise or full gift-purchase refund against settled Stripe evidence", "tags": [ "refunds" ] } }, "/statements/outstanding": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "Get the consolidated outstanding-invoice statement", "tags": [ "buyer-finance" ] } }, "/terminals": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "List payment terminals", "tags": [ "terminals" ] }, "post": { "description": "Resolves complete country, market, state and depot evidence through Supply before persisting. Contradictory geography or out-of-scope registration is rejected; unavailable Supply authority fails closed.", "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "Register a payment terminal", "tags": [ "terminals" ] } }, "/terminals/{id}": { "get": { "parameters": [ { "description": "id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "Get a terminal by id", "tags": [ "terminals" ] } }, "/terminals/{id}/connection": { "get": { "parameters": [ { "description": "id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "Get a terminal's connection status", "tags": [ "terminals" ] } }, "/terminals/{id}/settlements": { "get": { "description": "Reads retained settlement history only. Settlement recording is excluded; recorded captures alone do not establish complete provider settlement totals or reconciliation.", "parameters": [ { "description": "id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "List a terminal's settlements", "tags": [ "terminals" ] } }, "/terminals/{id}/status": { "patch": { "parameters": [ { "description": "id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "Update a terminal's status", "tags": [ "terminals" ] } }, "/terminals/{id}/transactions": { "get": { "description": "Reads terminal transaction history with canonical Payments-owned provider identity (LINKLY_POS or MX51_POS). This history route does not execute terminal operations.", "parameters": [ { "description": "id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/terminals.TerminalTransaction" }, "type": "array" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "List a terminal's transactions", "tags": [ "terminals" ] } }, "/webhooks/linkly-cloud/{id}/{session}": { "post": { "operationId": "receiveLinklyCloudNotification", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "session", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "description": "Per-session HMAC bearer supplied in Notification.AuthorizationHeader", "in": "header", "name": "Authorization", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Notification durably processed or duplicate" }, "400": { "description": "Malformed notification" }, "401": { "description": "Invalid callback authentication" }, "503": { "description": "Retry same notification" } }, "security": [], "summary": "Receive transaction-bound authenticated Linkly Cloud notification", "tags": [ "POSTerminals" ] } }, "/webhooks/stripe": { "post": { "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "type": "string" } } }, "description": "error" } }, "summary": "Stripe webhook receiver", "tags": [ "payments" ] } }, "/webhooks/stripe-terminal": { "post": { "description": "Signature verified; exact API version 2026-09-30.endive and configured live/test mode required. Durable receipt triggers authoritative provider reconciliation.", "operationId": "stripeTerminalWebhook", "responses": { "200": { "description": "Accepted" }, "400": { "description": "Signature, version or mode rejected" }, "503": { "description": "Retry delivery" } }, "security": [], "summary": "Dedicated Stripe Terminal Endive webhook", "tags": [ "POSTerminals" ] } } }, "servers": [ { "url": "/v1" } ] }