Card Verification
Enterprise

Card Verification is an Enterprise feature. Contact support@basistheory.com to request access.

Card Verification confirms that the cardholder details you hold match what the card issuer has on file, without running a payment. Two non-monetary checks are performed against the card networks:

Account Name Inquiry (ANI) compares the name you provide against the name on the issuer's account.
Address Verification Service (AVS) compares the billing address you provide against the address on the issuer's account.

Both checks run through a single request and return a normalized, network-agnostic result alongside the raw network response codes.

Verify Card

POST

https://api.basistheory.com/enrichments/card-verify

Permissions

enrichments:card-verify token:read

enrichments:card-verify is always required. token:read is additionally required when verifying a vaulted card with token_id — requests that pass raw card data need only enrichments:card-verify.

Request

Verifying a card token
curl --location 'https://api.basistheory.com/enrichments/card-verify' \
--header 'BT-API-KEY: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "token_id": "c06d0789-0a5c-4b8b-b5d0-e2f4ca6d3241",
    "owner": {
        "name": {
            "first": "Jane",
            "middle": "Q",
            "last": "Doe"
        },
        "address": {
            "line1": "123 Main St",
            "line2": "Apt 4",
            "city": "San Francisco",
            "state": "CA",
            "postal_code": "94104",
            "country": "US"
        }
    }
}'

Verifying a raw card
curl --location 'https://api.basistheory.com/enrichments/card-verify' \
--header 'BT-API-KEY: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "card": {
        "number": "4242424242424242",
        "expiration_month": 12,
        "expiration_year": 2029
    },
    "owner": {
        "name": {
            "first": "Jane",
            "last": "Doe"
        }
    }
}'

Verifying a card token
await client.enrichments.cardVerify({
  tokenId: "c06d0789-0a5c-4b8b-b5d0-e2f4ca6d3241",
  owner: {
    name: {
      first: "Jane",
      middle: "Q",
      last: "Doe",
    },
    address: {
      line1: "123 Main St",
      line2: "Apt 4",
      city: "San Francisco",
      state: "CA",
      postalCode: "94104",
      country: "US",
    },
  },
});

Verifying a raw card
await client.enrichments.cardVerify({
  card: {
    number: "4242424242424242",
    expirationMonth: 12,
    expirationYear: 2029,
  },
  owner: {
    name: {
      first: "Jane",
      last: "Doe",
    },
  },
});

Verifying a card token
await client.Enrichments.CardVerifyAsync(
    new CardVerificationRequest
    {
        TokenId = "c06d0789-0a5c-4b8b-b5d0-e2f4ca6d3241",
        Owner = new CardVerificationOwner
        {
            Name = new CardVerificationName
            {
                First = "Jane",
                Middle = "Q",
                Last = "Doe"
            },
            Address = new CardVerificationAddress
            {
                Line1 = "123 Main St",
                Line2 = "Apt 4",
                City = "San Francisco",
                State = "CA",
                PostalCode = "94104",
                Country = "US"
            }
        }
    }
);

Verifying a raw card
await client.Enrichments.CardVerifyAsync(
    new CardVerificationRequest
    {
        Card = new CardVerificationCard
        {
            Number = "4242424242424242",
            ExpirationMonth = 12,
            ExpirationYear = 2029
        },
        Owner = new CardVerificationOwner
        {
            Name = new CardVerificationName
            {
                First = "Jane",
                Last = "Doe"
            }
        }
    }
);

Verifying a card token
client.enrichments.card_verify(
    token_id="c06d0789-0a5c-4b8b-b5d0-e2f4ca6d3241",
    owner={
        "name": {
            "first": "Jane",
            "middle": "Q",
            "last": "Doe",
        },
        "address": {
            "line1": "123 Main St",
            "line2": "Apt 4",
            "city": "San Francisco",
            "state": "CA",
            "postal_code": "94104",
            "country": "US",
        },
    },
)

Verifying a raw card
client.enrichments.card_verify(
    card={
        "number": "4242424242424242",
        "expiration_month": 12,
        "expiration_year": 2029,
    },
    owner={
        "name": {
            "first": "Jane",
            "last": "Doe",
        },
    },
)

Verifying a card token
new EnrichmentsClient(ClientOptions.builder().build()).cardVerify(CardVerificationRequest.builder()
    .tokenId("c06d0789-0a5c-4b8b-b5d0-e2f4ca6d3241")
    .owner(CardVerificationOwner.builder()
        .name(CardVerificationName.builder()
            .first("Jane")
            .middle("Q")
            .last("Doe")
            .build())
        .address(CardVerificationAddress.builder()
            .line1("123 Main St")
            .line2("Apt 4")
            .city("San Francisco")
            .state("CA")
            .postalCode("94104")
            .country("US")
            .build())
        .build())
    .build());

