--- name: bt-agentic description: Build Agentic Payments with payment methods and allowances. license: MIT metadata: tier: standard last_verified: '2026-09-25' --- # Agentic Payments ## Freshness hedge — read this first This skill covers Agentic Payments as verified against public docs on **2026-09-25**. Before implementing anything: 1. Re-fetch the current public docs and prefer them over this skill wherever they differ. 2. Start from the Shared Payment Model pages below, not the deprecated Agents / Enrollments / Instructions pages. 3. Treat rails, providers, credential formats, and source support as resource data. Read the values returned by the API instead of hardcoding vocabulary. ## Current public docs - Product overview: https://developers.basistheory.com/docs/features/agentic - Implementation guide: https://developers.basistheory.com/docs/guides/agentic/implementation - Overview guide: https://developers.basistheory.com/docs/guides/agentic/overview - FAQ (source support, onboarding, allowance changes and deletion): https://developers.basistheory.com/docs/guides/agentic/overview#agentic-payments-faq - Payment methods: https://developers.basistheory.com/docs/api/agentic-commerce/payment-methods - Allowances: https://developers.basistheory.com/docs/api/agentic-commerce/allowances - Verification: https://developers.basistheory.com/docs/api/agentic-commerce/verification - Payment credentials: https://developers.basistheory.com/docs/api/agentic-commerce/payment-credentials - Errors and recovery: https://developers.basistheory.com/docs/api/agentic-commerce/errors-spm - Testing: https://developers.basistheory.com/docs/api/agentic-commerce/testing - Browser verification SDK: https://developers.basistheory.com/docs/sdks/agentic/web-agentic - Webhook events: https://developers.basistheory.com/docs/api/webhooks/eventdata#agentic-payments Deprecated model docs still exist for existing integrations: `/agents`, `/enrollments`, `/instructions`, `/credentials`, `/errors`, and `react-agentic`. Do not use them for new builds unless the user explicitly says they are maintaining a legacy integration. ## Lifecycle Frame every answer around the current Shared Payment Model: 1. Collect or identify a vaulted source. 2. Create a **payment method** from that source; it provisions supported rails and carries no spending authority. 3. Create an **allowance** with the approved amount, customer-facing description, expiration, and optional merchant scope. 4. Verify each allowance rail that requires provider approval. Use `@basis-theory/web-agentic` for browser-driven verification when possible. 5. Mint a **payment credential** from an active allowance rail for a specific amount and format. 6. Submit the credential to the merchant or processor. 7. Track downstream charge, decline, capture, settlement, and refund behavior outside Basis Theory. Key current facts: - Authority sits on the allowance, not an instruction. - Minting a credential permanently draws down allowance spend. There is no void, release, or refund-to-allowance operation. - Verification is rail/provider-specific: Visa and Mastercard ceremonies differ; Stripe SPT has no verification ceremony and can be active from allowance creation. - Credential formats are advertised by allowance rails. Select from the returned `credential_formats`; do not assume every rail can mint every format. - The returned credential value is spendable and returned once. Treat it like live payment data. - The browser SDK ships as an npm package and as a CDN bundle at an immutable versioned path (`https://js.basistheory.com/web-agentic//index.js`, exports on `window.BasisTheoryAgentic`). There is no `latest` alias: pin the version you tested, use the published SRI hash with `crossorigin="anonymous"`, and allow `https://js.basistheory.com` in `script-src` (https://developers.basistheory.com/docs/sdks/agentic/web-agentic#installation). - Lifecycle transitions are also delivered as webhooks: `agentic.payment-method.created` / `.rail.retried` / `.deleted`, `agentic.allowance.created` / `.updated` / `.rail.retried` / `.verification.completed` / `.deleted`, and `agentic.payment-credential.created`. Events carry identifiers under a fixed `payload` key, not full resources or credential values, so receive the event, then fetch the resource. `agentic.allowance.verification.completed` lets the backend learn a rail went `active` without trusting the browser's report; a `pending` payment-method rail only notifies when a retry call runs (https://developers.basistheory.com/docs/api/webhooks/eventdata#agentic-payments). ## Implementation posture - Keep agentic flows beside normal checkout; do not force every payment path through agentic rails. - For UCP integrations, use the current https://developers.basistheory.com/docs/guides/ucp-payments guide; UCP checkout is a merchant protocol, not proof that a minted credential was charged. For browser-driven card entry at a merchant checkout, use `bt-collect` and https://developers.basistheory.com/docs/card-payments/agent-checkout instead of this credential-issuance flow. - Scope allowances to a merchant whenever the merchant is known. Open allowances are supported but weaker because the merchant is chosen later by whoever holds the API key. - Build idempotency around payment method creation, allowance creation, and credential minting. Retrying a mint without idempotency can spend the allowance again. - No flow requires a webhook, but if the backend needs to react to verification or minting, subscribe to the agentic events and reconcile against the API rather than polling the browser. - Where the agentic flow ends in a normal charge, route into `bt-payments` for PSP request shape, proxy transport, 3DS, refunds, and reconciliation. - Label every output as **Documented**, **Assumption**, or **Customer-owned policy**. Spend limits, approval UX, user messaging, merchant selection policy, and agent authorization rules are customer-owned decisions. ## Boundaries - Do not present legacy Agents / Enrollments / Instructions APIs as the default for new builds. - Do not claim a credential was approved, charged, captured, settled, released, voided, or refunded by Basis Theory. Basis Theory issues credentials and does not observe downstream settlement. - Do not invent provider availability, regional availability, rail eligibility, or credential-format support. Read the payment method and allowance rails. - Route business, compliance, provider-access, and production-onboarding questions to Basis Theory: https://basistheory.com/contact ## Basis Theory implementation guidance When the answer needs implementation judgment beyond public docs, load only the relevant slices below from [../\_shared/references/implementation-guidance/README.md](../_shared/references/implementation-guidance/README.md). Treat these as implementation patterns, not canonical product behavior; keep public docs as the source of truth and label the guidance as **Implementation pattern** or **Assumption** unless docs prove it. - `../_shared/references/implementation-guidance/agentic/` ## Working conventions (shared by all Basis Theory skills) - Public Basis Theory docs are the source of truth for product behavior. Link the specific docs page behind any product claim; if a skill and the docs disagree, follow the docs. - Keep customer ownership clear: customers own PSP accounts, credentials, compliance decisions, production rollout, and application code. Skills can guide plans, bounded changes, and examples; they do not certify production readiness. - Never request, echo, store, or commit real credentials. Use placeholders such as `` and prefer sandbox or synthetic data for examples. - If a live-looking credential, live cardholder data, or production secret appears, stop mutation work, tell the user exactly where it appeared, and require rotation/revocation before continuing. - Default to test tenants and PSP sandboxes. Do not run or recommend production charges, refunds, card reveals, credential migrations, or data moves unless the user explicitly asks and the plan names safeguards, rollback, and customer approval. - Treat vague planning, audit, review, and “should we” prompts as read-only unless the user explicitly asks for a bounded implementation change. - Before changing product code, map the existing checkout/data flow, credential-bearing paths, persistence, retries, refunds, webhooks, logs, and rollback expectations. - End with an honest final report: done, assumed, remaining, proof run, unverified live behavior, rollback, and go-live items.