Agentic Commerce Testing

Basis Theory provides a sandbox environment for testing the Agentic Commerce API. Test tenants use mock providers that simulate the full enrollment, verification, and credential retrieval flows without making real calls to card networks.

Test Environment

Environment	Base URL
Test	`https://api.test.basistheory.com/agentic`

Use a test tenant API key to interact with the sandbox. All enrollment and verification flows are handled by mock providers that return deterministic responses based on the card number used. See the error codes reference for all possible error responses.

Test Cards

Each test card triggers a specific scenario during enrollment and verification. Use these cards when creating Basis Theory tokens for enrollment testing.

Enrollment Success

Card Number	Verification	Description
`4242424242424242`	Auto-approved	Enrollment is automatically approved — no OTP or passkey required.
`4000000000000002`	OTP challenge	Standard flow — requires OTP verification and passkey creation.
`4000020000000000`	OTP challenge	Alternate card for testing multiple enrollments.
`4000056655665556`	Passkey bypass	Verification completes without passkey creation.
`4711358892785746`	OTP challenge	Standard flow — requires OTP verification.
Any other Visa PAN	OTP challenge	Default behavior for unrecognized Visa cards.

Verification Failures

Card Number	Verification	Description
`4929980395567582`	Invalid OTP	OTP submission always returns an `INVALID_OTP` error.
`4916725297925395`	Max attempts exceeded	OTP submission returns a `MAX_ATTEMPTS_EXCEEDED` error.

Enrollment Failures

Card Number	Error	Description
`4330251207506660`	`CARD_REJECTED` (422)	Card fails network verification during enrollment.
`4539097887163333`	`CARD_REJECTED` (422)	Card is not eligible for agentic commerce enrollment.
`4929544240318920`	`CARD_REJECTED` (422)	Card is declined by the issuer during enrollment.

Mock Verification Flows

In the test environment, verification flows are simplified:

OTP challenge — The mock provider accepts any OTP code (e.g., 123456) unless the card is configured to return an OTP error.
Auto-approved — Verification completes immediately with no consumer interaction.
Passkey bypass — Verification completes without requiring passkey creation or authentication.

WebAuthn passkeys cannot be tested against mock endpoints. In the test environment, passkey steps are automatically bypassed after OTP verification succeeds.

Mock Credentials

When retrieving credentials for an approved instruction in the test environment, the mock provider returns deterministic virtual card data:

Virtual card number: 400000100000 + the original card's last 4 digits
Expiration: Matches the original card's expiration date
CVC: A deterministic 3-digit code derived from the instruction ID

Generating Test Tokens

Since the Agentic Commerce API accepts a token_id when creating enrollments, you first need to tokenize a test card in your test tenant.

#!/bin/bash

BT_API_KEY="<YOUR_TEST_PRIVATE_API_KEY>"

# Tokenize a test card (auto-approved scenario)
curl -X POST https://api.test.basistheory.com/tokens \
  -H "BT-API-KEY: $BT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "card",
    "data": {
      "number": "4242424242424242",
      "expiration_month": 12,
      "expiration_year": 2030,
      "cvc": "123"
    }
  }'

Use the returned token id as the token_id when creating an enrollment.

Test Environment​

Test Cards​

Enrollment Success​

Verification Failures​

Enrollment Failures​

Mock Verification Flows​

Mock Credentials​

Generating Test Tokens​