# Docs-only overlay: merged into grouped OpenAPI at sync time (see scripts/sync-openapi.mjs). # Keys must match OpenAPI tag `name` exactly. Values replace upstream tag descriptions in grouped YAML only. tags: - name: AccessKeys description: | Programmatic credentials for the Pay API. Create, list, and rotate keys used with **`X-Api-Key`**. Treat keys like passwords: prefer sandbox keys in development, rotate on compromise, and never expose them in client-side code or public repos. - name: Accounts description: | Top-level accounts your integration operates on. Scope is inferred from **`X-Api-Key`** — do not send `X-Account-Id`. Use accounts to inspect merchants, payouts, and reporting when building platforms or multi-entity products. - name: Charges description: | Records of captured payment transactions. Use charges to reconcile what was collected, inspect status, and support customer support workflows. Prefer **`PaymentIntents`** for new checkout flows; charges often reflect completed intent flows or legacy paths. - name: Customers description: | People or businesses you collect payments from. Attach **`PaymentMethod`** and **`PaymentIntent`** resources to customers for returning payer experiences. Create or update customers early so reporting and support share a stable identifier across payments. - name: ExternalAccounts description: | Bank or payout destinations linked for settlements. Used when moving funds out to merchants or connected accounts. Verification and capability rules apply; align creation with your onboarding and payout policies. - name: FileUploads description: | Secure uploads for KYC documents, agreements, or compliance artifacts. Typically a multi-step flow: create upload → transfer bytes → complete. Poll or webhook on related applications rather than blocking on upload alone. - name: FraudRules description: | Controls that influence risk decisions on transactions. Configure rules to match your tolerance and monitoring strategy. Coordinate changes with risk operations—rule updates can affect authorization behavior. - name: LegalEntities description: | Legal entities underlying merchant accounts. Retrieve entity details during onboarding or compliance reviews. Often paired with **`LegalEntityApplications`** and document uploads. - name: LegalEntityApplicationDocuments description: | Documents attached to a legal entity application (formation, identity, banking proof). Upload via **`FileUploads`** where applicable, then associate with the application lifecycle. - name: LegalEntityApplicationPrincipals description: | Individuals with ownership or control on an application (beneficial owners, signers). Required fields depend on program rules; collect before submission to avoid rework. - name: LegalEntityApplications description: | Applications to onboard or update a legal entity. Track state from draft through approval. Submit only when required principals and documents are attached. - name: LegalEntityPrincipals description: | Principals associated with an onboarded legal entity after approval. Use for ongoing KYB updates and ownership changes. - name: Merchants description: | Merchant profiles available under your platform account. List and retrieve merchants you manage or provision. Merchant lifecycle often ties to **`MerchantApplications`** and payout configuration. - name: MerchantApplications description: | Applications to create or onboard merchants. Follow submission and approval states from your dashboard or API responses. Pair with legal entity and external account resources for complete underwriting data. - name: Organizations description: | The current organization (`GET` / `PATCH /organization`). Branding, contact, and org-scoped configuration. Update when business details change to keep receipts and communications accurate. - name: DunningConfigurations description: | Organization dunning settings for unpaid recurring charges (`/dunning_configuration`). Coordinate with **`Subscriptions`** and webhook handlers before changing exhausted-action behavior. - name: Origins description: | Allowed browser origins for embedded flows (checkout, hosted components). Define origins explicitly—wildcard-style assumptions are unsafe. Required for **`PaymentIntents`** and iframe/SDK integrations; misconfiguration usually surfaces as client-side errors. - name: PaymentIntents description: | The primary object for accepting a payment: created server-side, confirmed client-side or server-side depending on your integration. Tracks amount, currency, customer, and status through **`requires_payment_method`** → **`processing`** → **`succeeded`** (or terminal failure). Use with **`PaymentMethods`** and embedded checkout. - name: PaymentLinks description: | Shareable URLs that start a hosted payment experience without building a full checkout page. Ideal for invoices, campaigns, or lightweight flows; amounts and line items are fixed when you create the link. - name: PaymentMethods description: | Stored instruments (card, bank, wallets where supported) attached to a **`Customer`** or used with a **`PaymentIntent`**. Collect sensitive data only through Amos-hosted or SDK-supported surfaces—never raw PANs on your servers. - name: PaymentSnapshots description: | Point-in-time snapshots of payment-related state for auditing, disputes, or reconciliation exports. Use when you need an immutable view tied to reporting or back-office tools. - name: Payouts description: | Transfers to **`ExternalAccounts`**. Monitor **`pending`**, **`succeeded`**, and **`failed`** states for treasury operations. Build idempotent creation and webhook-driven status updates for reliable money movement. - name: ProcessorTransactions description: | Raw processor-level transactions underlying authorizations and captures. Useful for deep reconciliation against processor statements and debugging mismatches. - name: Processors description: | Processor connections and configuration available to your account. Consult before enabling new payment methods or currencies tied to a specific processor. - name: Products description: | Sellable items or SKUs used with subscriptions and invoicing-style flows. Define products before **`SubscriptionPlans`** so pricing tiers reference stable catalog entries. - name: Reconciliations description: | Batch or ledger reconciliation records aligning Amos money movement with your books. Export or query for finance close processes alongside **`Payouts`** and **`ProcessorTransactions`**. - name: Refunds description: | Return funds to the payer against an existing charge or intent outcome. Prefer idempotent refund requests and webhook confirmation before updating order state in your system. - name: RenderTemplates description: | Embed render templates: allowed origins, payment methods, billing geography, and amount range. Issue a **render token** from a template to mount checkout iframes. Bank templates can disable ACH verification (`options.verification: false`) for virtual terminal-style flows. - name: SetupIntents description: | Collect and validate a **`PaymentMethod`** for future off-session charges (subscriptions, saved wallets). Flow resembles **`PaymentIntents`** but optimizes for vaulting rather than immediate capture. - name: SubscriptionPlans description: | Pricing plans (interval, trial, currency) built on **`Products`**. Attach plans to **`Subscriptions`** when customers enroll in recurring billing. - name: Subscriptions description: | Active recurring billing agreements. Track renewal dates, trial end, and cancellation behavior. Combine with webhooks for invoice-like events and dunning if offered for your program. - name: Voids description: | Cancel an authorization before capture when your processor and payment path support voids. Distinct from **`Refunds`** (post-capture). Use the operation appropriate to transaction state. - name: WebhookAttempts description: | Individual delivery tries for an event payload—including retries and failure reasons. Inspect attempts when an endpoint shows intermittent failures or signature mismatches. - name: WebhookEndpoints description: | HTTPS URLs where Amos delivers signed event notifications. Register one endpoint per environment (sandbox vs live). Rotate secrets safely and verify signatures before mutating production state. - name: WebhookRequests description: | Logical webhook deliveries grouping related **`WebhookAttempts`**. Correlate with your idempotent handlers using event IDs and request headers documented for verification.