{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Alzaf Pay — Current Local Merchant API", "version": "0.1.0-local", "description": "Source-audited local runtime contract, not hosted sandbox/live acceptance or exhaustive black-box conformance. 13 implemented v1 operations; settlements absent. Target openapi.json is unchanged. Integer BDT minor units only. Laravel trims input strings and converts empty strings to null before validation; optional nullable fields may normalize, other string fields reject null. Strict JSON object mutation bodies, duplicate JSON keys rejected, 1 MiB body limit. Use Accept:application/json and server-side secret keys; no browser merchant secrets." }, "servers": [ { "url": "http://127.0.0.1:8000/v1", "description": "Local backend only; configure your actual local port. No hosted/live server advertised." } ], "security": [ { "SecretKey": [] } ], "tags": [ { "name": "payments" }, { "name": "refunds" }, { "name": "transactions" }, { "name": "balance" }, { "name": "webhooks" } ], "x-evidence": { "classification": "source-audited-local-contract", "acceptance": "Existing local behavior tests; this document validation does not run financial operations.", "target": "openapi.json", "sourceRoutes": "apps/api/routes/web.php" }, "paths": { "/payment-intents": { "post": { "operationId": "createPaymentIntent", "summary": "Create a local test payment", "tags": [ "payments" ], "description": "Local/testing and test-key context only. Return URLs are optional; current validator accepts http/https URLs up to 2000 characters and does not enforce registration. Unknown fields rejected. merchant_reference is unique per project/environment (duplicate returns 409 INVALID_REQUEST). Customer is optional object, never null. No real provider dispatch.", "x-implementation-status": "local-implemented", "x-runtime-scope": "local-testing-test-mode-only", "x-required-scopes": [ "payments:write" ], "x-idempotency-required": true, "x-source-files": [ "apps/api/app/Http/Controllers/PlatformController.php" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Successful local response.", "headers": { "X-Request-Id": { "schema": { "$ref": "#/components/schemas/RequestId" }, "description": "Support reference; exact successful idempotent replay preserves the original response reference." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PaymentCreated" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "data", "request_id" ], "additionalProperties": false }, "example": { "data": { "id": "pay_01K4XZ1Q0A0000000000000001", "object": "payment_intent", "merchant_reference": "ORDER-1001", "amount": 10050, "currency": "BDT", "status": "CREATED", "refunded_amount": 0, "environment": "test", "merchant_id": "mer_01K4XZ1Q0A0000000000000001", "project_id": "prj_01K4XZ1Q0A0000000000000001", "customer": null, "description": null, "metadata": {}, "success_url": null, "cancel_url": null, "expires_at": "2026-10-17T12:30:00.000000Z", "created_at": "2026-10-17T12:00:00.000000Z", "updated_at": "2026-10-17T12:00:00.000000Z", "checkout_url": "http://127.0.0.1:3000/p/pay_01K4XZ1Q0A0000000000000001#token=EXAMPLE_ONLY" }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "401": { "description": "Missing, revoked, expired, invalid or wrong-environment secret key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_FAILED", "message": "Missing, revoked, expired, invalid or wrong-environment secret key.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "403": { "description": "Key scope or current creator membership/project permissions do not authorize this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHORIZATION_FAILED", "message": "Key scope or current creator membership/project permissions do not authorize this operation.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "409": { "description": "Idempotency key payload conflict or financial state conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "IDEMPOTENCY_CONFLICT", "message": "Idempotency key payload conflict or financial state conflict.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "415": { "description": "Mutation body requires application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "Mutation body requires application/json.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "422": { "description": "Input validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "Input validation failed.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "429": { "description": "Framework request throttling; current route limit is 120 requests/minute, not a merchant capacity guarantee.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the indicated delay.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "500": { "description": "Unexpected framework/server failure. Do not assume an uncertain mutation failed; inspect state or retry with the same idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The request could not be completed. Check the operation status before retrying.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "503": { "description": "Operation is unavailable or requires operational review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "PROVIDER_UNAVAILABLE", "message": "Operation is unavailable or requires operational review.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePayment" }, "example": { "merchant_reference": "ORDER-1001", "amount": 10050, "currency": "BDT" } } } } } }, "/payment-intents/{id}": { "get": { "operationId": "getPaymentIntent", "summary": "Read a scoped payment", "tags": [ "payments" ], "description": "Both paths read the same aggregate. No checkout capability URL or raw provider data is returned. Undeclared query parameters are currently ignored.", "x-implementation-status": "local-implemented", "x-runtime-scope": "scoped-read-or-management", "x-required-scopes": [ "payments:read" ], "x-idempotency-required": false, "x-source-files": [ "apps/api/app/Http/Controllers/PlatformController.php" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Existing identifier in the authenticated key scope; unknown/foreign identifiers return 404." } ], "responses": { "200": { "description": "Successful local response.", "headers": { "X-Request-Id": { "schema": { "$ref": "#/components/schemas/RequestId" }, "description": "Support reference; exact successful idempotent replay preserves the original response reference." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Payment" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "data", "request_id" ], "additionalProperties": false }, "example": { "data": { "id": "pay_01K4XZ1Q0A0000000000000001", "object": "payment_intent", "merchant_reference": "ORDER-1001", "amount": 10050, "currency": "BDT", "status": "CREATED", "refunded_amount": 0, "environment": "test", "merchant_id": "mer_01K4XZ1Q0A0000000000000001", "project_id": "prj_01K4XZ1Q0A0000000000000001", "customer": null, "description": null, "metadata": {}, "success_url": null, "cancel_url": null, "expires_at": "2026-10-17T12:30:00.000000Z", "created_at": "2026-10-17T12:00:00.000000Z", "updated_at": "2026-10-17T12:00:00.000000Z" }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "401": { "description": "Missing, revoked, expired, invalid or wrong-environment secret key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_FAILED", "message": "Missing, revoked, expired, invalid or wrong-environment secret key.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "403": { "description": "Key scope or current creator membership/project permissions do not authorize this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHORIZATION_FAILED", "message": "Key scope or current creator membership/project permissions do not authorize this operation.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "404": { "description": "Resource not found in this key scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "PAYMENT_NOT_FOUND", "message": "Resource not found in this key scope.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "422": { "description": "Input validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "Input validation failed.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "429": { "description": "Framework request throttling; current route limit is 120 requests/minute, not a merchant capacity guarantee.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the indicated delay.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "500": { "description": "Unexpected framework/server failure. This read can be retried; no financial mutation is performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The request could not be completed. Check the operation status before retrying.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } } } } }, "/payments/{id}": { "get": { "operationId": "getPayment", "summary": "Read a scoped payment", "tags": [ "payments" ], "description": "Both paths read the same aggregate. No checkout capability URL or raw provider data is returned. Undeclared query parameters are currently ignored.", "x-implementation-status": "local-implemented", "x-runtime-scope": "scoped-read-or-management", "x-required-scopes": [ "payments:read" ], "x-idempotency-required": false, "x-source-files": [ "apps/api/app/Http/Controllers/PlatformController.php" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Existing identifier in the authenticated key scope; unknown/foreign identifiers return 404." } ], "responses": { "200": { "description": "Successful local response.", "headers": { "X-Request-Id": { "schema": { "$ref": "#/components/schemas/RequestId" }, "description": "Support reference; exact successful idempotent replay preserves the original response reference." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Payment" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "data", "request_id" ], "additionalProperties": false }, "example": { "data": { "id": "pay_01K4XZ1Q0A0000000000000001", "object": "payment_intent", "merchant_reference": "ORDER-1001", "amount": 10050, "currency": "BDT", "status": "CREATED", "refunded_amount": 0, "environment": "test", "merchant_id": "mer_01K4XZ1Q0A0000000000000001", "project_id": "prj_01K4XZ1Q0A0000000000000001", "customer": null, "description": null, "metadata": {}, "success_url": null, "cancel_url": null, "expires_at": "2026-10-17T12:30:00.000000Z", "created_at": "2026-10-17T12:00:00.000000Z", "updated_at": "2026-10-17T12:00:00.000000Z" }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "401": { "description": "Missing, revoked, expired, invalid or wrong-environment secret key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_FAILED", "message": "Missing, revoked, expired, invalid or wrong-environment secret key.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "403": { "description": "Key scope or current creator membership/project permissions do not authorize this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHORIZATION_FAILED", "message": "Key scope or current creator membership/project permissions do not authorize this operation.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "404": { "description": "Resource not found in this key scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "PAYMENT_NOT_FOUND", "message": "Resource not found in this key scope.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "422": { "description": "Input validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "Input validation failed.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "429": { "description": "Framework request throttling; current route limit is 120 requests/minute, not a merchant capacity guarantee.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the indicated delay.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "500": { "description": "Unexpected framework/server failure. This read can be retried; no financial mutation is performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The request could not be completed. Check the operation status before retrying.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } } } } }, "/payment-intents/{id}/confirm": { "post": { "operationId": "confirmPaymentIntent", "summary": "Confirm using MockProvider", "tags": [ "payments" ], "description": "Only local/testing test-mode mock. SUCCESS returns SUCCEEDED; FAILED returns FAILED; PENDING/TIMEOUT/TIMEOUT_THEN_SUCCESS can return PROCESSING, all HTTP 200. Delayed resolution requires the local recovery worker; a timeout is not a definitive failure. Confirmed/unresolved replays do not launch another charge. Expired/terminal conflicts return 409.", "x-implementation-status": "local-implemented", "x-runtime-scope": "local-testing-test-mode-only", "x-required-scopes": [ "payments:write" ], "x-idempotency-required": true, "x-source-files": [ "apps/api/app/Http/Controllers/PlatformController.php" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Existing identifier in the authenticated key scope; unknown/foreign identifiers return 404." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Successful local response.", "headers": { "X-Request-Id": { "schema": { "$ref": "#/components/schemas/RequestId" }, "description": "Support reference; exact successful idempotent replay preserves the original response reference." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Payment" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "data", "request_id" ], "additionalProperties": false }, "example": { "data": { "id": "pay_01K4XZ1Q0A0000000000000001", "object": "payment_intent", "merchant_reference": "ORDER-1001", "amount": 10050, "currency": "BDT", "status": "SUCCEEDED", "refunded_amount": 0, "environment": "test", "merchant_id": "mer_01K4XZ1Q0A0000000000000001", "project_id": "prj_01K4XZ1Q0A0000000000000001", "customer": null, "description": null, "metadata": {}, "success_url": null, "cancel_url": null, "expires_at": "2026-10-17T12:30:00.000000Z", "created_at": "2026-10-17T12:00:00.000000Z", "updated_at": "2026-10-17T12:00:00.000000Z" }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "401": { "description": "Missing, revoked, expired, invalid or wrong-environment secret key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_FAILED", "message": "Missing, revoked, expired, invalid or wrong-environment secret key.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "403": { "description": "Key scope or current creator membership/project permissions do not authorize this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHORIZATION_FAILED", "message": "Key scope or current creator membership/project permissions do not authorize this operation.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "404": { "description": "Resource not found in this key scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "PAYMENT_NOT_FOUND", "message": "Resource not found in this key scope.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "409": { "description": "Idempotency key payload conflict or financial state conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "IDEMPOTENCY_CONFLICT", "message": "Idempotency key payload conflict or financial state conflict.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "415": { "description": "Mutation body requires application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "Mutation body requires application/json.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "422": { "description": "Input validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "Input validation failed.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "429": { "description": "Framework request throttling; current route limit is 120 requests/minute, not a merchant capacity guarantee.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the indicated delay.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "500": { "description": "Unexpected framework/server failure. Do not assume an uncertain mutation failed; inspect state or retry with the same idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The request could not be completed. Check the operation status before retrying.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "503": { "description": "Operation is unavailable or requires operational review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "PROVIDER_UNAVAILABLE", "message": "Operation is unavailable or requires operational review.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmPayment" }, "example": { "payment_method": "mock", "mock_scenario": "SUCCESS" } } } } } }, "/payment-intents/{id}/cancel": { "post": { "operationId": "cancelPaymentIntent", "summary": "Cancel a never-captured resolvable payment", "tags": [ "payments" ], "description": "Request body is optional: omit it and Content-Type when no reason is supplied, or send a JSON object. Idempotency-Key remains required. Allows CREATED/PENDING only when no capture exists and every existing attempt is FAILED; CANCELLED replay is successful. Captured, completed or unresolved provider attempts return 409 PAYMENT_ALREADY_COMPLETED. No provider cancellation is performed. Unlike create/confirm/refund, this service has no local-only guard; that does not establish live acceptance.", "x-implementation-status": "local-implemented", "x-runtime-scope": "scoped-read-or-management", "x-required-scopes": [ "payments:write" ], "x-idempotency-required": true, "x-source-files": [ "apps/api/app/Http/Controllers/PlatformController.php" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Existing identifier in the authenticated key scope; unknown/foreign identifiers return 404." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Successful local response.", "headers": { "X-Request-Id": { "schema": { "$ref": "#/components/schemas/RequestId" }, "description": "Support reference; exact successful idempotent replay preserves the original response reference." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Payment" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "data", "request_id" ], "additionalProperties": false }, "example": { "data": { "id": "pay_01K4XZ1Q0A0000000000000001", "object": "payment_intent", "merchant_reference": "ORDER-1001", "amount": 10050, "currency": "BDT", "status": "CANCELLED", "refunded_amount": 0, "environment": "test", "merchant_id": "mer_01K4XZ1Q0A0000000000000001", "project_id": "prj_01K4XZ1Q0A0000000000000001", "customer": null, "description": null, "metadata": {}, "success_url": null, "cancel_url": null, "expires_at": "2026-10-17T12:30:00.000000Z", "created_at": "2026-10-17T12:00:00.000000Z", "updated_at": "2026-10-17T12:00:00.000000Z" }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "401": { "description": "Missing, revoked, expired, invalid or wrong-environment secret key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_FAILED", "message": "Missing, revoked, expired, invalid or wrong-environment secret key.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "403": { "description": "Key scope or current creator membership/project permissions do not authorize this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHORIZATION_FAILED", "message": "Key scope or current creator membership/project permissions do not authorize this operation.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "404": { "description": "Resource not found in this key scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "PAYMENT_NOT_FOUND", "message": "Resource not found in this key scope.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "409": { "description": "Idempotency key payload conflict or financial state conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "IDEMPOTENCY_CONFLICT", "message": "Idempotency key payload conflict or financial state conflict.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "415": { "description": "Mutation body requires application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "Mutation body requires application/json.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "422": { "description": "Input validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "Input validation failed.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "429": { "description": "Framework request throttling; current route limit is 120 requests/minute, not a merchant capacity guarantee.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the indicated delay.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "500": { "description": "Unexpected framework/server failure. Do not assume an uncertain mutation failed; inspect state or retry with the same idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The request could not be completed. Check the operation status before retrying.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelPayment" }, "example": {} } } } } }, "/refunds": { "post": { "operationId": "createRefund", "summary": "Refund a locally captured mock payment", "tags": [ "refunds" ], "description": "Local/testing test-mode mock captures only. Current simulated refund completes synchronously: HTTP 202 data.status is SUCCEEDED. Remaining captured amount and unresolved reservations are checked under locks. Quoted capture needs a retained refund policy. State/amount conflicts return 409 REFUND_NOT_ALLOWED; real-provider refunds remain unavailable.", "x-implementation-status": "local-implemented", "x-runtime-scope": "local-testing-test-mode-only", "x-required-scopes": [ "refunds:write" ], "x-idempotency-required": true, "x-source-files": [ "apps/api/app/Http/Controllers/PlatformController.php" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Successful local response.", "headers": { "X-Request-Id": { "schema": { "$ref": "#/components/schemas/RequestId" }, "description": "Support reference; exact successful idempotent replay preserves the original response reference." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LocalRefundCreated" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "data", "request_id" ], "additionalProperties": false }, "example": { "data": { "id": "ref_01K4XZ1Q0A0000000000000001", "object": "refund", "payment_id": "pay_01K4XZ1Q0A0000000000000001", "amount": 1000, "currency": "BDT", "status": "SUCCEEDED", "reason": null, "created_at": "2026-10-17T12:05:00.000000Z" }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "401": { "description": "Missing, revoked, expired, invalid or wrong-environment secret key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_FAILED", "message": "Missing, revoked, expired, invalid or wrong-environment secret key.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "403": { "description": "Key scope or current creator membership/project permissions do not authorize this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHORIZATION_FAILED", "message": "Key scope or current creator membership/project permissions do not authorize this operation.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "404": { "description": "Resource not found in this key scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "PAYMENT_NOT_FOUND", "message": "Resource not found in this key scope.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "409": { "description": "Idempotency key payload conflict or financial state conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "IDEMPOTENCY_CONFLICT", "message": "Idempotency key payload conflict or financial state conflict.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "415": { "description": "Mutation body requires application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "Mutation body requires application/json.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "422": { "description": "Input validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "Input validation failed.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "429": { "description": "Framework request throttling; current route limit is 120 requests/minute, not a merchant capacity guarantee.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the indicated delay.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "500": { "description": "Unexpected framework/server failure. Do not assume an uncertain mutation failed; inspect state or retry with the same idempotency key and payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The request could not be completed. Check the operation status before retrying.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "503": { "description": "Operation is unavailable or requires operational review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "PROVIDER_UNAVAILABLE", "message": "Operation is unavailable or requires operational review.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRefund" }, "example": { "payment_id": "pay_01K4XZ1Q0A0000000000000001", "amount": 1000 } } } } } }, "/refunds/{id}": { "get": { "operationId": "getRefund", "summary": "Read a scoped refund", "tags": [ "refunds" ], "description": "Scoped lookup. Optional reason is nullable. Does not execute or retry a refund. Unknown query parameters are currently ignored.", "x-implementation-status": "local-implemented", "x-runtime-scope": "scoped-read-or-management", "x-required-scopes": [ "refunds:read" ], "x-idempotency-required": false, "x-source-files": [ "apps/api/app/Http/Controllers/PlatformController.php" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Existing identifier in the authenticated key scope; unknown/foreign identifiers return 404." } ], "responses": { "200": { "description": "Successful local response.", "headers": { "X-Request-Id": { "schema": { "$ref": "#/components/schemas/RequestId" }, "description": "Support reference; exact successful idempotent replay preserves the original response reference." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Refund" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "data", "request_id" ], "additionalProperties": false }, "example": { "data": { "id": "ref_01K4XZ1Q0A0000000000000001", "object": "refund", "payment_id": "pay_01K4XZ1Q0A0000000000000001", "amount": 1000, "currency": "BDT", "status": "SUCCEEDED", "reason": null, "created_at": "2026-10-17T12:05:00.000000Z" }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "401": { "description": "Missing, revoked, expired, invalid or wrong-environment secret key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_FAILED", "message": "Missing, revoked, expired, invalid or wrong-environment secret key.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "403": { "description": "Key scope or current creator membership/project permissions do not authorize this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHORIZATION_FAILED", "message": "Key scope or current creator membership/project permissions do not authorize this operation.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "404": { "description": "Resource not found in this key scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "PAYMENT_NOT_FOUND", "message": "Resource not found in this key scope.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "422": { "description": "Input validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "Input validation failed.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "429": { "description": "Framework request throttling; current route limit is 120 requests/minute, not a merchant capacity guarantee.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the indicated delay.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "500": { "description": "Unexpected framework/server failure. This read can be retried; no financial mutation is performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The request could not be completed. Check the operation status before retrying.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } } } } }, "/payment-methods": { "get": { "operationId": "listPaymentMethods", "summary": "List current normalized method availability", "tags": [ "payments" ], "description": "Only mock is listed. All availability/refund flags are true only in local/testing with test context, otherwise false. No provider names or real-provider availability are advertised. Unknown query parameters are currently ignored.", "x-implementation-status": "local-implemented", "x-runtime-scope": "scoped-read-or-management", "x-required-scopes": [ "payments:read" ], "x-idempotency-required": false, "x-source-files": [ "apps/api/app/Http/Controllers/PlatformController.php" ], "parameters": [], "responses": { "200": { "description": "Successful local response.", "headers": { "X-Request-Id": { "schema": { "$ref": "#/components/schemas/RequestId" }, "description": "Support reference; exact successful idempotent replay preserves the original response reference." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethod" } }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "data", "request_id" ], "additionalProperties": false }, "example": { "data": [ { "code": "mock", "display_name": "Test payment", "available": true, "supports_refund": true, "supports_partial_refund": true } ], "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "401": { "description": "Missing, revoked, expired, invalid or wrong-environment secret key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_FAILED", "message": "Missing, revoked, expired, invalid or wrong-environment secret key.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "403": { "description": "Key scope or current creator membership/project permissions do not authorize this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHORIZATION_FAILED", "message": "Key scope or current creator membership/project permissions do not authorize this operation.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "422": { "description": "Input validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "Input validation failed.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "429": { "description": "Framework request throttling; current route limit is 120 requests/minute, not a merchant capacity guarantee.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the indicated delay.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "500": { "description": "Unexpected framework/server failure. This read can be retried; no financial mutation is performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The request could not be completed. Check the operation status before retrying.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } } } } }, "/transactions": { "get": { "operationId": "listTransactions", "summary": "List posted capture/refund transactions", "tags": [ "transactions" ], "description": "Only cursor/limit queries accepted. Newest(created_at,id) first; opaque cursor binds scope, resource and limit, expires 15 minutes after first page. Amount is original capture/refund gross, not summed journal debits. Only PAYMENT/REFUND emitted; settlement_id is null. No settlement operations.", "x-implementation-status": "local-implemented", "x-runtime-scope": "scoped-read-or-management", "x-required-scopes": [ "transactions:read" ], "x-idempotency-required": false, "x-source-files": [ "apps/api/app/Http/Controllers/TransactionsController.php" ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Successful local response.", "headers": { "X-Request-Id": { "schema": { "$ref": "#/components/schemas/RequestId" }, "description": "Support reference; exact successful idempotent replay preserves the original response reference." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }, "page": { "$ref": "#/components/schemas/Page" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "data", "page", "request_id" ], "additionalProperties": false }, "example": { "data": [ { "id": "txn_01K4XZ1Q0A0000000000000001", "payment_id": "pay_01K4XZ1Q0A0000000000000001", "refund_id": null, "settlement_id": null, "type": "PAYMENT", "amount": 10050, "currency": "BDT", "created_at": "2026-10-17T12:00:00Z" } ], "page": { "next_cursor": null, "has_more": false }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "401": { "description": "Missing, revoked, expired, invalid or wrong-environment secret key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_FAILED", "message": "Missing, revoked, expired, invalid or wrong-environment secret key.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "403": { "description": "Key scope or current creator membership/project permissions do not authorize this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHORIZATION_FAILED", "message": "Key scope or current creator membership/project permissions do not authorize this operation.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "422": { "description": "Input validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "Input validation failed.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "429": { "description": "Framework request throttling; current route limit is 120 requests/minute, not a merchant capacity guarantee.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the indicated delay.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "500": { "description": "Unexpected framework/server failure. This read can be retried; no financial mutation is performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The request could not be completed. Check the operation status before retrying.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "503": { "description": "Operation is unavailable or requires operational review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "LEDGER_INTEGRITY_ERROR", "message": "Operation is unavailable or requires operational review.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } } } } }, "/balance": { "get": { "operationId": "getBalance", "summary": "Read an audited pending ledger balance", "tags": [ "balance" ], "description": "No query parameters accepted. Audits complete scoped ledger history in a consistent snapshot. pending is MERCHANT_PENDING credit minus debit; available/reserved remain 0 because release/settlement postings are not implemented. Integrity/out-of-range failures return503. This informational view cannot authorize spending and is not provider/bank reconciliation.", "x-implementation-status": "local-implemented", "x-runtime-scope": "scoped-read-or-management", "x-required-scopes": [ "balance:read" ], "x-idempotency-required": false, "x-source-files": [ "apps/api/app/Http/Controllers/BalanceController.php", "apps/api/app/Domain/Ledger/Balance.php" ], "parameters": [], "responses": { "200": { "description": "Successful local response.", "headers": { "X-Request-Id": { "schema": { "$ref": "#/components/schemas/RequestId" }, "description": "Support reference; exact successful idempotent replay preserves the original response reference." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Balance" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "data", "request_id" ], "additionalProperties": false }, "example": { "data": { "currency": "BDT", "pending": 10050, "available": 0, "reserved": 0, "as_of": "2026-10-17T12:00:00Z" }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "401": { "description": "Missing, revoked, expired, invalid or wrong-environment secret key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_FAILED", "message": "Missing, revoked, expired, invalid or wrong-environment secret key.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "403": { "description": "Key scope or current creator membership/project permissions do not authorize this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHORIZATION_FAILED", "message": "Key scope or current creator membership/project permissions do not authorize this operation.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "422": { "description": "Input validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "Input validation failed.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "429": { "description": "Framework request throttling; current route limit is 120 requests/minute, not a merchant capacity guarantee.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the indicated delay.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "500": { "description": "Unexpected framework/server failure. This read can be retried; no financial mutation is performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The request could not be completed. Check the operation status before retrying.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "503": { "description": "Operation is unavailable or requires operational review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "LEDGER_INTEGRITY_ERROR", "message": "Operation is unavailable or requires operational review.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } } } } }, "/webhook-endpoints": { "post": { "operationId": "createWebhookEndpoint", "summary": "Register a scoped webhook endpoint", "tags": [ "webhooks" ], "description": "Requires url and unique nonempty events. Local receiver is allowlisted only in local/testing test context with matching configuration. Public HTTPS is separately disabled by default and requires egress acceptance. No Idempotency-Key support for registration; replay may return duplicate 409, and the signing secret is not returned by listing.", "x-implementation-status": "local-implemented", "x-runtime-scope": "scoped-read-or-management", "x-required-scopes": [ "webhooks:write" ], "x-idempotency-required": false, "x-source-files": [ "apps/api/app/Http/Controllers/PlatformController.php" ], "parameters": [], "responses": { "201": { "description": "Successful local response.", "headers": { "X-Request-Id": { "schema": { "$ref": "#/components/schemas/RequestId" }, "description": "Support reference; exact successful idempotent replay preserves the original response reference." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreatedWebhookEndpoint" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "data", "request_id" ], "additionalProperties": false }, "example": { "data": { "id": "whe_01K4XZ1Q0A0000000000000001", "url": "http://127.0.0.1:9001/webhooks/alzaf-pay", "events": [ "payment.succeeded", "refund.succeeded" ], "enabled": true, "created_at": "2026-10-17T12:00:00.000000Z", "signing_secret": "whsec_EXAMPLE_ONLY" }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "401": { "description": "Missing, revoked, expired, invalid or wrong-environment secret key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_FAILED", "message": "Missing, revoked, expired, invalid or wrong-environment secret key.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "403": { "description": "Key scope or current creator membership/project permissions do not authorize this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHORIZATION_FAILED", "message": "Key scope or current creator membership/project permissions do not authorize this operation.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "409": { "description": "Duplicate URL in project/environment returns 409 INVALID_REQUEST.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "Duplicate URL in project/environment returns 409 INVALID_REQUEST.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "415": { "description": "Mutation body requires application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "Mutation body requires application/json.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "422": { "description": "Input validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "Input validation failed.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "429": { "description": "Framework request throttling; current route limit is 120 requests/minute, not a merchant capacity guarantee.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the indicated delay.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "500": { "description": "Unexpected framework/server failure. Registration has no idempotency guarantee. Inspect/list existing endpoints before deciding what to do; avoid blind replay. A signing secret from a lost creation response cannot be recovered by listing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The request could not be completed. Check the operation status before retrying.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpoint" }, "example": { "url": "http://127.0.0.1:9001/webhooks/alzaf-pay", "events": [ "payment.succeeded", "refund.succeeded" ] } } } } }, "get": { "operationId": "listWebhookEndpoints", "summary": "List registered webhook endpoints", "tags": [ "webhooks" ], "description": "Only cursor/limit accepted. Descending id order; cursor binds resource, scope and limit for 15 minutes. Includes disabled endpoints; never returns signing secrets.", "x-implementation-status": "local-implemented", "x-runtime-scope": "scoped-read-or-management", "x-required-scopes": [ "webhooks:read" ], "x-idempotency-required": false, "x-source-files": [ "apps/api/app/Http/Controllers/PlatformController.php" ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Successful local response.", "headers": { "X-Request-Id": { "schema": { "$ref": "#/components/schemas/RequestId" }, "description": "Support reference; exact successful idempotent replay preserves the original response reference." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "page": { "$ref": "#/components/schemas/Page" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "data", "page", "request_id" ], "additionalProperties": false }, "example": { "data": [ { "id": "whe_01K4XZ1Q0A0000000000000001", "url": "http://127.0.0.1:9001/webhooks/alzaf-pay", "events": [ "payment.succeeded", "refund.succeeded" ], "enabled": true, "created_at": "2026-10-17T12:00:00.000000Z" } ], "page": { "next_cursor": null, "has_more": false }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "401": { "description": "Missing, revoked, expired, invalid or wrong-environment secret key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_FAILED", "message": "Missing, revoked, expired, invalid or wrong-environment secret key.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "403": { "description": "Key scope or current creator membership/project permissions do not authorize this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHORIZATION_FAILED", "message": "Key scope or current creator membership/project permissions do not authorize this operation.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "422": { "description": "Input validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "Input validation failed.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "429": { "description": "Framework request throttling; current route limit is 120 requests/minute, not a merchant capacity guarantee.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the indicated delay.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "500": { "description": "Unexpected framework/server failure. This read can be retried; no financial mutation is performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The request could not be completed. Check the operation status before retrying.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } } } } }, "/webhook-endpoints/{id}": { "delete": { "operationId": "deleteWebhookEndpoint", "summary": "Disable an endpoint without deleting its history", "tags": [ "webhooks" ], "description": "No request body is required. Repeated disable returns 200 for an owned endpoint. Existing in-flight requests may finish. No financial transition and no Idempotency-Key requirement. Nonempty supplied bodies still pass global JSON syntax/type checks but endpoint-specific fields are ignored.", "x-implementation-status": "local-implemented", "x-runtime-scope": "scoped-read-or-management", "x-required-scopes": [ "webhooks:write" ], "x-idempotency-required": false, "x-source-files": [ "apps/api/app/Http/Controllers/PlatformController.php" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "Existing identifier in the authenticated key scope; unknown/foreign identifiers return 404." } ], "responses": { "200": { "description": "Successful local response.", "headers": { "X-Request-Id": { "schema": { "$ref": "#/components/schemas/RequestId" }, "description": "Support reference; exact successful idempotent replay preserves the original response reference." }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DeletedWebhookEndpoint" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "data", "request_id" ], "additionalProperties": false }, "example": { "data": { "id": "whe_01K4XZ1Q0A0000000000000001", "deleted": true }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "401": { "description": "Missing, revoked, expired, invalid or wrong-environment secret key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHENTICATION_FAILED", "message": "Missing, revoked, expired, invalid or wrong-environment secret key.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "403": { "description": "Key scope or current creator membership/project permissions do not authorize this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "AUTHORIZATION_FAILED", "message": "Key scope or current creator membership/project permissions do not authorize this operation.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "404": { "description": "Resource not found in this key scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Resource not found in this key scope.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "422": { "description": "Input validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_REQUEST", "message": "Input validation failed.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "429": { "description": "Framework request throttling; current route limit is 120 requests/minute, not a merchant capacity guarantee.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Retry after the indicated delay.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } }, "500": { "description": "Unexpected framework/server failure. Inspect/list the endpoint state; disabling an owned endpoint is repeatable without an idempotency key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "The request could not be completed. Check the operation status before retrying.", "details": [] }, "request_id": "req_01K4XZ1Q0A0000000000000001" } } } } } } } }, "components": { "schemas": { "RequestId": { "type": "string", "pattern": "^req_[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "PaymentId": { "type": "string", "pattern": "^pay_[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "Environment": { "type": "string", "enum": [ "test", "live" ] }, "Currency": { "type": "string", "const": "BDT" }, "Money": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer BDT minor units (poisha). 10050 means BDT 100.50. Never a decimal or float." }, "Metadata": { "type": "object", "maxProperties": 20, "propertyNames": { "maxLength": 40 }, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Non-sensitive merchant tags. Never credentials or card data." }, "PaymentStatus": { "type": "string", "enum": [ "CREATED", "PENDING", "PROCESSING", "SUCCEEDED", "FAILED", "CANCELLED", "EXPIRED", "PARTIALLY_REFUNDED", "REFUNDED" ] }, "Customer": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 150 }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "phone": { "type": "string", "maxLength": 30 } }, "required": [], "additionalProperties": false }, "Page": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "next_cursor", "has_more" ], "additionalProperties": false }, "CreatePayment": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "currency": { "$ref": "#/components/schemas/Currency" }, "merchant_reference": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "customer": { "$ref": "#/components/schemas/Customer" }, "success_url": { "anyOf": [ { "type": "string", "format": "uri", "pattern": "^https?://", "maxLength": 2000 }, { "type": "null" } ] }, "cancel_url": { "anyOf": [ { "type": "string", "format": "uri", "pattern": "^https?://", "maxLength": 2000 }, { "type": "null" } ] }, "expires_at": { "type": "string", "format": "date-time", "maxLength": 40, "description": "Explicit timezone; valid future timestamp at most 24 hours from server now. Default 30 minutes. Fractional seconds truncate to MySQL second precision." } }, "required": [ "amount", "currency", "merchant_reference" ], "additionalProperties": false }, "ConfirmPayment": { "type": "object", "properties": { "payment_method": { "const": "mock", "type": "string" }, "mock_scenario": { "type": "string", "enum": [ "SUCCESS", "FAILED", "PENDING", "TIMEOUT", "TIMEOUT_THEN_SUCCESS" ], "default": "SUCCESS" } }, "required": [ "payment_method" ], "additionalProperties": false }, "CancelPayment": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500 } }, "required": [], "additionalProperties": false }, "CreateRefund": { "type": "object", "properties": { "payment_id": { "type": "string", "minLength": 1, "description": "Existing project/environment payment identifier. Unknown or foreign IDs return 404." }, "amount": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "reason": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "required": [ "payment_id", "amount" ], "additionalProperties": false }, "Payment": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/PaymentId" }, "object": { "const": "payment_intent", "type": "string" }, "merchant_id": { "type": "string", "pattern": "^mer_[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "project_id": { "type": "string", "pattern": "^prj_[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "environment": { "$ref": "#/components/schemas/Environment" }, "merchant_reference": { "type": "string", "maxLength": 128 }, "amount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer BDT minor units (poisha). 10050 means BDT 100.50. Never a decimal or float." }, "currency": { "$ref": "#/components/schemas/Currency" }, "status": { "$ref": "#/components/schemas/PaymentStatus" }, "refunded_amount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer BDT minor units (poisha). 10050 means BDT 100.50. Never a decimal or float." }, "customer": { "anyOf": [ { "$ref": "#/components/schemas/Customer" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "success_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "cancel_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "object", "merchant_id", "project_id", "environment", "merchant_reference", "amount", "currency", "status", "refunded_amount", "customer", "description", "metadata", "success_url", "cancel_url", "expires_at", "created_at", "updated_at" ], "additionalProperties": false, "description": "Payment snapshot for retrieval, state transitions and webhook data. Does not disclose a checkout capability." }, "PaymentCreated": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/PaymentId" }, "object": { "const": "payment_intent", "type": "string" }, "merchant_id": { "type": "string", "pattern": "^mer_[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "project_id": { "type": "string", "pattern": "^prj_[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "environment": { "$ref": "#/components/schemas/Environment" }, "merchant_reference": { "type": "string", "maxLength": 128 }, "amount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer BDT minor units (poisha). 10050 means BDT 100.50. Never a decimal or float." }, "currency": { "$ref": "#/components/schemas/Currency" }, "status": { "$ref": "#/components/schemas/PaymentStatus" }, "refunded_amount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer BDT minor units (poisha). 10050 means BDT 100.50. Never a decimal or float." }, "customer": { "anyOf": [ { "$ref": "#/components/schemas/Customer" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "success_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "cancel_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "checkout_url": { "type": "string", "format": "uri", "description": "Confidential checkout capability in URL fragment; creation/replay only, never general reads." } }, "required": [ "id", "object", "merchant_id", "project_id", "environment", "merchant_reference", "amount", "currency", "status", "refunded_amount", "customer", "description", "metadata", "success_url", "cancel_url", "expires_at", "created_at", "updated_at", "checkout_url" ], "additionalProperties": false }, "Refund": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^ref_[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "object": { "type": "string", "const": "refund" }, "payment_id": { "$ref": "#/components/schemas/PaymentId" }, "amount": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "currency": { "$ref": "#/components/schemas/Currency" }, "status": { "type": "string", "enum": [ "CREATED", "PROCESSING", "UNKNOWN", "SUCCEEDED", "FAILED" ] }, "reason": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "object", "payment_id", "amount", "currency", "status", "reason", "created_at" ], "additionalProperties": false }, "LocalRefundCreated": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^ref_[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "object": { "type": "string", "const": "refund" }, "payment_id": { "$ref": "#/components/schemas/PaymentId" }, "amount": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "currency": { "$ref": "#/components/schemas/Currency" }, "status": { "type": "string", "const": "SUCCEEDED" }, "reason": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "object", "payment_id", "amount", "currency", "status", "reason", "created_at" ], "additionalProperties": false }, "Transaction": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^txn_[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "payment_id": { "$ref": "#/components/schemas/PaymentId" }, "refund_id": { "anyOf": [ { "type": "string", "pattern": "^ref_[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, { "type": "null" } ] }, "settlement_id": { "type": "null" }, "type": { "type": "string", "enum": [ "PAYMENT", "REFUND" ] }, "amount": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "currency": { "$ref": "#/components/schemas/Currency" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "payment_id", "refund_id", "settlement_id", "type", "amount", "currency", "created_at" ], "additionalProperties": false }, "Balance": { "type": "object", "properties": { "currency": { "$ref": "#/components/schemas/Currency" }, "pending": { "$ref": "#/components/schemas/Money" }, "available": { "type": "integer", "const": 0 }, "reserved": { "type": "integer", "const": 0 }, "as_of": { "type": "string", "format": "date-time" } }, "required": [ "currency", "pending", "available", "reserved", "as_of" ], "additionalProperties": false }, "PaymentMethod": { "type": "object", "properties": { "code": { "type": "string", "const": "mock" }, "display_name": { "type": "string", "const": "Test payment" }, "available": { "type": "boolean" }, "supports_refund": { "type": "boolean" }, "supports_partial_refund": { "type": "boolean" } }, "required": [ "code", "display_name", "available", "supports_refund", "supports_partial_refund" ], "additionalProperties": false }, "CreateWebhookEndpoint": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https?://", "maxLength": 2000, "description": "Default disabled-public-egress baseline accepts only the configured exact local receiver http://127.0.0.1:9001/webhooks/alzaf-pay in test mode. Public HTTPS needs separate enablement and DNS/address validation; this contract does not enable it." }, "events": { "type": "array", "minItems": 1, "maxItems": 10, "uniqueItems": true, "items": { "type": "string", "enum": [ "payment.created", "payment.processing", "payment.succeeded", "payment.failed", "payment.expired", "payment.cancelled", "refund.succeeded", "refund.failed", "settlement.created", "settlement.completed" ] }, "description": "Settlement names are accepted subscriptions only; no settlement producer or API is implemented." } }, "required": [ "url", "events" ], "additionalProperties": false }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^whe_[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "minItems": 1, "maxItems": 10, "uniqueItems": true, "items": { "type": "string", "enum": [ "payment.created", "payment.processing", "payment.succeeded", "payment.failed", "payment.expired", "payment.cancelled", "refund.succeeded", "refund.failed", "settlement.created", "settlement.completed" ] }, "description": "Settlement names are accepted subscriptions only; no settlement producer or API is implemented." }, "enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "url", "events", "enabled", "created_at" ], "additionalProperties": false }, "CreatedWebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^whe_[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "minItems": 1, "maxItems": 10, "uniqueItems": true, "items": { "type": "string", "enum": [ "payment.created", "payment.processing", "payment.succeeded", "payment.failed", "payment.expired", "payment.cancelled", "refund.succeeded", "refund.failed", "settlement.created", "settlement.completed" ] }, "description": "Settlement names are accepted subscriptions only; no settlement producer or API is implemented." }, "enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "signing_secret": { "type": "string", "description": "Shown once. Server-side secret; never returned by listing." } }, "required": [ "id", "url", "events", "enabled", "created_at", "signing_secret" ], "additionalProperties": false }, "DeletedWebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^whe_[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "oneOf": [ { "type": "array", "maxItems": 0 }, { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } ] } }, "required": [ "code", "message", "details" ], "additionalProperties": false }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "error", "request_id" ], "additionalProperties": false } }, "securitySchemes": { "SecretKey": { "type": "http", "scheme": "bearer", "bearerFormat": "alz_test_sk_", "description": "One merchant/project/environment per hashed key. Revocation/expiry and current creator permissions apply. Local financial simulation requires test key. Publishable keys cannot authenticate. Never place a real secret in example files." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" }, "example": "order-1001-create-v1", "description": "Required only for create/confirm/cancel/refund. Same canonical payload and scoped operation returns stored status/body/request_id; changed payload returns 409. No retention-expiry promise is implemented." }, "Cursor": { "name": "cursor", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "description": "Opaque encrypted cursor. Reuse unchanged with same limit; invalid/expired scope binding returns422." }, "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } } } }