{"lexicon":1,"id":"money.atmosphere.payment.createManagementSession","defs":{"main":{"type":"procedure","description":"Create a short-lived, single-use subscription management URL for a payer without an ATM sign-in. Requires an app service-auth JWT (iss must be the app that originated the subscription) plus a payer service-auth assertion (lxm money.atmosphere.payment.assertPayer) minted from the payer's live session with the app; the assertion iss must equal payerDid, and payerDid must be the subscription's verified or claimed payer, never a bare app-supplied hint. The URL opens ATM's hosted management surface scoped to the payer's subscriptions with the calling app. Pass at least one of subscriptionId or paymentId to anchor the session; subscriptionId is preferred. The assertion is verified and discarded — never stored or copied to records.","input":{"encoding":"application/json","schema":{"type":"object","required":["payerDid","payerAssertion"],"properties":{"payerDid":{"type":"string","format":"did","description":"The payer DID asserted by the app-held user session."},"payerAssertion":{"type":"string","maxLength":4096,"description":"Single-use payer service-auth JWT (lxm money.atmosphere.payment.assertPayer, aud = the broker DID's #atmosphere_money_broker service, e.g. did:plc:…#atmosphere_money_broker — a bare broker DID audience is rejected) proving the payer is signed in to the calling app right now."},"subscriptionId":{"type":"string","maxLength":256,"description":"Opaque ATM subscription relationship id from money.atmosphere.payment.listSubscriptions. Preferred anchor for the session."},"paymentId":{"type":"string","maxLength":256,"description":"ATM recurring payment id anchor. Use subscriptionId when available because replacement payment rows change over time."},"returnUrl":{"type":"string","format":"uri","maxLength":1024,"description":"Optional link back into the app shown on the management surface. Must be on the app's registered app URL origin."}}}},"output":{"encoding":"application/json","schema":{"type":"object","required":["url","expiresAt"],"properties":{"url":{"type":"string","format":"uri","description":"Short-lived, single-use management session URL. Open it promptly; it redeems into a short cookie-bound session on ATM's hosted management surface."},"expiresAt":{"type":"string","format":"datetime"}}}},"errors":[{"name":"InvalidRequest","description":"At least one of subscriptionId or paymentId is required."},{"name":"InvalidPayerAssertion","description":"The payer assertion JWT was missing, malformed, or failed verification."},{"name":"PayerDidMismatch","description":"The assertion issuer does not match payerDid."},{"name":"PaymentNotFound","description":"Subscription payment not found for this app and payer."},{"name":"NotASubscription","description":"Payment is not a subscription."},{"name":"InvalidReturnUrl","description":"returnUrl is not on the app's registered app URL origin."}]}}}