Skip to main content

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​

EnvironmentBase URL
Testhttps://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.

Visa Test Cards​

Enrollment Success​

Card NumberVerificationDescription
4242424242424242Auto-approvedEnrollment is automatically approved — no OTP or passkey required.
4000000000000002OTP challengeStandard flow — requires OTP verification and passkey creation.
4000020000000000OTP challengeAlternate card for testing multiple enrollments.
4000056655665556Passkey bypassVerification completes without passkey creation.
4711358892785746OTP challengeStandard flow — requires OTP verification.
Any other Visa PANOTP challengeDefault behavior for unrecognized Visa cards.

Verification Failures​

Card NumberVerificationDescription
4929980395567582Invalid OTPOTP submission always returns an INVALID_OTP error.
4916725297925395Max attempts exceededOTP submission returns a MAX_ATTEMPTS_EXCEEDED error.

Partial Failures (Retryable)​

Card NumberErrorDescription
4000000000003063PROVIDER_ENROLLMENT_FAILED (422)Card registers with the network but fails a subsequent provider step. Returns enrollment with failed status and card display data. Retryable via POST /enrollments/:id/retry.
4000000000003071PROVIDER_ENROLLMENT_FAILED (422)Card fails during token provisioning. Returns enrollment with failed status. Retryable via POST /enrollments/:id/retry.

Enrollment Failures​

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

Mastercard Test Cards​

Enrollment Success​

Card NumberVerificationDescription
5555555555554444Popup challengeStandard flow — requires Mastercard popup authentication.
5200828282828210Auto-approvedEnrollment is automatically approved — no popup required.
2223003122003222Popup challengeMastercard 2-series card — requires popup authentication.
5425233430109903Popup challengeStandard flow — requires Mastercard popup authentication.
Any other Mastercard PANPopup challengeDefault behavior for unrecognized Mastercard cards.

Enrollment Failures​

Card NumberErrorDescription
5105105105105100CARD_REJECTED (422)Card is not eligible for agentic commerce enrollment.

Mock Verification Flows​

In the test environment, verification flows are simplified:

Visa​

  • 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.

Mastercard​

  • Popup challenge — The mock provider simulates the Mastercard popup authentication flow. The popup completes automatically in the test environment.
  • Auto-approved — Verification completes immediately with no consumer interaction.

Mock Credentials​

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

Visa​

  • 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

Mastercard​

  • Virtual card number: 510000100000 + 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.

Last updated on