Skip to main content

Agentic Payments Setup

Agentic Payments is an Enterprise feature that depends on Basis Theory's relationships with the rail providers, so production access requires onboarding. Test access does not. Everything on this page other than the production section can be completed before onboarding, and the entire flow, including the verification ceremonies, can be rehearsed in a test tenant against deterministic mocks. Do this once per tenant. When you are finished, move on to the implementation guide.

Test Tenant Setup​

Nothing further is required. Send test-tenant traffic to https://api.test.basistheory.com, where every rail routes to a deterministic mock provider: no request reaches a provider, the browser ceremonies are Basis Theory-hosted mock pages speaking the live protocols, and allowance accounting behaves exactly as it does in production.

Use the testing reference for the test cards and the scenario each one exercises.

Production Tenant Setup​

Basis Theory configures your production tenant with the provider credentials that back each rail. This is done during onboarding and is not a self-service.

If a rail on a real payment method returns UNSUPPORTED_PROVIDER or PROVIDER_NOT_CONFIGURED, onboarding for that rail is incomplete. Contact us rather than retrying, since no retry will succeed until the configuration exists.

Use a Secure Top-Level Origin​

Most of the allowance verification ceremonies require a secure top-level browser context. Serve production and staging pages over HTTPS. Browsers commonly treat localhost as secure during development, but an HTTPS tunnel more closely exercises the iframe, popup, and origin behavior of your deployed site.

Prepare Your Frontend for the Verification Ceremonies​

Each ceremony runs in a customer-facing surface, an embedded iframe or a popup. Your application needs to account for that:

  • Tell customers to allow popups for your domain, and handle the blocked case with a retry affordance rather than a silent failure.
  • Ad/content blockers, privacy tools, browser security settings, and network filters can prevent hosted iframes from loading. Test with blockers disabled and make sure the returned iframe URL is reachable.
  • If your Content Security Policy restricts connect-src, allow the Agentic Payments API origin your frontend uses: https://api.test.basistheory.com for test tenants and https://api.basistheory.com for production.

Access Controls​

Refer to the implementation guide to create the applications your integration needs: a public application your frontend uses to create payment methods and drive allowance verification, and a private application your backend uses for everything else.

Confirm the Setup Works​

Create a payment method from a tokenized test card and read its rails array. Each rail that comes back enabled is configured correctly. A rail that comes back error carries a stable error.code you can look up in Errors and Recovery, and its full history is available at GET /agentic/payment-methods/{payment_method_id}/errors.

Next Steps​

Last updated on