{"openapi":"3.1.0","info":{"title":"TrustBill Subscription API","version":"1.1.0","description":"Create recurring plans and subscriptions. Customers must authorize subscriptions through their TrustBill wallet, select a funding asset and confirm with their six-digit payment PIN. Guest crypto checkout is not available for subscriptions."},"servers":[{"url":"https://pay.trustbill.net","description":"Production"}],"tags":[{"name":"Subscription Plans"},{"name":"Subscriptions"},{"name":"Subscription Changes"}],"components":{"securitySchemes":{"MerchantApiKey":{"type":"apiKey","in":"header","name":"X-API-KEY","description":"Merchant API key. Keep live keys on your server only."}},"schemas":{"ApiError":{"type":"object","properties":{"error":{"type":"string","examples":["SUBSCRIPTION_NOT_FOUND"]},"message":{"type":"string"}}},"SubscriptionPlanCreate":{"type":"object","required":["name","amount","currency","interval"],"properties":{"externalReference":{"type":"string","maxLength":200,"examples":["monthly-business-plan"]},"name":{"type":"string","maxLength":200,"examples":["Monthly Business Plan"]},"description":{"type":"string","maxLength":2000},"amount":{"type":"string","pattern":"^\\d+(\\.\\d{1,18})?$","examples":["49.00"]},"currency":{"type":"string","examples":["EUR"]},"interval":{"type":"string","enum":["DAY","WEEK","MONTH","YEAR"]},"intervalCount":{"type":"integer","minimum":1,"maximum":365,"default":1},"trialDays":{"type":"integer","minimum":0,"maximum":365,"default":0},"maximumChargeAmount":{"type":"string","examples":["49.00"]},"metadata":{"type":"object","additionalProperties":true}}},"SubscriptionCreate":{"type":"object","required":["externalReference","planId","successUrl","cancelUrl"],"anyOf":[{"required":["walletUserId"]},{"required":["customerEmail"]}],"properties":{"externalReference":{"type":"string","maxLength":200,"examples":["customer-subscription-001"]},"serviceReference":{"type":"string","maxLength":200},"planId":{"type":"string","format":"uuid"},"walletUserId":{"type":"string","format":"uuid","description":"TrustBill wallet user ID"},"customerEmail":{"type":"string","format":"email","description":"Email of an existing TrustBill wallet user"},"successUrl":{"type":"string","format":"uri"},"cancelUrl":{"type":"string","format":"uri"},"authorizationExpiresInMinutes":{"type":"integer","minimum":5,"maximum":10080,"default":60},"metadata":{"type":"object","additionalProperties":true}}},"SubscriptionAuthorizationResult":{"type":"object","description":"The merchant redirects the customer to authorizationUrl. After login, the customer selects fundingAsset and approves using the payment PIN.","properties":{"subscriptionId":{"type":"string","format":"uuid"},"status":{"type":"string","examples":["PENDING_APPROVAL"]},"authorizationUrl":{"type":"string","format":"uri"},"authorizationExpiresAt":{"type":"string","format":"date-time"}}},"SubscriptionChangeCreate":{"type":"object","required":["requestedPlanId","successUrl","cancelUrl"],"properties":{"requestedPlanId":{"type":"string","format":"uuid"},"effectiveMode":{"type":"string","enum":["IMMEDIATE","NEXT_BILLING"],"default":"NEXT_BILLING"},"immediateChargeAmount":{"type":"string","default":"0"},"successUrl":{"type":"string","format":"uri"},"cancelUrl":{"type":"string","format":"uri"},"reason":{"type":"string","maxLength":1000},"metadata":{"type":"object","additionalProperties":true}}}}},"security":[{"MerchantApiKey":[]}],"paths":{"/api/v1/subscription-plans":{"post":{"tags":["Subscription Plans"],"summary":"Create a subscription plan","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionPlanCreate"}}}},"responses":{"201":{"description":"Plan created"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Invalid API key"}}},"get":{"tags":["Subscription Plans"],"summary":"List subscription plans","responses":{"200":{"description":"Plan list"}}}},"/api/v1/subscription-plans/{id}":{"get":{"tags":["Subscription Plans"],"summary":"Get a subscription plan","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Plan"},"404":{"description":"Plan not found"}}}},"/api/v1/subscriptions":{"post":{"tags":["Subscriptions"],"summary":"Create a subscription authorization","description":"Returns an authorization URL. Redirect the customer to it. Subscriptions require a TrustBill wallet account; external guest crypto payment is not supported. The customer selects the funding asset on the authorization page.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionCreate"}}}},"responses":{"201":{"description":"Authorization created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionAuthorizationResult"}}}},"400":{"description":"Invalid request"},"404":{"description":"Plan or wallet user not found"},"409":{"description":"Conflict"}}},"get":{"tags":["Subscriptions"],"summary":"List subscriptions","responses":{"200":{"description":"Subscription list"}}}},"/api/v1/subscriptions/{id}":{"get":{"tags":["Subscriptions"],"summary":"Get a subscription","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Subscription, current authorization and funding asset"},"404":{"description":"Subscription not found"}}}},"/api/v1/subscriptions/{id}/pause":{"post":{"tags":["Subscriptions"],"summary":"Pause a subscription","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Subscription paused"},"409":{"description":"Invalid status transition"}}}},"/api/v1/subscriptions/{id}/resume":{"post":{"tags":["Subscriptions"],"summary":"Resume a subscription","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Subscription resumed"},"409":{"description":"Invalid status transition"}}}},"/api/v1/subscriptions/{id}/cancel":{"post":{"tags":["Subscriptions"],"summary":"Cancel a subscription","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Subscription cancelled"},"409":{"description":"Invalid status transition"}}}},"/api/v1/subscriptions/{id}/change-sessions":{"post":{"tags":["Subscription Changes"],"summary":"Create a customer-approved plan change","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionChangeCreate"}}}},"responses":{"201":{"description":"Change session created"},"404":{"description":"Subscription or requested plan not found"},"409":{"description":"Conflict"}}}}}}