{"lexicon":1,"id":"money.atmosphere.payment.createPledge","defs":{"main":{"type":"procedure","description":"Create a pledge: the payer saves a card for a recipient who has not finished ATM payment setup, and ATM converts it into a real subscription when the recipient becomes payable and has approved this app. Returns the ATM-hosted card-save URL to hand the payer to. No charge and no payment record is created at pledge time. Requires app service-auth; the app must have the pledges + subscriptions modules enabled.","input":{"encoding":"application/json","schema":{"type":"object","required":["recipientDid","amount","interval","environment"],"properties":{"recipientDid":{"type":"string","format":"did","description":"Recipient the payer is pledging to. Does NOT need to be an ATM participant yet."},"amount":{"type":"integer","minimum":50,"maximum":2000000,"description":"Pledged per-cycle amount in integer minor units (same bounds as checkout)."},"currency":{"type":"string","minLength":3,"maxLength":16,"description":"Lowercase 3–16-letter currency identifier. Fiat identifiers use ISO 4217 codes. Defaults to usd. Pledge creation accepts only currencies in ATM's configured checkout processor allowlist; the wider schema range is reserved for future payment rails."},"interval":{"type":"string","knownValues":["month","quarter","year"],"maxLength":16},"environment":{"type":"string","knownValues":["test","live"],"maxLength":16},"payerDid":{"type":"string","format":"did","description":"Optional signed-in payer hint. Guest pledges omit it; the payer's email is collected on the card-save page."},"payerEmailHint":{"type":"string","maxLength":320,"description":"Private prefill hint for the card-save page. Stored privately for pledge notices; never written to public records."},"tierLabel":{"type":"string","maxLength":200},"subscriptionGroupKey":{"type":"string","maxLength":256,"description":"Same offering-scoping contract as subscription checkout: pledges and subscriptions sharing a group key are one offering for duplicate blocking."},"listing":{"type":"ref","ref":"com.atproto.repo.strongRef"},"entitlements":{"type":"array","maxLength":50,"items":{"type":"ref","ref":"com.atproto.repo.strongRef"}},"metadata":{"type":"unknown","description":"Private app metadata carried onto the converted payment. Never published."},"autoConvert":{"type":"boolean","description":"Deprecated compatibility alias. Existing clients may set true for automatic conversion or false for manual conversion. New clients should use requireManualConversion. The two fields are mutually exclusive. If neither is supplied, ATM preserves the historical automatic-conversion behavior."},"requireManualConversion":{"type":"boolean","description":"When true, conversion happens only via convertPledges or the creator dashboard. Omitted or false means ATM automatically converts after the grace window once the recipient is payable and has approved this app."},"expiresAt":{"type":"string","format":"datetime","description":"Optional expiry; the pledge is retired without charge if not converted by then."},"returnUrl":{"type":"string","format":"uri","maxLength":2048},"cancelUrl":{"type":"string","format":"uri","maxLength":2048}}}},"output":{"encoding":"application/json","schema":{"type":"object","required":["pledgeId","token","url","status"],"properties":{"pledgeId":{"type":"string","maxLength":256},"token":{"type":"string","maxLength":256,"description":"Browser bearer for the ATM-hosted card-save/manage page. Long-lived for the pledge's lifetime."},"url":{"type":"string","format":"uri","maxLength":2048},"status":{"type":"string","knownValues":["pending-setup"],"maxLength":32,"description":"Pledge status right after creation (currently always pending-setup: the payer has not saved a card yet). Same vocabulary as listPledges#pledge.status."}}}},"errors":[{"name":"LiveModeNotEnabled"},{"name":"AppEnvironmentNotConfigured"},{"name":"AppModuleDisabled"},{"name":"InvalidRecipient"},{"name":"InvalidPayerDid"},{"name":"SelfPledge"},{"name":"InvalidAmount"},{"name":"UnsupportedCurrency"},{"name":"InvalidInterval"},{"name":"ConflictingConversionMode","description":"autoConvert and requireManualConversion were both supplied; choose only one."},{"name":"InvalidExpiry"},{"name":"InvalidGroupKey"},{"name":"InvalidRedirectUrl"},{"name":"ListingRecipientMismatch"},{"name":"ProductArchived"},{"name":"PriceInactive"},{"name":"PledgeAlreadyActive","description":"This supporter already has a live pledge for this offering; cancel it before creating another."},{"name":"AlreadySubscribed","description":"This supporter already has an active subscription for this offering."},{"name":"InvalidMetadata"}]}}}