{"openapi":"3.1.0","info":{"title":"ForgePay Merchant API","version":"0.1.0","description":"Test-mode foundation for external ForgePay merchant integrations. ForgePay is not a bank and live payouts are not enabled in this MVP."},"servers":[{"url":"http://localhost:3000/api/v1"}],"security":[{"bearerApiKey":[]}],"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"fp_test_xxx or fp_live_xxx"}},"schemas":{"ApiError":{"type":"object","required":["code","message","details","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}}}}},"paths":{"/checkout/sessions":{"post":{"summary":"Create a test-mode checkout session","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":180}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount_fgc","currency","description","success_url","cancel_url"],"properties":{"amount_fgc":{"type":"string","example":"500"},"amount_minor":{"type":"string","deprecated":true,"example":"50000"},"currency":{"type":"string","enum":["FGC"]},"description":{"type":"string","example":"AI image pack"},"customer_email":{"type":"string","format":"email"},"customer_reference":{"type":"string"},"success_url":{"type":"string","format":"uri"},"cancel_url":{"type":"string","format":"uri"},"external_reference":{"type":"string"},"metadata":{"type":"object"}}}}}},"responses":{"201":{"description":"Checkout session created. Response contains checkout_session_id, checkout_url and expires_at."},"400":{"description":"Validation error"},"401":{"description":"Invalid bearer API key"},"409":{"description":"Idempotency key conflict"},"429":{"description":"Rate limited"}}},"get":{"summary":"List checkout sessions","parameters":[{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"status","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Checkout session list"}}}},"/subscriptions":{"post":{"summary":"Create a subscription checkout session","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":180}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount_fgc","currency","interval","description","merchant_customer_reference","success_url","cancel_url"],"properties":{"amount_fgc":{"type":"string","example":"25"},"amount_minor":{"type":"string","deprecated":true,"example":"2500"},"currency":{"type":"string","enum":["FGC"]},"interval":{"type":"string","enum":["daily","weekly","monthly","yearly"]},"description":{"type":"string","example":"AI writing monthly plan"},"merchant_customer_reference":{"type":"string"},"customer_email":{"type":"string","format":"email"},"success_url":{"type":"string","format":"uri"},"cancel_url":{"type":"string","format":"uri"},"external_reference":{"type":"string"},"max_total_amount_fgc":{"type":"string","example":"250"},"end_date":{"type":"string","format":"date-time"},"metadata":{"type":"object"}}}}}},"responses":{"201":{"description":"Subscription created in paused status. Response contains a hosted checkout_url for user approval."},"400":{"description":"Validation error"},"401":{"description":"Invalid bearer API key"},"409":{"description":"Idempotency key conflict"},"429":{"description":"Rate limited"}}},"get":{"summary":"List subscriptions","responses":{"200":{"description":"Subscription list"}}}},"/subscriptions/{subscription_id}/cancel":{"post":{"summary":"Cancel a subscription","parameters":[{"name":"subscription_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Subscription cancelled"},"401":{"description":"Invalid bearer API key"},"404":{"description":"Subscription not found"},"409":{"description":"Subscription is not cancellable"}}}},"/refunds":{"post":{"summary":"Create a refund review placeholder","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":180}}],"responses":{"201":{"description":"Refund placeholder created"}}}},"/balance":{"get":{"summary":"Read merchant test-mode settlement summary","responses":{"200":{"description":"Merchant balance summary"}}}}},"webhooks":{"hmac":{"signatureHeader":"ForgePay-Signature","timestampHeader":"ForgePay-Timestamp","algorithm":"HMAC-SHA256 over `${timestamp}.${rawBody}`"}}}