{"openapi":"3.1.0","info":{"title":"GPT Monetization Gateway - PayPal Checkout","description":"Shared capability discovery, demand measurement, PayPal checkout, and one-use entitlement redemption. NANDEYANEeN is Sandbox-only until a separate Live activation approval.","version":"0.8.0-paypal-sandbox-hardened"},"servers":[{"url":"https://nandeyaneen-sandbox.kgninja.dev","description":"Isolated NANDEYANEeN PayPal Sandbox deployment"}],"externalDocs":{"description":"NANDEYANEeN Action privacy notice","url":"https://nandeyaneen-sandbox.kgninja.dev/privacy"},"security":[{"GptBearerAuth":[]}],"paths":{"/gpt/capabilities":{"get":{"operationId":"getGptCapabilities","summary":"List capabilities for the authenticated GPT","description":"Derives GPT identity only from the Bearer credential. It never trusts a client-supplied source_gpt.","x-openai-isConsequential":false,"responses":{"200":{"description":"Capability and payment state for the credential-derived GPT.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CapabilitiesResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/gpt/action":{"post":{"operationId":"submitGptAction","summary":"Record explicit demand for a future-paid capability","description":"Records demand as an internal side effect of this normal Gateway request. It does not create a checkout, pay, capture, redeem, or unlock.","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionRequest"}}}},"responses":{"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/PaymentRequiredOrBlocked"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"409":{"$ref":"#/components/responses/ReplayConflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/gpt/payment/session":{"post":{"operationId":"createPaypalCheckoutSession","summary":"Create one fixed JPY 100 PayPal checkout","description":"Creates one idempotent PayPal order only after the user explicitly confirms the server-declared environment and fixed JPY 100 one-time price. Sandbox never moves real money. Creation never unlocks an enhanced result.","x-openai-isConsequential":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentSessionRequest"}}}},"responses":{"200":{"description":"Idempotent replay of existing checkout state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentSessionResponse"}}}},"201":{"description":"New fixed-price PayPal checkout created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentSessionResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/PaymentUnavailable"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"409":{"$ref":"#/components/responses/PaymentConflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"$ref":"#/components/responses/BadGateway"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/gpt/entitlement/redeem":{"post":{"operationId":"redeemEnhancedResult","summary":"Consume one verified enhanced-result entitlement","description":"Atomically consumes one PayPal-webhook-verified entitlement. Only fulfillment_unlocked=true authorizes one enhanced result; an exact retry never authorizes a second result.","x-openai-isConsequential":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntitlementRedemptionRequest"}}}},"responses":{"200":{"description":"First consumption or safe non-unlocking replay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntitlementRedemptionResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/PaymentUnavailable"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"409":{"$ref":"#/components/responses/PaymentConflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}},"components":{"securitySchemes":{"GptBearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"GPT-specific API key","description":"A unique high-entropy key configured only in this GPT. D1 stores only its domain-separated SHA-256 hash."}},"schemas":{"SourceGpt":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","description":"Credential-derived GPT slug. Clients never submit it.","examples":["nandeyaneen"]},"UuidV4":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"ActionRequest":{"type":"object","additionalProperties":false,"required":["capability_id","client_request_id"],"properties":{"capability_id":{"type":"string","enum":["premium.enhanced_result","premium.external_action"]},"client_request_id":{"$ref":"#/components/schemas/UuidV4"},"session_id":{"$ref":"#/components/schemas/UuidV4","description":"Optional random UUID. Never derive it from personal data."}}},"PaymentSessionRequest":{"type":"object","additionalProperties":false,"required":["capability_id","client_request_id","expected_environment","price_confirmation"],"properties":{"capability_id":{"type":"string","enum":["premium.enhanced_result"]},"client_request_id":{"$ref":"#/components/schemas/UuidV4"},"expected_environment":{"type":"string","enum":["sandbox","live"]},"price_confirmation":{"type":"string","enum":["JPY_100_ONE_TIME"],"description":"Send only after the user explicitly confirms one JPY 100 one-time checkout in the returned environment."}}},"EntitlementRedemptionRequest":{"type":"object","additionalProperties":false,"required":["capability_id","client_request_id","payment_token","expected_environment"],"properties":{"capability_id":{"type":"string","enum":["premium.enhanced_result"]},"client_request_id":{"$ref":"#/components/schemas/UuidV4"},"payment_token":{"type":"string","minLength":43,"maxLength":43,"pattern":"^[A-Za-z0-9_-]{43}$","description":"Opaque Gateway token. Never ask the user to paste PayPal identifiers."},"expected_environment":{"type":"string","enum":["sandbox","live"]}}},"FixedPaymentAmount":{"type":"object","additionalProperties":false,"required":["value","currency"],"properties":{"value":{"type":"string","enum":["100"]},"currency":{"type":"string","enum":["JPY"]}}},"PaymentSessionResponse":{"type":"object","additionalProperties":false,"required":["code","source_gpt","source_attribution","capability_id","environment","commerce_disclosure_url","amount","one_time","payment_token","approval_url","payment_status","replayed","payments_enabled","real_money","webhook_verified","fulfillment_unlocked"],"properties":{"code":{"type":"string","enum":["PAYPAL_SANDBOX_SESSION_CREATED","PAYPAL_SANDBOX_CAPTURE_PENDING","PAYPAL_SANDBOX_PAYMENT_VERIFIED","PAYPAL_LIVE_SESSION_CREATED","PAYPAL_LIVE_CAPTURE_PENDING","PAYPAL_LIVE_PAYMENT_VERIFIED"]},"source_gpt":{"$ref":"#/components/schemas/SourceGpt"},"source_attribution":{"type":"string","enum":["bearer_credential"]},"capability_id":{"type":"string","enum":["premium.enhanced_result"]},"environment":{"type":"string","enum":["sandbox","live"]},"commerce_disclosure_url":{"type":["string","null"],"format":"uri"},"amount":{"$ref":"#/components/schemas/FixedPaymentAmount"},"one_time":{"type":"boolean","enum":[true]},"payment_token":{"type":"string","minLength":43,"maxLength":43,"pattern":"^[A-Za-z0-9_-]{43}$"},"approval_url":{"type":["string","null"],"format":"uri"},"payment_status":{"type":"string","enum":["created","capture_pending","captured"]},"replayed":{"type":"boolean"},"payments_enabled":{"type":"boolean"},"real_money":{"type":"boolean"},"webhook_verified":{"type":"boolean"},"fulfillment_unlocked":{"type":"boolean","enum":[false]}}},"EntitlementRedemptionResponse":{"type":"object","additionalProperties":false,"required":["code","source_gpt","capability_id","authorization_id","remaining_uses","replayed","fulfillment_unlocked","real_money","environment"],"properties":{"code":{"type":"string","enum":["PREMIUM_ENHANCED_RESULT_UNLOCKED","ENTITLEMENT_REDEMPTION_REPLAYED"]},"source_gpt":{"$ref":"#/components/schemas/SourceGpt"},"capability_id":{"type":"string","enum":["premium.enhanced_result"]},"authorization_id":{"type":"string","format":"uuid"},"remaining_uses":{"type":"integer","enum":[0]},"replayed":{"type":"boolean"},"fulfillment_unlocked":{"type":"boolean","description":"True only on the first atomic consumption."},"real_money":{"type":"boolean"},"environment":{"type":"string","enum":["sandbox","live"]}}},"Capability":{"type":"object","additionalProperties":false,"required":["id","display_name","description","access_tier","available","status"],"properties":{"id":{"type":"string"},"display_name":{"type":"string"},"description":{"type":"string"},"access_tier":{"type":"string","enum":["free","future_paid"]},"available":{"type":"boolean"},"status":{"type":"string","enum":["active","planned"]}}},"CapabilitiesResponse":{"type":"object","additionalProperties":false,"required":["api_version","source_gpt","source_attribution","payments_enabled","payment_environment","commerce_disclosure_url","entitlement_redemption_enabled","real_money","amount","one_time","entitlement_uses","test_traffic_authorized","capabilities"],"properties":{"api_version":{"type":"string"},"source_gpt":{"$ref":"#/components/schemas/SourceGpt"},"source_attribution":{"type":"string","enum":["bearer_credential"]},"payments_enabled":{"type":"boolean"},"payment_environment":{"type":["string","null"],"enum":["sandbox","live",null]},"commerce_disclosure_url":{"type":["string","null"],"format":"uri"},"entitlement_redemption_enabled":{"type":"boolean"},"real_money":{"type":"boolean"},"amount":{"oneOf":[{"$ref":"#/components/schemas/FixedPaymentAmount"},{"type":"null"}]},"one_time":{"type":["boolean","null"]},"entitlement_uses":{"type":["integer","null"],"minimum":1,"maximum":1},"test_traffic_authorized":{"type":"boolean","description":"Non-secret acknowledgement used only by the automated Sandbox verifier."},"capabilities":{"type":"object","additionalProperties":false,"required":["free","future_paid"],"properties":{"free":{"type":"array","items":{"$ref":"#/components/schemas/Capability"}},"future_paid":{"type":"array","items":{"$ref":"#/components/schemas/Capability"}}}}}},"MonetizationState":{"type":"object","additionalProperties":false,"required":["payments_enabled","payment_environment","real_money","payment_attempted","external_transaction_attempted"],"properties":{"payments_enabled":{"type":"boolean"},"payment_environment":{"type":["string","null"],"enum":["sandbox","live",null]},"real_money":{"type":"boolean"},"payment_attempted":{"type":"boolean"},"external_transaction_attempted":{"type":"boolean"}}},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error","monetization"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"},"source_gpt":{"$ref":"#/components/schemas/SourceGpt"},"capability_id":{"type":"string"},"replayed":{"type":"boolean"}}},"monetization":{"$ref":"#/components/schemas/MonetizationState"}}}},"responses":{"BadRequest":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Bearer key is missing, invalid, revoked, or mapped to an inactive GPT.","headers":{"WWW-Authenticate":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PaymentRequiredOrBlocked":{"description":"Demand was recorded. Checkout either needs explicit confirmation or remains disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PaymentUnavailable":{"description":"Checkout or redemption is disabled, paused, misconfigured, or unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Endpoint, payment, or entitlement was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"MethodNotAllowed":{"description":"Endpoint does not accept this method.","headers":{"Allow":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ReplayConflict":{"description":"Source-scoped request UUID was already bound to another capability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PaymentConflict":{"description":"Payment is pending, terminal, unverified, revoked, or already consumed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PayloadTooLarge":{"description":"JSON body exceeds the bounded request limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"UnsupportedMediaType":{"description":"Content-Type is not application/json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimited":{"description":"Per-GPT rate limit exceeded.","headers":{"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalError":{"description":"Unexpected bounded internal failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"BadGateway":{"description":"Fixed PayPal provider request failed or returned an invalid bounded response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unavailable":{"description":"Authentication, configuration, D1, cryptographic state, or payment verification is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}