{ "openapi": "3.1.0", "info": { "title": "Atlas Pay Merchant API", "version": "1.0.0-preview", "description": "Merchant catalog and orders, hosted or Elements standalone checkout, currency presentment, delivery capture, refunds and automatic risk gates. Developer preview requiring deployment and migrations through 0016 (inspect the remote migration list first). Catalog orders use card-only manual capture and fixed currency; eligible standalone checkouts request Adaptive Pricing. Buyer wallet endpoints use web sessions. Real Stripe and storefront acceptance remain launch gates. Prepared by Kyle Campbell.", "contact": { "name": "Atlas Pay", "url": "https://dashboard.atlaspay.sh/docs" } }, "servers": [ { "url": "https://dashboard.atlaspay.sh/api/v1" } ], "security": [ { "merchantKey": [] } ], "tags": [ { "name": "Account" }, { "name": "Checkouts" }, { "name": "Refunds" }, { "name": "Events" }, { "name": "Products" }, { "name": "Orders" } ], "paths": { "/account": { "get": { "operationId": "getAccount", "tags": [ "Account" ], "summary": "Read the authenticated workspace", "description": "Requires account:read. Keys are scoped to a workspace and mode, not a single customer or order.", "responses": { "200": { "description": "Workspace and key capabilities", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "request_id": { "type": "string" }, "data": { "$ref": "#/components/schemas/Account" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/capabilities": { "get": { "operationId": "getCapabilities", "tags": [ "Account" ], "summary": "Read merchant-country currency rules", "description": "Requires account:read. Stripe Country Specs indicate charge currency support, not guaranteed onboarding or availability of each local payment method.", "responses": { "200": { "description": "Currency precision and charge-unit multiples", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "request_id": { "type": "string" }, "data": { "type": "object", "required": [ "merchant_country", "mode", "payments_enabled", "currencies", "payment_methods", "note" ], "properties": { "merchant_country": { "type": "string" }, "mode": { "enum": [ "test", "live" ] }, "payments_enabled": { "type": "boolean" }, "payment_methods": { "const": "dynamic" }, "note": { "type": "string" }, "currencies": { "type": "array", "items": { "$ref": "#/components/schemas/Currency" } } } } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/checkouts": { "post": { "operationId": "createCheckout", "tags": [ "Checkouts" ], "summary": "Create or replay a one-time hosted or Elements checkout", "description": "Requires checkouts:write and completed Stripe onboarding. Amounts must come from your authoritative server-side order. Do not fulfill on this response or a browser redirect. Reuse the same idempotency key and exact body after uncertain results. A replay returns current resource status and may have a null URL. Elements creation/replay can disclose a client secret only for an open pending session. Authorize buyer access and never log the body. Original amount/currency are preserved when Adaptive Pricing converts the buyer amount.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckout" } } } }, "responses": { "201": { "$ref": "#/components/responses/CheckoutCreation" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/checkouts/{id}": { "get": { "operationId": "getCheckout", "tags": [ "Checkouts" ], "summary": "Retrieve current processor-verified checkout status", "description": "Requires checkouts:read. Cross-workspace or wrong-mode IDs return 404. Verify reference, original amount/currency, and mode. Fulfill only when status paid, risk_decision allow and fulfillment_allowed true. Never includes a client secret.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cs_" } } ], "responses": { "200": { "$ref": "#/components/responses/Checkout" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/refunds": { "post": { "operationId": "createRefund", "tags": [ "Refunds" ], "summary": "Create or replay a full or partial refund", "description": "Requires refunds:write. Only a paid checkout in this workspace and mode is eligible. Stripe enforces remaining refundable balance. Use a distinct idempotency key for each distinct refund; retry the same refund with the same key/body. Pending or requires_action is not success.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRefund" } } } }, "responses": { "201": { "$ref": "#/components/responses/Refund" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/refunds/{id}": { "get": { "operationId": "getRefund", "tags": [ "Refunds" ], "summary": "Retrieve current refund status", "description": "Requires refunds:read. Only refunds created through this merchant API can be retrieved. Ownership and mode are verified before a Stripe request.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^re_" } } ], "responses": { "200": { "$ref": "#/components/responses/Refund" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/events": { "get": { "operationId": "listEvents", "tags": [ "Events" ], "summary": "Read a durable event page for recovery", "description": "Requires events:read. Returns up to 100 events in increasing sequence order, scoped to workspace and mode across all its keys. Sequence gaps are normal. Persist next_cursor only after processing; continue while has_more. Re-read current resource status to handle out-of-order updates.", "parameters": [ { "name": "after", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "default": 0 } } ], "responses": { "200": { "description": "Event page", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_cursor", "request_id" ], "properties": { "data": { "type": "array", "maxItems": 100, "items": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "required": [ "sequence" ], "properties": { "sequence": { "type": "integer", "minimum": 1 } } } ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "integer" }, "request_id": { "type": "string" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/products": { "get": { "operationId": "listProducts", "tags": [ "Products" ], "summary": "List workspace and mode catalog products", "description": "Requires products:read. Includes inactive items. 50 items per page, by ID.", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 100 }, "description": "Literal name/SKU substring search. Percent and underscore are not wildcards." }, { "name": "after", "in": "query", "schema": { "type": "string", "maxLength": 100 }, "description": "Use the previous response's next_cursor; IDs are not time-sorted." } ], "responses": { "200": { "description": "Product page", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_cursor", "request_id" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" }, "maxItems": 50 }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createProduct", "tags": [ "Products" ], "summary": "Create a catalog product", "description": "Requires products:write. Inactive by default. Case-sensitive unique SKU prevents duplicate creation; reconcile by listing after an uncertain result. No Idempotency-Key required. This does not charge a buyer.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProduct" } } } }, "responses": { "201": { "description": "Product resource", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "$ref": "#/components/schemas/Product" }, "request_id": { "type": "string" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/products/{id}": { "get": { "operationId": "getProduct", "tags": [ "Products" ], "summary": "Retrieve one catalog product", "description": "Requires products:read. Scoped to workspace and mode.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "Product resource", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "$ref": "#/components/schemas/Product" }, "request_id": { "type": "string" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "put": { "operationId": "updateProduct", "tags": [ "Products" ], "summary": "Replace editable product fields", "description": "Requires products:write. expected_version prevents lost edits; 409 on stale version or duplicate SKU. Existing order prices do not change.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 100 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProduct" } } } }, "responses": { "200": { "description": "Product resource", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "$ref": "#/components/schemas/Product" }, "request_id": { "type": "string" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/products/import": { "post": { "operationId": "importProducts", "tags": [ "Products" ], "summary": "Validate or atomically import up to 50 new products", "description": "Requires products:write. JSON, not raw CSV; 256 KiB maximum. dry_run=true writes nothing and returns an empty data array. Duplicate SKUs reject the full batch; never overwrites. No Idempotency-Key: reconcile SKU existence after an uncertain response.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportProducts" } } } }, "responses": { "200": { "description": "Validation or import result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportResult" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/orders": { "get": { "operationId": "listOrders", "tags": [ "Orders" ], "summary": "List stored catalog orders", "description": "Requires orders:read. Stored snapshots, NOT fresh processor verification. Retrieve a specific order before fulfillment.", "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string", "maxLength": 100 }, "description": "Use the previous response's next_cursor; IDs are not time-sorted." } ], "responses": { "200": { "description": "Order page", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_cursor", "request_id" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" }, "maxItems": 50 }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createOrder", "tags": [ "Orders" ], "summary": "Create a server-priced hosted or Atlas wallet order", "description": "Requires orders:write, enabled Connect charges and card-only delivery configuration. New orders use capture_policy on_delivery: authorize at checkout, capture only after trusted delivery confirmation. payment_flow defaults to hosted; atlas_wallet defers checkout until signed-in buyer confirmation. Prices come from active workspace products; merchant calculates shipping/tax. No inventory reservation. Physical products require shipping countries. Reference is unique per workspace/mode. Retry with the same key/body. Creation does not authorize or capture funds.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrder" } } } }, "responses": { "201": { "description": "Order resource", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "$ref": "#/components/schemas/Order" }, "request_id": { "type": "string" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/orders/{id}": { "get": { "operationId": "getOrder", "tags": [ "Orders" ], "summary": "Retrieve and verify current order payment", "description": "Requires orders:read. Verifies current session, PaymentIntent and charge in the original account. on_delivery dispatch requires authorized, no settlement_action, no refund/dispute, and a future capture_before compatible with delivery. Legacy automatic orders require paid before fulfillment. Deduplicate shipments and verify reference/items/total/mode/shipping. GET never captures or cancels funds.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 100 } } ], "responses": { "200": { "description": "Order resource", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "$ref": "#/components/schemas/Order" }, "request_id": { "type": "string" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/orders/{id}/delivery": { "post": { "operationId": "confirmOrderDelivery", "tags": ["Orders"], "summary": "Attest actual delivery and capture the existing authorization", "description": "Requires orders:deliver and an Idempotency-Key. on_delivery orders only. Persists delivery before capturing the full stored total on the original account. The trusted caller must verify actual delivery evidence. A 200 may still mean processing; inspect payment_status. Retry the exact body/key/timestamp. Competing cancellation or changed proof/key returns 409. Expired/unknown holds and unresolved actions older than 23 hours require review. No replacement charge or partial capture.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ord_[a-f0-9]{32}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Delivery" } } } }, "responses": { "200": { "$ref": "#/components/responses/OrderAction" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/orders/{id}/cancel": { "post": { "operationId": "cancelOrderAuthorization", "tags": ["Orders"], "summary": "Cancel an existing uncaptured authorization", "description": "Requires orders:cancel and an Idempotency-Key. Releases an existing hold for an on_delivery order, not an unpaid-checkout abandonment or refund endpoint. Delivery and cancellation share an exclusive decision. Retry the exact key/body. Only payment_status canceled confirms processor cancellation. Issuers control balance updates. Never automatically refunds or charges another payment.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ord_[a-f0-9]{32}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": ["reason"], "properties": { "reason": { "enum": ["customer_requested", "merchant_unavailable", "delivery_failed"] } } } } } }, "responses": { "200": { "$ref": "#/components/responses/OrderAction" }, "default": { "$ref": "#/components/responses/Error" } } } }, "/orders/{id}/fulfillment": { "post": { "operationId": "fulfillOrder", "tags": [ "Orders" ], "summary": "Record merchant fulfillment and tracking", "description": "Legacy capture_policy automatic only; requires orders:write. New on_delivery orders return 409 and must use /delivery with its separate scope after actual delivery. Fresh processor verification refuses unpaid, refunded or disputed legacy orders. Identical retries are idempotent; conflicting records return 409. Does not ship goods, buy labels, or deliver downloads.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 100 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fulfillment" } } } }, "responses": { "200": { "description": "Order resource", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "$ref": "#/components/schemas/Order" }, "request_id": { "type": "string" } } } } } }, "default": { "$ref": "#/components/responses/Error" } } } } }, "webhooks": { "paymentUpdate": { "post": { "summary": "Signed merchant callback", "description": "Delivered to the HTTPS URL registered with the creating key. Verify HMAC-SHA256(timestamp + '.' + raw body), accept timestamps within 300 seconds, compare in constant time, deduplicate event ID, verify mode and current resource, and acknowledge only after durable processing. At least once and unordered. Cron attempts up to 20 deliveries per minute, max 12 attempts/event, 8-second timeout, exponential backoff capped at 6 hours. Revoking the key stops callbacks. Recover using GET /events.", "security": [], "parameters": [ { "name": "Atlas-Signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^t=[0-9]+,v1=[a-f0-9]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Durably processed or duplicate event" }, "default": { "description": "Non-2xx triggers retry; redirects are not followed" } } } } }, "components": { "securitySchemes": { "merchantKey": { "type": "http", "scheme": "bearer", "bearerFormat": "ap_test_<64 hex> or ap_live_<64 hex>", "description": "Server-only secret from Developers. A key is shown once, has explicit permissions and expiry, and can be revoked by its workspace owner." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical operation, scoped by workspace/mode/operation type. Reuse after timeout or transient failure. Changed body returns 409. Unresolved operations older than 23 hours return IDEMPOTENCY_EXPIRED and require reconciliation before a new attempt.", "schema": { "type": "string", "minLength": 8, "maxLength": 200, "pattern": "^[!-~]+$" } } }, "responses": { "OrderAction": { "description": "Current order; inspect payment_status and settlement_completed_at, not HTTP status alone", "content": { "application/json": { "schema": { "type": "object", "required": ["data", "request_id"], "properties": { "data": { "$ref": "#/components/schemas/Order" }, "request_id": { "type": "string" } } } } } }, "CheckoutCreation": { "description": "Created or replayed checkout. Open Elements creation may contain a private client secret.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "$ref": "#/components/schemas/CheckoutCreation" }, "request_id": { "type": "string" } } } } } }, "Checkout": { "description": "Checkout resource; creation does not confirm payment", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "$ref": "#/components/schemas/Checkout" }, "request_id": { "type": "string" } } } } } }, "Refund": { "description": "Refund resource; only succeeded means completed", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "$ref": "#/components/schemas/Refund" }, "request_id": { "type": "string" } } } } } }, "Error": { "description": "400 invalid input/processor rejection; 401 invalid, expired, or revoked key; 403 missing scope; 404 inaccessible resource; 409 state or idempotency conflict; 413 body over 16 KiB (256 KiB for product imports); 429 rate limited; 500/502/503 service failure. Retry transient errors with the same key/body and backoff. Limit: 120 requests/minute/key per Cloudflare location, not a globally exact rate.", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait when rate limited", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Delivery": { "type": "object", "additionalProperties": false, "required": ["status", "delivery_reference", "delivered_at"], "properties": { "status": { "const": "delivered" }, "delivery_reference": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,120}$" }, "delivered_at": { "type": "string", "format": "date-time", "description": "Actual delivery time after order creation; at most one minute of future clock skew." } } }, "Amount": { "type": "integer", "minimum": 1, "maximum": 99999999, "description": "Stripe charge units. USD 25.00 = 2500, JPY 2500 = 2500. ISK/UGX require multiple of 100; supported three-decimal currencies require multiple of 10. Processor minimums and limits also apply." }, "Currency": { "type": "object", "required": [ "code", "decimals", "amount_multiple" ], "properties": { "code": { "type": "string", "pattern": "^[A-Z]{3}$" }, "decimals": { "type": "integer", "enum": [ 0, 2, 3 ] }, "amount_multiple": { "type": "integer", "enum": [ 1, 10, 100 ] } } }, "Account": { "type": "object", "required": [ "id", "name", "country", "default_currency", "mode", "payments_enabled", "site_origin", "webhook_configured", "scopes" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "country": { "type": "string" }, "default_currency": { "type": "string" }, "mode": { "enum": [ "test", "live" ] }, "payments_enabled": { "type": "boolean" }, "site_origin": { "type": "string", "format": "uri" }, "webhook_configured": { "type": "boolean" }, "scopes": { "type": "array", "items": { "enum": [ "account:read", "checkouts:read", "checkouts:write", "refunds:read", "refunds:write", "events:read", "products:read", "products:write", "orders:read", "orders:write" ] } } } }, "Presentment": { "type": "object", "required": [ "amount", "currency", "effective_exchange_rate" ], "properties": { "amount": { "type": "integer", "minimum": 0, "description": "Charge units in the presentment currency." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "effective_exchange_rate": { "type": [ "number", "null" ], "description": "Receipt-only ratio of rounded major-unit presentment to integration amounts; null for unavailable or zero amounts." } } }, "CheckoutCreation": { "allOf": [ { "$ref": "#/components/schemas/Checkout" }, { "type": "object", "properties": { "client_secret": { "type": "string", "description": "Only in open Elements creation/replay. Deliver only to the authorized buyer; never log, cache, persist in the browser, or include in URLs." }, "account_id": { "type": "string", "description": "Connected account for loadStripe stripeAccount; present with client_secret." } } } ] }, "CreateCheckout": { "type": "object", "additionalProperties": false, "required": [ "amount", "currency", "reference", "description", "success_url", "cancel_url" ], "properties": { "amount": { "$ref": "#/components/schemas/Amount" }, "currency": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "reference": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "customer_email": { "type": "string", "format": "email" }, "success_url": { "type": "string", "format": "uri", "description": "Public HTTPS URL on the key's registered origin. No credentials, fragments, or nonstandard ports." }, "cancel_url": { "type": "string", "format": "uri", "description": "Same origin restrictions as success_url." }, "ui_mode": { "enum": [ "hosted", "elements" ], "default": "hosted", "description": "Elements uses success_url as return_url. cancel_url is validated but navigation belongs to your page." }, "adaptive_pricing": { "type": "boolean", "default": true, "description": "Request Stripe Adaptive Pricing for eligible payments. Offered currencies depend on account, settlement and buyer eligibility." } } }, "Checkout": { "type": "object", "required": [ "id", "object", "reference", "amount", "currency", "status", "payment_status", "payment_id", "url", "livemode", "expires_at", "created_at", "risk_decision", "fulfillment_allowed", "ui_mode", "presentment" ], "properties": { "id": { "type": "string" }, "object": { "const": "checkout" }, "reference": { "type": "string" }, "amount": { "type": [ "integer", "null" ], "description": "Original integration amount; verify this against your server order and use its currency for refunds." }, "currency": { "type": "string" }, "status": { "enum": [ "pending", "paid", "expired", "failed", "review", "blocked" ], "description": "Atlas checkout state. review/blocked prevent fulfillment even when payment_status is paid." }, "payment_status": { "enum": [ "paid", "unpaid", "no_payment_required" ] }, "payment_id": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ], "format": "uri" }, "livemode": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "risk_decision": { "enum": [ "pending", "allow", "review", "block" ], "description": "Latest automatic risk assessment. Re-read the checkout before fulfillment." }, "fulfillment_allowed": { "type": "boolean", "description": "True only when payment is paid, risk is allow and no refund is recorded. All amount, currency, ownership and fulfillment checks still apply." }, "ui_mode": { "enum": [ "hosted", "elements" ] }, "presentment": { "anyOf": [ { "$ref": "#/components/schemas/Presentment" }, { "type": "null" } ], "description": "Actual buyer amount from Stripe, when available. Not a pre-payment quote." } } }, "CreateRefund": { "type": "object", "additionalProperties": false, "required": [ "checkout_id", "amount", "reference" ], "properties": { "checkout_id": { "type": "string", "pattern": "^cs_[A-Za-z0-9_]+$" }, "amount": { "$ref": "#/components/schemas/Amount" }, "reference": { "type": "string", "minLength": 1, "maxLength": 120 } } }, "Refund": { "type": "object", "required": [ "id", "object", "checkout_id", "reference", "amount", "currency", "status", "payment_id", "created_at" ], "properties": { "id": { "type": "string" }, "object": { "const": "refund" }, "checkout_id": { "type": [ "string", "null" ] }, "reference": { "type": [ "string", "null" ] }, "amount": { "type": "integer" }, "currency": { "type": "string" }, "status": { "enum": [ "pending", "requires_action", "succeeded", "failed", "canceled", null ] }, "payment_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "Event": { "type": "object", "required": [ "id", "type", "created_at", "livemode", "data" ], "properties": { "id": { "type": "string" }, "type": { "enum": [ "checkout.updated", "refund.updated", "order.paid", "order.authorized", "order.delivered", "order.canceled", "order.authorization_expired", "order.authorization_review", "order.risk_blocked", "order.risk_review", "order.payment_updated", "order.fulfilled", "payment.risk_updated" ] }, "created_at": { "type": "string", "format": "date-time" }, "livemode": { "type": "boolean" }, "data": { "oneOf": [ { "$ref": "#/components/schemas/Checkout" }, { "$ref": "#/components/schemas/Refund" }, { "$ref": "#/components/schemas/Order" }, { "$ref": "#/components/schemas/PaymentRiskUpdate" } ] } } }, "PaymentRiskUpdate": { "type": "object", "required": [ "payment_id", "risk_decision", "fulfillment_allowed" ], "properties": { "payment_id": { "type": "string" }, "risk_decision": { "enum": [ "allow", "review", "block" ] }, "fulfillment_allowed": { "type": "boolean" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "request_id": { "type": "string", "description": "Present when the Worker handled the request. A frontend upstream-connect failure may omit it." } } }, "CreateProduct": { "type": "object", "required": [ "sku", "name", "amount", "currency" ], "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 2000, "default": "" }, "variant": { "type": "string", "maxLength": 120, "default": "" }, "amount": { "$ref": "#/components/schemas/Amount" }, "currency": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "kind": { "enum": [ "physical", "digital", "service" ], "default": "physical" }, "active": { "type": "boolean", "default": false } }, "additionalProperties": false }, "Product": { "type": "object", "required": [ "id", "object", "sku", "name", "description", "variant", "amount", "currency", "kind", "active", "version", "livemode", "created_at", "updated_at" ], "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 2000, "default": "" }, "variant": { "type": "string", "maxLength": 120, "default": "" }, "amount": { "$ref": "#/components/schemas/Amount" }, "currency": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "kind": { "enum": [ "physical", "digital", "service" ], "default": "physical" }, "active": { "type": "boolean", "default": false }, "id": { "type": "string" }, "object": { "const": "product" }, "version": { "type": "integer", "minimum": 1 }, "livemode": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "UpdateProduct": { "type": "object", "required": [ "product", "expected_version" ], "properties": { "product": { "$ref": "#/components/schemas/CreateProduct" }, "expected_version": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, "ImportProducts": { "type": "object", "required": [ "products" ], "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/CreateProduct" }, "minItems": 1, "maxItems": 50 }, "dry_run": { "type": "boolean", "default": false } }, "additionalProperties": false }, "ImportResult": { "type": "object", "required": [ "data", "validated", "imported", "request_id" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "validated": { "type": "integer" }, "imported": { "type": "integer" }, "request_id": { "type": "string" } } }, "CreateOrder": { "type": "object", "required": [ "reference", "items", "success_url", "cancel_url" ], "properties": { "payment_flow": { "type": "string", "enum": ["hosted", "atlas_wallet"], "default": "hosted", "description": "atlas_wallet returns an Atlas buyer-review link; requires wallet configuration and migration 0009. No payment session is created until the buyer selects a card." }, "reference": { "type": "string", "maxLength": 120, "minLength": 1 }, "items": { "type": "array", "items": { "type": "object", "required": [ "product_id", "quantity" ], "properties": { "product_id": { "type": "string", "pattern": "^prod_[a-f0-9]{32}$" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false }, "minItems": 1, "maxItems": 10 }, "shipping_amount": { "type": "integer", "minimum": 0, "maximum": 99999999, "default": 0 }, "tax_amount": { "type": "integer", "minimum": 0, "maximum": 99999999, "default": 0 }, "shipping_countries": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "maxItems": 20, "default": [], "description": "Required for physical items; list only countries you can ship to. Stripe determines valid supported codes." }, "customer_email": { "type": "string", "maxLength": 254, "format": "email" }, "success_url": { "type": "string", "format": "uri", "description": "Public HTTPS on the API key's exact registered website origin." }, "cancel_url": { "type": "string", "format": "uri", "description": "Same origin restrictions as success_url." } }, "additionalProperties": false }, "OrderItem": { "type": "object", "required": [ "product_id", "sku", "name", "variant", "quantity", "unit_amount", "amount", "kind", "version" ], "properties": { "product_id": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "variant": { "type": "string" }, "quantity": { "type": "integer" }, "unit_amount": { "$ref": "#/components/schemas/Amount" }, "amount": { "$ref": "#/components/schemas/Amount" }, "kind": { "enum": [ "physical", "digital", "service" ] }, "version": { "type": "integer" } } }, "Fulfillment": { "type": "object", "required": [ "status" ], "properties": { "status": { "const": "fulfilled" }, "carrier": { "type": "string", "maxLength": 120, "default": "" }, "tracking_number": { "type": "string", "maxLength": 200, "default": "" }, "tracking_url": { "anyOf": [ { "type": "string", "format": "uri", "description": "Public HTTPS without credentials, fragments or nonstandard ports." }, { "const": "" } ], "default": "" } }, "additionalProperties": false }, "Order": { "type": "object", "required": [ "id", "object", "reference", "items", "amount", "currency", "shipping_amount", "tax_amount", "checkout_id", "payment_status", "capture_policy", "authorized_at", "capture_before", "payment_checked_at", "settlement_action", "settlement_completed_at", "amount_refunded", "fulfillment_status", "customer_email", "shipping_details", "fulfillment", "livemode", "paid_at", "created_at", "updated_at" ], "properties": { "capture_policy": { "enum": ["automatic", "on_delivery"], "description": "New catalog orders use on_delivery; legacy records retain automatic." }, "authorized_at": { "type": ["string", "null"], "format": "date-time" }, "capture_before": { "type": ["string", "null"], "format": "date-time", "description": "Actual card authorization deadline; never assume a fixed duration." }, "payment_checked_at": { "type": ["string", "null"], "format": "date-time" }, "settlement_action": { "enum": ["deliver", "cancel", null] }, "settlement_completed_at": { "type": ["string", "null"], "format": "date-time" }, "payment_flow": { "enum": ["hosted", "atlas_wallet"], "description": "Present on create/retrieve, not stored list/event snapshots." }, "id": { "type": "string" }, "object": { "const": "order" }, "reference": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } }, "amount": { "$ref": "#/components/schemas/Amount" }, "currency": { "type": "string" }, "shipping_amount": { "type": "integer" }, "tax_amount": { "type": "integer" }, "checkout_id": { "type": [ "string", "null" ] }, "checkout_url": { "type": [ "string", "null" ], "format": "uri", "description": "Present on create/retrieve, not list or event snapshots. For atlas_wallet this is a confidential Atlas review link including its fragment, never the buyer's private saved-card Stripe URL." }, "risk_decision": { "enum": ["pending", "allow", "review", "block"], "description": "Retrieve current state before dispatch or fulfillment. Only allow permits the normal order flow; all existing payment, refund, dispute, delivery and expiry checks still apply. A block is terminal for this order and does not refund or cancel a payment." }, "payment_status": { "enum": [ "pending", "authorized", "authorization_review", "authorization_expired", "processing", "canceled", "paid", "expired", "failed", "disputed" ], "description": "Authorized is not captured payment. authorization_expired can mean deadline passed before processor cancellation is observed. Disputed is a sticky review hold; paid with a positive amount_refunded requires reconciliation." }, "amount_refunded": { "type": "integer", "minimum": 0 }, "fulfillment_status": { "enum": [ "unfulfilled", "fulfilled", "delivered" ] }, "customer_email": { "type": [ "string", "null" ] }, "shipping_details": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "address": { "type": [ "object", "null" ], "properties": { "line1": { "type": [ "string", "null" ] }, "line2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } } } } }, "fulfillment": { "anyOf": [ { "$ref": "#/components/schemas/Delivery" }, { "$ref": "#/components/schemas/Fulfillment" }, { "type": "null" } ] }, "livemode": { "type": "boolean" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }