Agentic Payments Overview

Authorize an AI agent with a spend allowance, without exposing raw credentials.

An agent shopping on a customer’s behalf eventually needs to pay. Giving it direct access to the customer's raw credential creates unnecessary risk: that credential may work across merchants and amounts, and revoking it may require replacing or reauthorizing the underlying payment method.

Agentic Payments separates payment authority into three resources. A payment method references an existing source. An allowance defines the customer-approved constraints: merchant, amount, and expiration. A credential is minted from the allowance for a single purchase and is the only resource exposed to the agent, who has no access to the underlying payment method.

Updating an Existing Integration

Agentic Payments does not convert existing Agents, Enrollments, or Instructions. Every Payment Method, Allowance, and Payment Credential is created through the new API. See Migrating to Agentic Payments for the concept mapping and cutover guidance.

Start with a Guide

This page introduces the model and the terminology. For hands-on implementation, refer to the guides below:

Agentic Payments Setup

Learn how to request access, configure your tenants, and prepare your application for verification.

Implementation

Learn how to go from a source to a minted credential, including verification and failure recovery.

Testing Reference

Reference material for test sources, mock provider ceremonies, and failure scenarios.

Own Browser Verification

Implement the verification API state machine and browser protocols without using the Web Agentic SDK.

How Agentic Payments Works

The model is called the Shared Payment Model, or SPM. A source is registered once as a reusable payment method, the customer grants a bounded mandate against it, and a credential for one purchase is issued only when the agent is ready to pay. Each step is a separate resource with its own lifecycle, so the authority the customer granted and the credential the agent presents are never the same object.

Concept	Question it Answers	Lifetime
Source	Where is the money coming from?	Input to the model, managed outside Agentic Payments
Payment Method	Is that source set up for agentic purchases?	Reusable across many Allowances
Allowance	How much may be spent, where, and until when?	Decided by the Customer
Credential	What does the agent present at checkout?	One Purchase

The last three rows are the resources Agentic Payments creates and manages. A source is the object they are built on, and it exists whether or not you use Agentic Payments at all.

The separation is the point: authority lives only in the allowance, so payment methods stay reusable and credentials stay disposable.

Sources

A source is where the money comes from. It is the one entry in the model that Agentic Payments does not create or manage: a source exists on its own, and a payment method references it. The source object on the payment method names it by type; the supported source type is a vaulted card (basis_theory_card_token), referencing a card token in your tenant.

Everything downstream follows from the source. The rails a payment method is registered with, the ceremonies a customer completes, and the formats a credential can take are all consequences of what backs the payment method.

Payment Methods

A payment method registers a source for agentic use. Creating one is not a bookkeeping step. Basis Theory registers the source with each supported provider in the same call, which is what makes it spendable later.

Those registrations happen at third parties, so they succeed and fail independently. A payment method reports the outcome of each one separately and can exist with one working registration and one failed one, which is why you read its rails array rather than just trusting the 201 status.

Rails and Providers

A rail is a way that a source can produce a spendable credential, and a provider is who operates it. The rail and provider values together identify one rail on a resource, and requests that select one echo both values back.

Which rails a payment method gets is decided by its source: for example a card is registered with its own card network's agentic program, and with any processor rails that accept it. You never pick a provider; it follows from the source. The API reference lists every current supported combination and the credential formats each one produces.

Allowances

An allowance is a spending mandate: an amount, a merchant, a customer-facing description of what the spending is for, and a time it expires. It is deliberately free of anything provider-specific, which is what makes it the resource you show a customer for approval.

An allowance also tracks its own balance. As credentials are minted, the amount spent rises and the amount available falls, and Basis Theory refuses to mint a credential that would take the allowance past its total. Two agents minting at the same instant cannot overspend one allowance. These totals account for credential issuance, not merchant transactions: amount_spent means allowance capacity was consumed, not that money settled.

Because rails are provisioned per allowance, an allowance has rails of its own, each with its own status: the allowance status describes the mandate, and is active until the allowance is cancelled or expires, while a rail status describes one way of spending it. An active allowance is not the same as a usable one. Read the rail you intend to mint from.

Credentials

A credential is what the agent presents at checkout. It is minted from an allowance for a specific amount, and the spendable value is returned exactly once, in the response to the request that created it. Basis Theory never stores it and no later read returns it.

A credential's format is its representation. Each allowance rail advertises the formats it can produce in credential_formats, so an agent picks a representation at mint time without knowing anything about the source underneath.

The API reference documents every format, when to use it, and its request and response. The implementation guide walks through minting each one.

Verification

Whether a customer has to prove presence before a credential can be issued is a property of the rail rather than of the model. Verification is scoped to a single rail on a single allowance, so approving one allowance does not grant open-ended agentic access to the source.

A rail that requires verification will not release a credential just because your application asked for one: the customer approves the mandate through a ceremony the provider itself owns. For example, on card network rails, that ceremony uses a passkey or a one-time code; processor rails such as Stripe Shared Payment Tokens may require none. Read each rail's status rather than assuming: a rail that requires verification is created in pending_verification, and one that does not is active immediately.

Verification is self-served. The ceremony runs in your own pages, in your own popups and iframes. There is no Basis Theory-hosted checkout to redirect to and no Basis Theory branding in front of your customer.

Verification is never self-asserted. Your frontend reports what happened in the browser, but only Basis Theory advances the state machine, and it confirms every transition with the provider server to server. Nothing your client sends can activate a rail on its own. A browser message saying the ceremony finished is a cue to make the next API call, not a result.

The Web Agentic SDK runs these ceremonies while preserving each provider's security boundaries. If your application needs to drive the state machine and browser protocols directly, see Own the Browser Verification Flow.

Spend, and What Basis Theory Can See

Minting a credential spends the allowance. The amount comes out when Basis Theory issues the credential, not when the merchant charges it, and it holds even when the purchase never happens: if the agent never presents the credential, if the merchant rejects it, or if authorization declines, the allowance has still been drawn down. There is no void, release, or refund-to-allowance operation.

The reason is honesty about what Basis Theory can observe. Minting is the last event it sees. Merchant authorization, capture, clearing, settlement, refunds, and disputes all happen afterwards on rails Basis Theory is not part of, which is why a credential's status stays created and never becomes approved, declined, or settled. A release endpoint would have to trust a client claiming a credential went unused, and that claim is unverifiable.

The practical consequence is how you size allowances. The safest way is to mint for the amount of the checkout in front of you rather than pre-minting against a ceiling.

An allowance is not a hold on funds and does not reserve money with the issuer.
It is authority to spend, and minting consumes that authority whether or not a payment follows.

Who This Is For

• Agent and assistant builders who need their agent to complete a real checkout, and need the customer to stay in control of what it can spend.

• Platforms and marketplaces that already hold cards on file and want to expose agentic spending to their own customers without becoming the party that hands out real credentials.

• Wallets and neobanks that want to offer agentic spending on cards they already have, using the card networks' own agentic programs rather than issuing new virtual cards.

Keep the Integration Rail-Agnostic

Rails, providers, formats, and source types are data on the resources rather than fixed vocabulary. Three habits keep an integration aligned with that:

1. Treat rail and provider as an opaque pair. Read them off the resource and echo them back.
   An integration that branches on provider === "vic" breaks the moment a rail carries a provider it has not seen; one that iterates the rails array does not.

2. Read credential_formats from the rail rather than inferring it. Each allowance rail publishes the formats it can produce.
   Pick from that list at request time instead of hard-coding which rail produces which format.

3. Switch on source.type rather than assuming a card. The source object names what backs the payment method.
   Read its type instead of assuming the shape of what is behind it.

Learn More

• Agentic Payments API documents every field, value, status, and error.
• Errors and Recovery covers what is safe to retry and which unknown outcomes are terminal.
• Agentic Payments covers the platform capability, how it compares to card issuing, and frequently asked questions.
• Deprecated Integration documents the earlier Agents, Enrollments, and Instructions model, which remains available for existing integrations.