{"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"}}}}},"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 proves the creator took the payment-setup action inside the app and authorizes ATM to auto-register the recipient and auto-approve this app (no separate ATM sign-in). Absent → the request stays pending and the recipient must already be registered. 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},"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":"True when a verified recipient presence token caused this approval to be granted immediately, with no separate creator approval handshake."},"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."}]}}}