Verifying a raw card
new EnrichmentsClient(ClientOptions.builder().build()).cardVerify(CardVerificationRequest.builder()
    .card(CardVerificationCard.builder()
        .number("4242424242424242")
        .expirationMonth(12)
        .expirationYear(2029)
        .build())
    .owner(CardVerificationOwner.builder()
        .name(CardVerificationName.builder()
            .first("Jane")
            .last("Doe")
            .build())
        .build())
    .build());

Verifying a card token
verification, err := client.Enrichments.CardVerify(ctx, &basistheory.CardVerificationRequest{
	TokenID: "c06d0789-0a5c-4b8b-b5d0-e2f4ca6d3241",
	Owner: &basistheory.CardVerificationOwner{
		Name: &basistheory.CardVerificationName{
			First:  basistheory.String("Jane"),
			Middle: basistheory.String("Q"),
			Last:   basistheory.String("Doe"),
		},
		Address: &basistheory.CardVerificationAddress{
			Line1:      basistheory.String("123 Main St"),
			Line2:      basistheory.String("Apt 4"),
			City:       basistheory.String("San Francisco"),
			State:      basistheory.String("CA"),
			PostalCode: basistheory.String("94104"),
			Country:    basistheory.String("US"),
		},
	},
})
if err != nil {
	log.Fatal(err)
}

fmt.Println(verification.Ani.Result, verification.Avs.Result)

Verifying a raw card
verification, err := client.Enrichments.CardVerify(ctx, &basistheory.CardVerificationRequest{
	Card: &basistheory.CardVerificationCard{
		Number:          "4242424242424242",
		ExpirationMonth: 12,
		ExpirationYear:  2029,
	},
	Owner: &basistheory.CardVerificationOwner{
		Name: &basistheory.CardVerificationName{
			First: basistheory.String("Jane"),
			Last:  basistheory.String("Doe"),
		},
	},
})
if err != nil {
	log.Fatal(err)
}

fmt.Println(verification.Ani.Result)

Request Parameters

Name	Type	Description
`token_id`	string (Optional)	The ID of the token containing the card to verify. Token type must be `card`. Mutually exclusive with `card`.
`card`	object (Optional)	The raw card to verify, in case it is not vaulted. Mutually exclusive with `token_id`.
`owner`	object	The cardholder details to verify against the issuer. At least one of `owner.name` or `owner.address` is required.

Exactly one of token_id or card must be provided. When token_id is used, the card number and expiration date are decrypted server-side and never leave the Basis Theory vault in your request or response.

Only card tokens can be verified by reference. The card networks require an expiration date for every inquiry, and a card_number token stores only the card number. To verify a card held as a card_number token, send the card number and its expiration date in the card object instead.

Card Object

Required when verifying a card that is not referenced by a card token.

Name	Type	Description
`number`	string	The card number.
`expiration_month`	integer	The card's expiration month.
`expiration_year`	integer	The card's four-digit expiration year.

Owner Object

Name	Type	Description
`name`	object (Optional)	The cardholder name to verify. Providing this object runs the ANI check.
`address`	object (Optional)	The billing address to verify. Providing this object runs the AVS check.

The checks that run are implied by the data you send. Include owner.name to run ANI, include owner.address to run AVS, and include both to run both. There is no separate parameter to select checks, and a check cannot run without the data it compares against.

Name Object

Name	Type	Description
`first`	string (Optional)	The cardholder's first name.
`middle`	string (Optional)	The cardholder's middle name or initial.
`last`	string (Optional)	The cardholder's last name.
`suffix`	string (Optional)	The cardholder's name suffix (e.g. `Jr`).
`company`	string (Optional)	The company name, for business cards. Mutually exclusive with `first`, `middle`, `last` and `suffix`.

At minimum, first and last (or company for a business card) should be provided. Requests with less name detail return a less conclusive ANI result.

Address Object

Name	Type	Description
`line1`	string (Optional)	The first line of the billing street address.
`line2`	string (Optional)	The second line of the billing street address.
`city`	string (Optional)	The billing address city.
`state`	string (Optional)	The billing address state, province or region.
`postal_code`	string (Optional)	The billing address postal code.
`country`	string (Optional)	The two character ISO 3166-1 alpha-2 country code (e.g. `US`).

All address fields are individually optional, but AVS only produces a meaningful result when at least line1 or postal_code is provided.

Response

Returns the normalized result of each check that was run.

