{"lexicon":1,"id":"money.atmosphere.app.requestRecipientApproval","defs":{"publicRecordPaymentPolicy":{"type":"object","properties":{"appRecord":{"type":"string","knownValues":["public","private"],"maxLength":16},"attestation":{"type":"string","knownValues":["public","private"],"maxLength":16}}},"publicRecordsPolicy":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether this app may send explicit payer-facing public payment record choices for this recipient scope. When false, ATM treats matching app-originated payments as private for public payment-record purposes."},"defaults":{"type":"ref","ref":"#publicRecordPaymentPolicy"},"byPaymentType":{"type":"object","properties":{"tip":{"type":"ref","ref":"#publicRecordPaymentPolicy"},"subscribe":{"type":"ref","ref":"#publicRecordPaymentPolicy"},"shop":{"type":"ref","ref":"#publicRecordPaymentPolicy"},"commission":{"type":"ref","ref":"#publicRecordPaymentPolicy"},"ticket":{"type":"ref","ref":"#publicRecordPaymentPolicy"}}}}},"ticketFee":{"type":"object","required":["bps","flatAmount","passToBuyer"],"properties":{"bps":{"type":"integer","minimum":0,"maximum":1000},"flatAmount":{"type":"integer","minimum":0,"maximum":1000},"passToBuyer":{"type":"boolean"}},"description":"Server-resolved ATM ticket fee terms snapshotted into the recipient approval when ticket payments are requested."},"main":{"type":"procedure","description":"Request creator approval for an app to accept ATM payments for that recipient. Requires a service-auth JWT signed by the app DID.","input":{"encoding":"application/json","schema":{"type":"object","required":["recipientDid","environment","paymentTypes"],"properties":{"recipientDid":{"type":"string","format":"did"},"environment":{"type":"string","knownValues":["test","live"],"maxLength":8},"paymentTypes":{"type":"array","minLength":1,"maxLength":32,"items":{"type":"string","knownValues":["tip","subscribe","shop","commission","ticket"],"maxLength":32}},"feeShareBps":{"type":"integer","minimum":0,"maximum":10000,"description":"App fee cap requested for this recipient, in basis points of the gross payment."},"publicRecords":{"type":"ref","ref":"#publicRecordsPolicy"},"requestReason":{"type":"string","maxGraphemes":300,"maxLength":3000},"setupReturnUrl":{"type":"string","format":"uri"},"recipientAssertionJwt":{"type":"string","maxLength":4096,"description":"Optional short-lived recipient (creator) presence token: a com.atproto.server.getServiceAuth JWT with iss = recipientDid, aud = ATM broker, lxm = money.atmosphere.app.assertRecipient. A verified token may register the creator role without a separate ATM sign-in, but the app approval remains pending because the token is not bound to the requested app, environment, fee, payment types, or public-record policy. An invalid token is rejected (400)."}}}},"output":{"encoding":"application/json","schema":{"type":"object","required":["id","status","dashboardUrl","paymentTypes","feeShareBps"],"properties":{"id":{"type":"string","maxLength":128},"status":{"type":"string","knownValues":["pending","approved","blocked","revoked","needs-review"],"maxLength":32},"dashboardUrl":{"type":"string","format":"uri"},"onboardingUrl":{"type":"string","format":"uri","description":"ATM-hosted URL where the creator can finish payment setup. Currently always returned; optional so future statuses can omit it."},"paymentTypes":{"type":"array","maxLength":32,"items":{"type":"string","knownValues":["tip","subscribe","shop","commission","ticket"],"maxLength":32}},"feeShareBps":{"type":"integer","minimum":0,"maximum":10000},"ticketFee":{"type":"ref","ref":"#ticketFee","description":"Exact ATM ticket fee terms included in the pending approval when paymentTypes contains ticket."},"materialChangeReasons":{"type":"array","maxLength":32,"items":{"type":"string","maxLength":64},"description":"Which requested terms materially changed versus the existing approval (empty when none). Currently always returned; optional so it can be omitted when not applicable."},"autoApproved":{"type":"boolean","description":"Deprecated compatibility field. Always false: recipient presence can register the creator role but cannot approve an app or its requested terms."},"needsPaymentSetup":{"type":"boolean","description":"True when the app should route the creator through ATM to finish setup. Only reflects real payout readiness once status is 'approved': False then means the recipient's environment-scoped connected account has charges and payouts enabled (existing-ATM-creator streamline — the approval alone is enough), while merely having started setup (an account id exists but Stripe requirements are unmet) still returns True. For any not-yet-approved status (pending/needs-review/blocked/revoked) it is a conservative True with no Stripe probe, since the app is not yet authorized to learn a creator's private payout-readiness state."}}}},"errors":[{"name":"AppEnvironmentNotConfigured","description":"This app environment is not configured in ATM."},{"name":"ApprovalRequestFailed","description":"The approval request could not be created."}]}}}