{ "openapi": "3.1.0", "info": { "title": "Local Protocol", "description": "Local Protocol delivery API. Covers service discovery, delivery requests, quotes, and deliveries.", "version": "0.1.0" }, "servers": [ { "url": "http://localhost:8000", "description": "Local development server" } ], "tags": [ { "name": "discovery", "description": "Service discovery and health" }, { "name": "requests", "description": "Delivery request operations" }, { "name": "quotes", "description": "Delivery quote operations" }, { "name": "deliveries", "description": "Delivery lifecycle operations" }, { "name": "merchants", "description": "Merchant and catalog operations" }, { "name": "orders", "description": "Order lifecycle operations" }, { "name": "events", "description": "Event vocabulary operations" }, { "name": "payments", "description": "Payment instrument operations" } ], "paths": { "/.well-known/local-protocol": { "get": { "tags": [ "discovery" ], "summary": "Service discovery", "description": "Returns server capabilities, supported standards, and endpoint paths.", "operationId": "getDiscovery", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import LocalProtocol from \"local-protocol\";\n\nconst client = new LocalProtocol();\n\nconst discovery = await client.wellKnown.retrieve();\nconsole.log(discovery.capabilities);" }, { "lang": "python", "label": "Python SDK", "source": "from local_protocol import LocalProtocol\n\nclient = LocalProtocol()\ndiscovery = client.well_known.retrieve()\nprint(discovery.capabilities)" }, { "lang": "shell", "label": "cURL", "source": "curl -sS http://localhost:8000/.well-known/local-protocol" } ], "responses": { "200": { "description": "Discovery metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string", "description": "Protocol version." }, "name": { "type": "string", "description": "Server name." }, "capabilities": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": true }, "description": "Supported capabilities by domain." }, "endpoints": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Endpoint path map." } }, "required": [ "version", "name", "capabilities", "endpoints" ], "additionalProperties": false } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } } } } }, "/healthz": { "get": { "tags": [ "discovery" ], "summary": "Health check", "description": "Returns server health status.", "operationId": "getHealth", "responses": { "200": { "description": "Server is healthy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "503": { "description": "Service unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } } } } }, "/requests": { "post": { "tags": [ "requests" ], "summary": "Create delivery request", "description": "Submit a new delivery request. The `nonce` field provides idempotency.", "operationId": "createRequest", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import LocalProtocol from \"local-protocol\";\n\nconst client = new LocalProtocol();\n\nconst request = await client.requests.create({\n id: \"req_demo_123\",\n nonce: \"nonce_demo_123\",\n pickup_location: {\n coordinates: { latitude: 37.7751, longitude: -122.4193 },\n },\n dropoff_location: {\n coordinates: { latitude: 37.7875, longitude: -122.4073 },\n },\n pickup_time: \"2026-02-10T17:00:00Z\",\n dropoff_time: \"2026-02-10T17:30:00Z\",\n});\n\nconsole.log(request.id);" }, { "lang": "python", "label": "Python SDK", "source": "from local_protocol import LocalProtocol\n\nclient = LocalProtocol()\nrequest = client.requests.create(\n id=\"req_demo_123\",\n nonce=\"nonce_demo_123\",\n pickup_location={\"coordinates\": {\"latitude\": 37.7751, \"longitude\": -122.4193}},\n dropoff_location={\"coordinates\": {\"latitude\": 37.7875, \"longitude\": -122.4073}},\n pickup_time=\"2026-02-10T17:00:00Z\",\n dropoff_time=\"2026-02-10T17:30:00Z\",\n)\n\nprint(request.id)" }, { "lang": "shell", "label": "cURL", "source": "curl -sS -X POST \\\n -H \"Content-Type: application/json\" \\\n http://localhost:8000/requests \\\n -d '{\n \"id\": \"req_demo_123\",\n \"nonce\": \"nonce_demo_123\",\n \"pickup_location\": {\"coordinates\": {\"latitude\": 37.7751, \"longitude\": -122.4193}},\n \"dropoff_location\": {\"coordinates\": {\"latitude\": 37.7875, \"longitude\": -122.4073}},\n \"pickup_time\": \"2026-02-10T17:00:00Z\",\n \"dropoff_time\": \"2026-02-10T17:30:00Z\"\n }'" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryRequest" } } } }, "responses": { "201": { "description": "Request created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryRequest" } } } }, "400": { "description": "Invalid nonce.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } }, "409": { "description": "Duplicate nonce or request ID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } }, "422": { "description": "Validation errors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" }, "description": "List of validation error messages." } }, "required": [ "errors" ] } }, "required": [ "detail" ] } } } } } }, "get": { "tags": [ "requests" ], "summary": "List delivery requests", "description": "Returns all delivery requests.", "operationId": "listRequests", "responses": { "200": { "description": "List of requests.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryRequest" } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } } } } }, "/requests/{request_id}": { "get": { "tags": [ "requests" ], "summary": "Get delivery request", "description": "Returns a single delivery request by ID.", "operationId": "getRequest", "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "The request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryRequest" } } } }, "404": { "description": "Request not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } } } } }, "/requests/{request_id}/quotes": { "post": { "tags": [ "quotes" ], "summary": "Create quote", "description": "Submit a quote for a delivery request. The `nonce` field provides idempotency.", "operationId": "createQuote", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import LocalProtocol from \"local-protocol\";\n\nconst client = new LocalProtocol();\n\nconst quote = await client.requests.quotes.create(\"req_demo_123\", {\n id: \"quote_demo_123\",\n nonce: \"nonce_quote_123\",\n price: 1299,\n currency: \"USD\",\n pickup_location: {\n coordinates: { latitude: 37.7751, longitude: -122.4193 },\n },\n dropoff_location: {\n coordinates: { latitude: 37.7875, longitude: -122.4073 },\n },\n pickup_estimate: \"2026-02-10T17:08:00Z\",\n dropoff_estimate: \"2026-02-10T17:30:00Z\",\n payment: {\n instruments: [\n {\n id: \"pi_demo_123\",\n handler_id: \"com.localprotocol.evm_auth_capture_escrow\",\n type: \"evm_auth_capture_escrow\",\n },\n ],\n },\n});\n\nconsole.log(quote.id);" }, { "lang": "python", "label": "Python SDK", "source": "from local_protocol import LocalProtocol\n\nclient = LocalProtocol()\nquote = client.requests.quotes.create(\n request_id=\"req_demo_123\",\n id=\"quote_demo_123\",\n nonce=\"nonce_quote_123\",\n price=1299,\n currency=\"USD\",\n pickup_location={\"coordinates\": {\"latitude\": 37.7751, \"longitude\": -122.4193}},\n dropoff_location={\"coordinates\": {\"latitude\": 37.7875, \"longitude\": -122.4073}},\n pickup_estimate=\"2026-02-10T17:08:00Z\",\n dropoff_estimate=\"2026-02-10T17:30:00Z\",\n payment={\n \"instruments\": [\n {\n \"id\": \"pi_demo_123\",\n \"handler_id\": \"com.localprotocol.evm_auth_capture_escrow\",\n \"type\": \"evm_auth_capture_escrow\",\n }\n ]\n },\n)\n\nprint(quote.id)" } ], "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryQuote" } } } }, "responses": { "201": { "description": "Quote created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryQuote" } } } }, "400": { "description": "Invalid nonce.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } }, "404": { "description": "Request not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } }, "409": { "description": "Duplicate nonce or quote ID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } }, "422": { "description": "Validation errors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" }, "description": "List of validation error messages." } }, "required": [ "errors" ] } }, "required": [ "detail" ] } } } } } }, "get": { "tags": [ "quotes" ], "summary": "List quotes for request", "description": "Returns all quotes for a delivery request.", "operationId": "listQuotes", "parameters": [ { "$ref": "#/components/parameters/RequestId" } ], "responses": { "200": { "description": "List of quotes.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryQuote" } } } } }, "404": { "description": "Request not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } } } } }, "/requests/{request_id}/quotes/{quote_id}": { "get": { "tags": [ "quotes" ], "summary": "Get quote", "description": "Returns a single quote by ID.", "operationId": "getQuote", "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/QuoteId" } ], "responses": { "200": { "description": "The quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryQuote" } } } }, "404": { "description": "Request or quote not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } } } } }, "/deliveries": { "post": { "tags": [ "deliveries" ], "summary": "Create delivery", "description": "Create a delivery from an accepted quote. The `nonce` field provides idempotency.", "operationId": "createDelivery", "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "import LocalProtocol from \"local-protocol\";\n\nconst client = new LocalProtocol();\n\nconst delivery = await client.deliveries.create({\n request_id: \"req_demo_123\",\n quote_id: \"quote_demo_123\",\n nonce: \"nonce_delivery_123\",\n event_vocabulary: \"xyz.localprotocol.delivery.courier@2026-01-30\",\n});\n\nconsole.log(delivery.id);" }, { "lang": "python", "label": "Python SDK", "source": "from local_protocol import LocalProtocol\n\nclient = LocalProtocol()\ndelivery = client.deliveries.create(\n request_id=\"req_demo_123\",\n quote_id=\"quote_demo_123\",\n nonce=\"nonce_delivery_123\",\n event_vocabulary=\"xyz.localprotocol.delivery.courier@2026-01-30\",\n)\n\nprint(delivery.id)" }, { "lang": "shell", "label": "cURL", "source": "curl -sS -X POST \\\n -H \"Content-Type: application/json\" \\\n http://localhost:8000/deliveries \\\n -d '{\n \"request_id\": \"req_demo_123\",\n \"quote_id\": \"quote_demo_123\",\n \"nonce\": \"nonce_delivery_123\",\n \"event_vocabulary\": \"xyz.localprotocol.delivery.courier@2026-01-30\"\n }'" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "The delivery request to fulfill." }, "quote_id": { "type": "string", "description": "The accepted quote." }, "nonce": { "type": "string", "description": "Client-generated idempotency key." }, "webhook_url": { "type": [ "string", "null" ], "format": "uri", "description": "Optional URL to receive delivery event webhook notifications." }, "event_vocabulary": { "type": "string", "default": "xyz.localprotocol.delivery.courier@2026-01-30", "description": "Event vocabulary standard to use." } }, "required": [ "request_id", "quote_id", "nonce" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Delivery created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Delivery" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } }, "404": { "description": "Request or quote not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } }, "409": { "description": "Duplicate nonce or nonce reuse with different payload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } } } }, "get": { "tags": [ "deliveries" ], "summary": "List deliveries", "description": "Returns all deliveries.", "operationId": "listDeliveries", "responses": { "200": { "description": "List of deliveries.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } } } } }, "/deliveries/{delivery_id}": { "get": { "tags": [ "deliveries" ], "summary": "Get delivery", "description": "Returns a single delivery by ID.", "operationId": "getDelivery", "parameters": [ { "$ref": "#/components/parameters/DeliveryId" } ], "responses": { "200": { "description": "The delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Delivery" } } } }, "404": { "description": "Delivery not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } } } } }, "/deliveries/{delivery_id}/event": { "patch": { "tags": [ "deliveries" ], "summary": "Update delivery event", "description": "Transition a delivery to a new event state. If a webhook URL was registered, the server pushes an event notification in the background.", "operationId": "updateDeliveryEvent", "parameters": [ { "$ref": "#/components/parameters/DeliveryId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "description": "Event identifier from the delivery's event vocabulary." }, "event_description": { "type": "string", "description": "Human-readable event description." } }, "required": [ "event", "event_description" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Delivery event updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Delivery" } } } }, "404": { "description": "Delivery not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } } } } }, "/merchants/{merchant_id}": { "get": { "tags": [ "merchants" ], "summary": "Get merchant", "description": "Returns a merchant with its full denormalized catalog tree.", "operationId": "getMerchant", "parameters": [ { "$ref": "#/components/parameters/MerchantId" } ], "responses": { "200": { "description": "The merchant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Merchant" } } } }, "404": { "description": "Merchant not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } } } } }, "/orders/requests": { "post": { "tags": [ "orders" ], "summary": "Create order request", "description": "Submit a new order request with a cart. The `nonce` field provides idempotency.", "operationId": "createOrderRequest", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } }, "responses": { "201": { "description": "Order request created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderRequest" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } }, "409": { "description": "Duplicate nonce or request ID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } }, "422": { "description": "Validation errors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" }, "description": "List of validation error messages." } }, "required": [ "errors" ] } }, "required": [ "detail" ] } } } } } } }, "/orders/requests/{order_request_id}/quotes": { "get": { "tags": [ "orders" ], "summary": "List order quotes", "description": "Returns all quotes for an order request.", "operationId": "listOrderQuotes", "parameters": [ { "$ref": "#/components/parameters/OrderRequestId" } ], "responses": { "200": { "description": "List of order quotes.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrderQuote" } } } } }, "404": { "description": "Order request not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } } } } }, "/orders/requests/{order_request_id}/quotes/{order_quote_id}": { "get": { "tags": [ "orders" ], "summary": "Get order quote", "description": "Returns a single order quote by ID.", "operationId": "getOrderQuote", "parameters": [ { "$ref": "#/components/parameters/OrderRequestId" }, { "$ref": "#/components/parameters/OrderQuoteId" } ], "responses": { "200": { "description": "The order quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderQuote" } } } }, "404": { "description": "Order request or quote not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } } } } }, "/orders": { "post": { "tags": [ "orders" ], "summary": "Create order", "description": "Accept a quote and create an order. The `nonce` field provides idempotency.", "operationId": "createOrder", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "order_request_id": { "type": "string", "description": "The order request to fulfill." }, "order_quote_id": { "type": "string", "description": "The accepted quote." }, "nonce": { "type": "string", "description": "Client-generated idempotency key." }, "payment_instrument_id": { "type": "string", "description": "Reference to the registered payment instrument." } }, "required": [ "order_request_id", "order_quote_id", "nonce", "payment_instrument_id" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Order created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "description": "Invalid nonce or quote does not belong to request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } }, "404": { "description": "Order request or quote not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } }, "409": { "description": "Duplicate nonce.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } } } } }, "/orders/{order_id}": { "get": { "tags": [ "orders" ], "summary": "Get order", "description": "Returns a single order by ID.", "operationId": "getOrder", "parameters": [ { "$ref": "#/components/parameters/OrderId" } ], "responses": { "200": { "description": "The order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "404": { "description": "Order not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } } } } }, "/event-vocabularies/{name}": { "get": { "tags": [ "events" ], "summary": "Get event vocabulary", "description": "Returns a delivery event vocabulary by name.", "operationId": "getEventVocabulary", "parameters": [ { "$ref": "#/components/parameters/EventVocabularyName" } ], "responses": { "200": { "description": "The event vocabulary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryEventVocabulary" } } } }, "404": { "description": "Event vocabulary not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } } } } }, "/payment-instruments": { "post": { "tags": [ "payments" ], "summary": "Register payment instrument", "description": "Register a payment instrument for use in order creation.", "operationId": "createPaymentInstrument", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvmAuthCaptureEscrowInstrument" } } } }, "responses": { "201": { "description": "Payment instrument registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvmAuthCaptureEscrowInstrument" } } } }, "400": { "description": "Invalid instrument data.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message." } }, "required": [ "detail" ] } } } }, "422": { "description": "Validation errors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" }, "description": "List of validation error messages." } }, "required": [ "errors" ] } }, "required": [ "detail" ] } } } } } } } }, "components": { "parameters": { "RequestId": { "name": "request_id", "in": "path", "required": true, "description": "Delivery request identifier.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "QuoteId": { "name": "quote_id", "in": "path", "required": true, "description": "Quote identifier.", "schema": { "$ref": "#/components/schemas/QuoteId" } }, "DeliveryId": { "name": "delivery_id", "in": "path", "required": true, "description": "Delivery identifier.", "schema": { "$ref": "#/components/schemas/DeliveryId" } }, "MerchantId": { "name": "merchant_id", "in": "path", "required": true, "description": "Merchant identifier.", "schema": { "$ref": "#/components/schemas/MerchantId" } }, "OrderRequestId": { "name": "order_request_id", "in": "path", "required": true, "description": "Order request identifier.", "schema": { "$ref": "#/components/schemas/OrderRequestId" } }, "OrderQuoteId": { "name": "order_quote_id", "in": "path", "required": true, "description": "Order quote identifier.", "schema": { "$ref": "#/components/schemas/OrderQuoteId" } }, "OrderId": { "name": "order_id", "in": "path", "required": true, "description": "Order identifier.", "schema": { "$ref": "#/components/schemas/OrderId" } }, "EventVocabularyName": { "name": "name", "in": "path", "required": true, "description": "Event vocabulary name in reverse-domain notation (e.g., xyz.localprotocol.delivery.courier).", "schema": { "$ref": "#/components/schemas/EventVocabularyName" } } }, "schemas": { "Coordinates": { "type": "object", "description": "Coordinates", "required": [ "latitude", "longitude" ], "additionalProperties": false, "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude in decimal degrees." }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude in decimal degrees." } } }, "PostalAddress": { "type": "object", "properties": { "extended_address": { "type": "string", "description": "An address extension such as an apartment number, C/O or alternative name." }, "street_address": { "type": "string", "description": "The street address." }, "address_locality": { "type": "string", "description": "The locality in which the street address is, and which is in the region. For example, Mountain View." }, "address_region": { "type": "string", "description": "The region in which the locality is, and which is in the country. Required for applicable countries (i.e. state in US, province in CA). For example, California or another appropriate first-level Administrative division." }, "address_country": { "type": "string", "description": "The country. Recommended to be in 2-letter ISO 3166-1 alpha-2 format, for example \"US\". For backward compatibility, a 3-letter ISO 3166-1 alpha-3 country code such as \"SGP\" or a full country name such as \"Singapore\" can also be used." }, "postal_code": { "type": "string", "description": "The postal code. For example, 94043." }, "first_name": { "type": "string", "description": "Optional. First name of the contact associated with the address." }, "last_name": { "type": "string", "description": "Optional. Last name of the contact associated with the address." }, "phone_number": { "type": "string", "description": "Optional. Phone number of the contact associated with the address." } }, "description": "Postal Address" }, "Location": { "description": "Location", "anyOf": [ { "required": [ "postal_address" ], "type": "object", "properties": { "postal_address": { "$ref": "#/components/schemas/PostalAddress" }, "coordinates": { "$ref": "#/components/schemas/Coordinates" } }, "additionalProperties": false, "title": "LocationWithPostalAddress" }, { "required": [ "coordinates" ], "type": "object", "properties": { "coordinates": { "$ref": "#/components/schemas/Coordinates" }, "postal_address": { "$ref": "#/components/schemas/PostalAddress" } }, "additionalProperties": false, "title": "LocationWithCoordinates" } ] }, "DeliveryRequest": { "type": "object", "description": "DeliveryRequest", "required": [ "id", "nonce", "pickup_location", "dropoff_location", "pickup_time", "dropoff_time" ], "properties": { "id": { "type": "string", "description": "Unique request identifier." }, "nonce": { "type": "string", "description": "Client-generated idempotency key." }, "pickup_location": { "$ref": "#/components/schemas/Location", "description": "Pickup location for the delivery." }, "dropoff_location": { "$ref": "#/components/schemas/Location", "description": "Dropoff location for the delivery." }, "pickup_time": { "type": "string", "format": "date-time", "description": "Requested pickup time (RFC 3339)." }, "dropoff_time": { "type": "string", "format": "date-time", "description": "Requested dropoff time (RFC 3339)." }, "pickup_instructions": { "type": "string", "description": "Pickup directions, access codes, or handling notes." }, "dropoff_instructions": { "type": "string", "description": "Dropoff directions, access codes, or delivery notes." } }, "additionalProperties": false }, "DeliveryQuote": { "type": "object", "description": "DeliveryQuote", "required": [ "id", "nonce", "price", "currency", "pickup_location", "dropoff_location", "pickup_estimate", "dropoff_estimate", "payment" ], "properties": { "id": { "type": "string", "description": "Unique quote identifier." }, "nonce": { "type": "string", "description": "Client-generated idempotency key." }, "price": { "type": "integer", "minimum": 0, "description": "Price in minor currency units." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code." }, "pickup_location": { "$ref": "#/components/schemas/Location", "description": "Pickup location for the delivery." }, "dropoff_location": { "$ref": "#/components/schemas/Location", "description": "Dropoff location for the delivery." }, "pickup_estimate": { "type": "string", "format": "date-time", "description": "Estimated pickup time (RFC 3339)." }, "dropoff_estimate": { "type": "string", "format": "date-time", "description": "Estimated dropoff time (RFC 3339)." }, "expires_at": { "type": "string", "format": "date-time", "description": "Time when the quote expires (RFC 3339)." }, "payment": { "$ref": "#/components/schemas/Payment", "description": "Payment handlers available for accepting this quote." } }, "additionalProperties": false }, "CreateDeliveryRequest": { "type": "object", "required": [ "request_id", "quote_id", "nonce" ], "additionalProperties": false, "properties": { "request_id": { "type": "string", "description": "The delivery request to fulfill." }, "quote_id": { "type": "string", "description": "The accepted quote." }, "nonce": { "type": "string", "description": "Client-generated idempotency key." }, "webhook_url": { "type": [ "string", "null" ], "description": "Optional URL to receive delivery event webhook notifications.", "format": "uri" }, "event_vocabulary": { "type": "string", "description": "Event vocabulary standard to use.", "default": "xyz.localprotocol.delivery.courier@2026-01-30" } } }, "UpdateEventRequest": { "type": "object", "required": [ "event", "event_description" ], "additionalProperties": false, "properties": { "event": { "type": "string", "description": "Event identifier from the delivery's event vocabulary." }, "event_description": { "type": "string", "description": "Human-readable event description." } } }, "Delivery": { "type": "object", "description": "Delivery resource created when a quote is accepted.", "required": [ "id", "request_id", "quote_id", "payment_instrument_id", "event", "event_description", "event_vocabulary", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "Unique delivery identifier." }, "request_id": { "type": "string", "description": "Reference to the original request." }, "quote_id": { "type": "string", "description": "Reference to the accepted quote." }, "payment_instrument_id": { "type": "string", "description": "Reference to the payment instrument used to create this delivery." }, "event": { "type": "string", "description": "Current event identifier." }, "event_description": { "type": "string", "description": "Human-readable description of the current event." }, "event_vocabulary": { "type": "string", "description": "Event vocabulary standard in use." }, "webhook_url": { "type": [ "string", "null" ], "description": "Registered webhook URL, if any." }, "created_at": { "type": "string", "format": "date-time", "description": "Delivery creation timestamp (RFC 3339)." }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp (RFC 3339)." } }, "additionalProperties": false }, "DiscoveryResponse": { "type": "object", "required": [ "version", "name", "capabilities", "endpoints" ], "properties": { "version": { "type": "string", "description": "Protocol version." }, "name": { "type": "string", "description": "Server name." }, "capabilities": { "type": "object", "description": "Supported capabilities by domain.", "additionalProperties": { "type": "object", "additionalProperties": true } }, "endpoints": { "type": "object", "description": "Endpoint path map.", "additionalProperties": { "type": "string" } } }, "additionalProperties": false }, "HealthResponse": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] } }, "additionalProperties": false }, "ErrorResponse": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "string", "description": "Error message." } } }, "ValidationErrorResponse": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "type": "string" }, "description": "List of validation error messages." } } } } }, "FiatCurrency": { "type": "object", "description": "Fiat currency descriptor.", "required": [ "symbol" ], "additionalProperties": false, "properties": { "symbol": { "type": "string", "description": "ISO 4217 currency code (e.g., 'USD', 'EUR', 'JPY').", "pattern": "^[A-Z0-9_]+$" } } }, "EvmCurrency": { "type": "object", "description": "EVM token currency descriptor.", "required": [ "chain_id", "address", "decimals" ], "additionalProperties": false, "properties": { "chain_id": { "type": "integer", "minimum": 1, "description": "EVM chain id." }, "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Token contract address." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Decimal places for the token." } } }, "EvmAmount": { "type": "object", "description": "Amount denominated in an EVM token. Value is in atomic token units.", "required": [ "value", "currency" ], "additionalProperties": false, "properties": { "value": { "type": "string", "pattern": "^[0-9]+$", "description": "Value in atomic token units as an integer string." }, "currency": { "type": "object", "properties": { "chain_id": { "type": "integer", "minimum": 1, "description": "EVM chain id." }, "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Token contract address." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Decimal places for the token." } }, "required": [ "chain_id", "address", "decimals" ], "additionalProperties": false, "description": "EVM token currency." } } }, "Amount": { "type": "object", "description": "Amount with explicit currency. Value is always in minor units (e.g., cents for USD).", "required": [ "value", "currency" ], "additionalProperties": false, "properties": { "value": { "type": "string", "pattern": "^[0-9]+$", "description": "Value in minor currency units as an integer string (e.g., \"1000\" = $10.00 USD, or atomic units for EVM tokens). Use \"0\" for free items." }, "currency": { "description": "Currency descriptor (fiat or EVM token).", "anyOf": [ { "$ref": "#/components/schemas/FiatCurrency" }, { "$ref": "#/components/schemas/EvmCurrency" } ] } } }, "Media": { "type": "object", "description": "Product media item (image, video, etc.).", "required": [ "type", "url" ], "properties": { "type": { "type": "string", "enum": [ "image", "video", "model_3d" ], "description": "Media type discriminator." }, "url": { "type": "string", "format": "uri", "description": "URL to the media resource." }, "alt_text": { "type": "string", "description": "Accessibility text describing the media." }, "width": { "type": "integer", "minimum": 1, "description": "Width in pixels (for images/video)." }, "height": { "type": "integer", "minimum": 1, "description": "Height in pixels (for images/video)." } }, "additionalProperties": false }, "Interval": { "type": "object", "description": "A single time interval for a day of the week or a specific date.", "required": [ "from_hour", "from_minute", "to_hour", "to_minute" ], "additionalProperties": false, "properties": { "day": { "type": "string", "description": "Day of week (e.g., Monday, Tuesday)." }, "date": { "type": "string", "description": "Calendar date in YYYY-MM-DD." }, "from_hour": { "type": "integer", "minimum": 0, "maximum": 23, "description": "Start hour (0-23)." }, "from_minute": { "type": "integer", "minimum": 0, "maximum": 59, "description": "Start minute (0-59)." }, "to_hour": { "type": "integer", "minimum": 0, "maximum": 23, "description": "End hour (0-23)." }, "to_minute": { "type": "integer", "minimum": 0, "maximum": 59, "description": "End minute (0-59)." } } }, "Availability": { "type": "object", "description": "Availability schedule for a catalog, category, or item.", "required": [ "intervals" ], "additionalProperties": false, "properties": { "timezone": { "type": "string", "description": "IANA timezone for the intervals. Defaults to the merchant timezone when omitted." }, "intervals": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/Interval" }, "description": "Availability intervals (weekly or date-specific)." } } }, "ModifierItem": { "type": "object", "description": "A purchasable modifier item that can be selected within a modifier group.", "required": [ "id", "name", "price" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Modifier item identifier." }, "name": { "type": "string", "description": "Modifier item name." }, "description": { "type": "string", "description": "Optional modifier item description." }, "price": { "description": "Price for this modifier item.", "type": "object", "properties": { "value": { "type": "string", "pattern": "^[0-9]+$", "description": "Value in minor currency units as an integer string (e.g., \"1000\" = $10.00 USD, or atomic units for EVM tokens). Use \"0\" for free items." }, "currency": { "anyOf": [ { "$ref": "#/components/schemas/FiatCurrency" }, { "$ref": "#/components/schemas/EvmCurrency" } ], "description": "Currency descriptor (fiat or EVM token)." } }, "required": [ "value", "currency" ], "additionalProperties": false }, "metadata": { "type": "object", "description": "Business-defined custom data extending the modifier item.", "additionalProperties": true } } }, "ModifierOption": { "type": "object", "description": "Selectable option within a modifier group.", "required": [ "id", "modifier_item" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Modifier option identifier." }, "modifier_item": { "$ref": "#/components/schemas/ModifierItem", "description": "Modifier item for this option." }, "child_modifier_groups": { "type": "array", "items": { "$ref": "#/components/schemas/ModifierGroup" }, "description": "Nested modifier groups required after selecting this option." }, "is_default": { "type": "boolean", "description": "Whether this option is selected by default." }, "metadata": { "type": "object", "description": "Business-defined custom data extending the modifier option.", "additionalProperties": true } } }, "ModifierGroup": { "type": "object", "description": "Group of modifier options with selection constraints.", "required": [ "id", "name", "modifier_options" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Modifier group identifier." }, "name": { "type": "string", "description": "Display name for the modifier group." }, "description": { "type": "string", "description": "Optional modifier group description." }, "minimum_selections": { "type": "integer", "minimum": 0, "description": "Minimum number of selections required from this group." }, "maximum_selections": { "type": "integer", "minimum": 0, "description": "Maximum number of selections allowed from this group." }, "allow_quantities": { "type": "boolean", "description": "Whether modifier options can be selected with quantities greater than 1." }, "max_per_modifier": { "type": "integer", "minimum": 0, "description": "Maximum quantity allowed per modifier option. Defaults to 1 (each modifier can be selected at most once)." }, "modifier_options": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ModifierOption" }, "description": "Ordered modifier options within this group. Order should be used for display." }, "type": { "type": "string", "description": "Modifier group type classification." }, "metadata": { "type": "object", "description": "Business-defined custom data extending the modifier group.", "additionalProperties": true } } }, "CatalogItem": { "type": "object", "description": "A menu item with embedded modifier groups.", "required": [ "id", "name", "description", "price" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Item identifier." }, "name": { "type": "string", "description": "Item name." }, "description": { "type": "string", "description": "Item description." }, "price": { "$ref": "#/components/schemas/Amount", "description": "Base price for the item." }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/Media" }, "description": "Item media (images, videos, 3D models)." }, "modifier_groups": { "type": "array", "items": { "$ref": "#/components/schemas/ModifierGroup" }, "description": "Modifier groups available for this item." }, "availability": { "$ref": "#/components/schemas/Availability", "description": "Item availability. Ignored when the catalog or category defines availability." }, "metadata": { "type": "object", "description": "Business-defined custom data extending the item.", "additionalProperties": true } } }, "CatalogCategory": { "type": "object", "description": "A category grouping items in a catalog.", "required": [ "id", "name", "items" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Category identifier." }, "name": { "type": "string", "description": "Category display name." }, "description": { "type": "string", "description": "Optional category description." }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogCategory" }, "description": "Ordered list of child categories for nested category trees." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogItem" }, "description": "Ordered list of items in this category." }, "availability": { "$ref": "#/components/schemas/Availability", "description": "Category availability. Ignored when the catalog defines availability." }, "metadata": { "type": "object", "description": "Business-defined custom data extending the category.", "additionalProperties": true } } }, "Catalog": { "type": "object", "description": "A catalog containing embedded categories, items, availability, and fulfillment configuration.", "required": [ "id", "name", "categories" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Catalog identifier." }, "name": { "type": "string", "description": "Catalog name." }, "description": { "type": "string", "description": "Catalog description." }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogCategory" }, "description": "Ordered top-level categories included in this catalog. Nested categories live under each category's categories array." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogItem" }, "description": "Ordered items included in this catalog that are not assigned to a category. Consumers that require category membership should place these items into a synthetic category." }, "availability": { "$ref": "#/components/schemas/Availability", "description": "Catalog availability. When present, it overrides category and item availability." }, "metadata": { "type": "object", "description": "Business-defined custom data extending the catalog.", "additionalProperties": true } } }, "Merchant": { "type": "object", "description": "Merchant catalog payload containing denormalized catalogs.", "required": [ "id", "name", "timezone", "catalogs" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Merchant identifier." }, "name": { "type": "string", "description": "Merchant name." }, "timezone": { "type": "string", "description": "IANA timezone for availability schedules." }, "last_updated": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp of the latest catalog update." }, "catalogs": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/Catalog" }, "description": "Catalogs available for the merchant." }, "metadata": { "type": "object", "description": "Business-defined custom data extending the merchant.", "additionalProperties": true } } }, "CartItem": { "type": "object", "description": "Cart Item", "required": [ "id", "quantity" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Item identifier." }, "quantity": { "type": "integer", "minimum": 1, "description": "Quantity requested." } } }, "Cart": { "type": "object", "description": "Cart", "required": [ "id", "intent_id", "nonce", "items" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Unique cart identifier." }, "intent_id": { "type": "string", "description": "Shared intent identifier for tracing Request → Quote → Order." }, "nonce": { "type": "string", "description": "Client-generated idempotency key." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CartItem" }, "description": "Items in the cart." } } }, "OrderRequest": { "type": "object", "description": "OrderRequest", "required": [ "id", "intent_id", "nonce" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Unique request identifier." }, "intent_id": { "type": "string", "description": "Shared intent identifier for tracing Request → Quote → Order." }, "nonce": { "type": "string", "description": "Client-generated idempotency key." } } }, "OrderQuote": { "type": "object", "description": "OrderQuote", "required": [ "id", "intent_id", "nonce", "price", "ready_at", "expires_at" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Unique quote identifier." }, "intent_id": { "type": "string", "description": "Shared intent identifier for tracing Request → Quote → Order." }, "nonce": { "type": "string", "description": "Client-generated idempotency key." }, "price": { "type": "integer", "description": "Price in minor currency units." }, "ready_at": { "type": "string", "format": "date-time", "description": "Estimated readiness time (RFC 3339)." }, "expires_at": { "type": "string", "format": "date-time", "description": "Quote expiration time (RFC 3339)." } } }, "CreateOrderRequest": { "type": "object", "required": [ "order_request_id", "order_quote_id", "nonce", "payment_instrument_id" ], "additionalProperties": false, "properties": { "order_request_id": { "type": "string", "description": "The order request to fulfill." }, "order_quote_id": { "type": "string", "description": "The accepted quote." }, "nonce": { "type": "string", "description": "Client-generated idempotency key." }, "payment_instrument_id": { "type": "string", "description": "Reference to the registered payment instrument." } } }, "Order": { "type": "object", "description": "Order", "required": [ "id", "intent_id", "nonce", "payment_instrument_id" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Unique order identifier." }, "intent_id": { "type": "string", "description": "Shared intent identifier for tracing Request → Quote → Order." }, "nonce": { "type": "string", "description": "Client-generated idempotency key." }, "payment_instrument_id": { "type": "string", "description": "Reference to the payment instrument used to create this order." } } }, "EvmToken": { "type": "object", "description": "EVM token identifier used for auth/capture settlement.", "required": [ "symbol", "decimals" ], "additionalProperties": false, "properties": { "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "ERC-20 contract address. Omit for native gas tokens (e.g., ETH, MATIC)." }, "symbol": { "type": "string", "description": "Token symbol (e.g., USDC)." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Token decimals." } } }, "EvmAuthCaptureEscrowConfig": { "type": "object", "description": "Handler configuration for auth/capture escrow on EVM chains.", "required": [ "chain_id", "contract", "operator", "receiver", "accepted_tokens" ], "additionalProperties": true, "properties": { "chain_id": { "type": "integer", "minimum": 1, "description": "EVM chain id for the escrow contract." }, "contract": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Escrow contract address on the target chain." }, "operator": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Operator address authorized to drive state transitions." }, "receiver": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Default receiver address for captures." }, "accepted_tokens": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/EvmToken" }, "description": "Tokens accepted on the escrow contract chain." } } }, "EvmAuthCaptureEscrowInstrument": { "description": "Payment instrument for auth/capture escrow on EVM chains.", "allOf": [ { "$ref": "#/components/schemas/PaymentInstrument" }, { "$ref": "#/components/schemas/EvmAuthCaptureEscrowInstrumentDetails" }, { "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "evm_auth_capture_escrow" ] } }, "type": "object" } ] }, "PaymentCredential": { "type": "object", "description": "The base definition for any payment credential. Handlers define specific credential types.", "required": [ "type" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "The credential type discriminator. Specific schemas will constrain this to a constant value." } } }, "PaymentInstrument": { "type": "object", "description": "The base definition for any payment instrument. It links the instrument to a specific payment handler.", "required": [ "id", "handler_id", "type" ], "properties": { "id": { "type": "string", "description": "A unique identifier for this instrument instance, assigned by the platform." }, "handler_id": { "type": "string", "description": "The unique identifier for the handler instance that produced this instrument. This corresponds to the 'id' field in the Payment Handler definition." }, "type": { "type": "string", "description": "The broad category of the instrument (e.g., 'card', 'tokenized_card'). Specific schemas will constrain this to a constant value." }, "billing_address": { "description": "The billing address associated with this payment method.", "type": "object", "properties": { "extended_address": { "type": "string", "description": "An address extension such as an apartment number, C/O or alternative name." }, "street_address": { "type": "string", "description": "The street address." }, "address_locality": { "type": "string", "description": "The locality in which the street address is, and which is in the region. For example, Mountain View." }, "address_region": { "type": "string", "description": "The region in which the locality is, and which is in the country. Required for applicable countries (i.e. state in US, province in CA). For example, California or another appropriate first-level Administrative division." }, "address_country": { "type": "string", "description": "The country. Recommended to be in 2-letter ISO 3166-1 alpha-2 format, for example \"US\". For backward compatibility, a 3-letter ISO 3166-1 alpha-3 country code such as \"SGP\" or a full country name such as \"Singapore\" can also be used." }, "postal_code": { "type": "string", "description": "The postal code. For example, 94043." }, "first_name": { "type": "string", "description": "Optional. First name of the contact associated with the address." }, "last_name": { "type": "string", "description": "Optional. Last name of the contact associated with the address." }, "phone_number": { "type": "string", "description": "Optional. Phone number of the contact associated with the address." } } }, "credential": { "$ref": "#/components/schemas/PaymentCredential" }, "display": { "type": "object", "description": "Display information for this payment instrument. Each payment instrument schema defines its specific display properties, as outlined by the payment handler.", "additionalProperties": true } }, "additionalProperties": true }, "Payment": { "type": "object", "description": "Payment configuration containing handlers.", "properties": { "instruments": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentInstrument" }, "description": "The payment instruments available for this payment. Each instrument is associated with a specific handler via the handler_id field. Handlers can extend the base payment_instrument schema to add handler-specific fields." } }, "required": [ "instruments" ] }, "DeliveryEventVocabulary": { "type": "object", "description": "Schema for delivery event vocabularies.", "required": [ "name", "version", "title", "description", "events" ], "additionalProperties": false, "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$", "description": "Standard identifier in reverse-domain notation (e.g., xyz.localprotocol.delivery.courier)." }, "version": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Version in YYYY-MM-DD format." }, "extends": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+@\\d{4}-\\d{2}-\\d{2}$" }, "description": "Parent standard this standard extends (optional). Only one parent is allowed; the reference must include a version date. Used for lineage and discovery." }, "title": { "type": "string", "description": "Human-readable title for the standard." }, "description": { "type": "string", "description": "Human-readable description of the standard." }, "spec": { "type": "string", "format": "uri", "description": "URL to human-readable specification document." }, "events": { "type": "object", "additionalProperties": { "type": "object", "properties": { "description": { "type": "string", "description": "Human-readable description of the event." } }, "required": [ "description" ], "additionalProperties": false }, "description": "Map of all event IDs supported by this standard, including inherited events." } } }, "RequestId": { "type": "string", "description": "Delivery request identifier." }, "QuoteId": { "type": "string", "description": "Quote identifier." }, "DeliveryId": { "type": "string", "description": "Delivery identifier." }, "MerchantId": { "type": "string", "description": "Merchant identifier." }, "OrderRequestId": { "type": "string", "description": "Order request identifier." }, "OrderQuoteId": { "type": "string", "description": "Order quote identifier." }, "OrderId": { "type": "string", "description": "Order identifier." }, "EventVocabularyName": { "type": "string", "description": "Event vocabulary name in reverse-domain notation (e.g., xyz.localprotocol.delivery.courier)." }, "SelectedPaymentInstrumentSelectionState": { "type": "object", "properties": { "selected": { "type": "boolean", "description": "Whether this instrument is selected by the user." } } }, "SelectedPaymentInstrument": { "description": "A payment instrument with selection state.", "allOf": [ { "$ref": "#/components/schemas/PaymentInstrument" }, { "$ref": "#/components/schemas/SelectedPaymentInstrumentSelectionState" } ] }, "EvmAuthCaptureEscrowInstrumentDetails": { "type": "object", "properties": { "payment_info_hash": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$", "description": "Hash that identifies the on-chain payment authorization." }, "operator": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Operator address used to compute the payment info hash." }, "payer": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Payer address used to compute the payment info hash." }, "receiver": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Receiver address used for captures." }, "token": { "type": "object", "properties": { "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "ERC-20 contract address. Omit for native gas tokens (e.g., ETH, MATIC)." }, "symbol": { "type": "string", "description": "Token symbol (e.g., USDC)." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Token decimals." } }, "required": [ "symbol", "decimals" ], "additionalProperties": false, "description": "EVM token." }, "max_amount": { "type": "object", "properties": { "value": { "type": "string", "pattern": "^[0-9]+$", "description": "Value in atomic token units as an integer string." }, "currency": { "type": "object", "properties": { "chain_id": { "type": "integer", "minimum": 1, "description": "EVM chain id." }, "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Token contract address." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Decimal places for the token." } }, "required": [ "chain_id", "address", "decimals" ], "additionalProperties": false, "description": "EVM token currency." } }, "required": [ "value", "currency" ], "additionalProperties": false, "description": "Maximum amount that can be authorized (atomic units). Currency chain_id MUST match the instrument chain_id; currency address and decimals MUST match token address and decimals." }, "preapproval_expires_at": { "type": "string", "format": "date-time", "description": "Pre-approval expiration timestamp (RFC 3339)." }, "authorization_expires_at": { "type": "string", "format": "date-time", "description": "Authorization expiration timestamp (RFC 3339)." }, "refund_expires_at": { "type": "string", "format": "date-time", "description": "Refund expiration timestamp (RFC 3339)." }, "nonce": { "type": "string", "pattern": "^[0-9]+$", "description": "Unique nonce used to compute the payment info hash." }, "chain_id": { "type": "integer", "minimum": 1, "description": "EVM chain id for the escrow contract." }, "contract": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Escrow contract address on the target chain." }, "amount": { "type": "object", "properties": { "value": { "type": "string", "pattern": "^[0-9]+$", "description": "Value in atomic token units as an integer string." }, "currency": { "type": "object", "properties": { "chain_id": { "type": "integer", "minimum": 1, "description": "EVM chain id." }, "address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Token contract address." }, "decimals": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Decimal places for the token." } }, "required": [ "chain_id", "address", "decimals" ], "additionalProperties": false, "description": "EVM token currency." } }, "required": [ "value", "currency" ], "additionalProperties": false, "description": "Amount in atomic units. Currency chain_id MUST match the instrument chain_id; currency address and decimals MUST match token address and decimals." } }, "required": [ "payment_info_hash", "operator", "payer", "receiver", "token", "max_amount", "preapproval_expires_at", "authorization_expires_at", "refund_expires_at", "nonce", "chain_id", "contract", "amount" ], "additionalProperties": true } } }, "webhooks": {} }