Credentials

The credentials endpoint returns virtual card credentials for an approved instruction. The response includes a virtual card number, expiry, and CVC that the agent uses to complete a purchase at a merchant. These are not actual PANs — they are network-generated virtual credentials.

This endpoint returns virtual card credentials that look like a card number and CVC but are not actual PCI cardholder data. These credentials should still be treated securely and requests should only be made from your backend.

Authentication

All requests require a BT-API-KEY header with your Basis Theory API key.

All errors follow the standard error response format.

Get Credentials

Retrieves virtual card credentials for an approved instruction.

POST

https://api.basistheory.com/agentic/agents/{agent_id}/instructions/{instruction_id}/credentials

Permissions

agent:instruction:credentials

Credentials can only be retrieved for instructions with approved status. Attempting to retrieve credentials for a pending, pending_verification, expired, cancelled, or failed instruction will return a 400 error.

Request

curl -X POST https://api.basistheory.com/agentic/agents/agt_fukICjsY2xzRCECiTCbKM/instructions/ins_luPDv2xm3Yb8RjFJz9oTC/credentials \
  -H 'BT-API-KEY: <BT_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "merchant": {
      "name": "Amazon",
      "url": "https://www.amazon.com",
      "country_code": "US"
    },
    "products": [
      {
        "name": "Widget",
        "price": 99.99,
        "quantity": 2
      }
    ],
    "shipping_address": {
      "line1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country_code": "US"
    }
  }'

Request Parameters

Attribute	Required	Type	Description
agent_id	Yes	string	The ID of the agent
instruction_id	Yes	string	The ID of the approved instruction
merchant	No	object	The merchant object. Falls back to the merchant stored on the instruction (if provided during instruction creation). A 400 error is returned if no merchant is available from either source.
products	No	array	Array of product objects being purchased
amount	No	object	Override amount for this credential request. See amount object
delivery_method	No	string	How the purchase will be delivered. One of: no-delivery, address-billing, address-on-file, address-other, pickup, electronic
shipping_address	No	object	The shipping address object

Merchant Object

Attribute	Required	Type	Description
name	Yes	string	The merchant name (displayed to the cardholder during passkey verification)
url	Yes	string	The merchant website URL
country_code	Yes	string	ISO 3166-1 alpha-2 country code of the merchant
category_code	No	string	4-digit merchant category code (MCC)

Product Object

Attribute	Required	Type	Description
name	Yes	string	The product name
price	Yes	number	The product price
quantity	Yes	integer	The quantity being purchased

Shipping Address Object

Attribute	Required	Type	Description
line1	Yes	string	The first line of the street address
city	Yes	string	The city
state	Yes	string	The state or province code
postal_code	Yes	string	The postal code
country_code	Yes	string	ISO 3166-1 alpha-2 country code

Response

Returns a credentials object if successful.

{
  "card": {
    "number": "4111111111111111",
    "expiration_month": "12",
    "expiration_year": "2026",
    "cvc": "123"
  },
  "expires_at": "2026-02-20T00:00:00Z"
}

Credentials Object

Attribute	Type	Description
card	object	The virtual card credentials. See card credentials
expires_at	string	ISO 8601 timestamp for when the credentials expire

Card Credentials Object

Attribute	Type	Description
number	string	The virtual card number
expiration_month	string	The card expiration month
expiration_year	string	The four-digit card expiration year
cvc	string	The card verification code