{
  "ani": {
    "result": "match",
    "name": {
      "full": "match",
      "first": "match",
      "middle": "partial_match",
      "last": "match"
    }
  },
  "avs": {
    "result": "partial_match",
    "address_line": "no_match",
    "postal_code": "match",
    "network_code": "Z"
  },
  "network": "visa",
  "par": "V0010013816180398433121885963",
  "created_at": "2026-08-09T17:00:00.000Z"
}

Name	Type	Description
`ani`	object	The Account Name Inquiry result. Omitted when `owner.name` was not provided.
`avs`	object	The Address Verification result. Omitted when `owner.address` was not provided.
`network`	string	The card network that answered the inquiry (e.g. `visa`, `mastercard`, `discover`).
`par`	string	The Payment Account Reference (PAR) returned by the network, a network-issued identifier that stays stable across all tokens and cards issued for the same underlying account.
`created_at`	string	The UTC timestamp when the verification was performed, in ISO 8601 format.

Results are not persisted by Basis Theory. Each response reflects the issuer's answer at the moment of the call and is not retrievable later — store any result you need to act on or audit.

ANI Object

Name	Type	Description
`result`	string	The overall name match result.
`name.full`	string	Match result for the full name.
`name.first`	string	Match result for the first name.
`name.middle`	string	Match result for the middle name.
`name.last`	string	Match result for the last name.

Per-name-part results are only returned by networks that support them. Visa and Discover return first, middle and last; Mastercard returns full only. Fields the network did not return are omitted from the response — an absent field is not a failed match. Discover ANI coverage is limited, as there is no issuer mandate.

AVS Object

Name	Type	Description
`result`	string	The overall address match result.
`address_line`	string	Match result for the street address. Omitted when the network did not evaluate the address.
`postal_code`	string	Match result for the postal code. Omitted when the network did not evaluate the postal code.
`network_code`	string	The raw single-character AVS response code returned by the network. See AVS network codes.

ANI Results

Value	Description
`match`	The name provided matches the name on the issuer's account.
`partial_match`	Some parts, but not all, of the name provided matches the name on the issuer's account.
`no_match`	The name provided does not match the name on the issuer's account.
`not_performed`	The issuer did not perform the name check.
`not_supported`	The issuer does not support Account Name Inquiry.

name.full, name.first, name.middle and name.last each return match, partial_match or no_match.

AVS Results

Value	Description
`match`	Both the street address and the postal code match the issuer's records.
`partial_match`	Either the street address or the postal code matches, but not both.
`no_match`	Neither the street address nor the postal code matches.
`unavailable`	The issuer's AVS system was unavailable or did not return a result. Retry later.
`not_supported`	The issuer or card type does not support AVS.
`error`	The address data submitted could not be processed. Re-examine the address you provided.

AVS Network Codes

avs.network_code is the raw code returned by the network, preserved so you can apply rules you may already run against AVS codes elsewhere. The table below shows how each code is normalized.

`network_code`	`result`	`address_line`	`postal_code`
`Y`	`match`	`match`	`match`
`A`	`partial_match`	`match`	`no_match`
`Z`	`partial_match`	`no_match`	`match`
`W`	`partial_match`	`no_match`	`match`
`N`	`no_match`	`no_match`	`no_match`
`U`	`unavailable`	—	—
`R`	`unavailable`	—	—
`M`	`unavailable`	—	—
`S`	`not_supported`	—	—
`G`	`not_supported`	—	—
`I`	`not_supported`	—	—
`E`	`error`	—	—

Error Handling

Errors generated by the Basis Theory API follow the standard API Error formatting.

Status	Description
`400`	The request is invalid — neither `token_id` nor `card` was provided, both were provided, neither `owner.name` nor `owner.address` was provided, or a field is malformed.
`401`	The request is missing valid authentication credentials.
`403`	The Application lacks the `enrichments:card-verify` permission, lacks `token:read` for a `token_id` request, or Card Verification is not enabled for your tenant.
`404`	The token referenced by `token_id` does not exist or is not accessible under the Application's access controls.
`422`	The token referenced by `token_id` is not a `card` token, or its card data is incomplete (for example, a missing expiration date).
`424`	The verification could not be completed because the upstream verification service returned an error or was unreachable. No check result is returned — retry the request.

Verification is all-or-nothing. If either requested check fails upstream, the request fails with a 424 rather than returning a partial result.

Verify Card​

Permissions​

Request​

Request Parameters​

Card Object​

Owner Object​

Name Object​

Address Object​

Response​

ANI Object​

AVS Object​

ANI Results​

AVS Results​

AVS Network Codes​

Error Handling​