Credentials

DEPRECATED

This API is deprecated and remains available for existing integrations. New integrations should use payment credentials. No removal date has been announced.

The credentials endpoint returns network-generated 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. The virtual number is not the funding card's PAN.

Treat the entire response as a sensitive bearer credential. Request it only from your backend, never log it, and expose it only to the agent or checkout that will use it.

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. A pending instruction returns 400 INSTRUCTION_PENDING, pending_verification returns 400 INSTRUCTION_PENDING_VERIFICATION, and cancelled returns 400 INSTRUCTION_CANCELLED. Any other non-approved status returns 404 INSTRUCTION_NOT_FOUND.

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": "2030",
    "cvc": "123"
  },
  "expires_at": "2030-02-20T00:00:00Z"
}

Publish a Transaction Confirmation

Reports an authorization or transaction outcome for a credential issued from an instruction.

POST

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

Permissions

agent:instruction:credentials

This endpoint accepts confirmations only for an approved non-autofill instruction. Visa forwards them to the card network. Mastercard and Stripe acknowledge them without a provider call because those integrations have no equivalent confirmation API.

Request

curl -X POST https://api.basistheory.com/agentic/agents/agt_fukICjsY2xzRCECiTCbKM/instructions/ins_luPDv2xm3Yb8RjFJz9oTC/confirmations \
  -H 'BT-API-KEY: <BT_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "confirmation_data": [
      {
        "transaction_reference_id": "txn_7bD9",
        "transaction_status": "approved",
        "transaction_type": "purchase",
        "transaction_timestamp": "2030-02-20T18:42:00.000Z",
        "amount": "99.99",
        "currency_code": "USD",
        "mandates_completed": true
      }
    ]
  }'

confirmation_data must contain at least one item.

Attribute	Required	Type	Description
transaction_reference_id	No	string	Provider transaction reference. When omitted, the service uses its stored reference or generates one
transaction_status	Yes	string	approved, declined, pending, error, or cancelled
transaction_type	Yes	string	purchase, authorization, capture, refund, reversal, verification, chargeback, or fraud
transaction_timestamp	No	string	ISO 8601 timestamp. Defaults to the current time
mandates_completed	No	boolean	Whether the mandate has completed
amount	Conditional	string	Decimal with at most two fractional digits. Supply with currency_code, or omit both
currency_code	Conditional	string	Three-letter uppercase currency code. Supply with amount, or omit both

Response

Returns 202 Accepted with a provider correlation identifier:

{
  "client_reference_id": "conf_2mL8pQ"
}

Errors: 400 VALIDATION_ERROR, 400 AUTOFILL_NOT_CONFIRMABLE, 400 INSTRUCTION_PENDING_VERIFICATION, 403 ENROLLMENT_ACCESS_DENIED, 404 AGENT_NOT_FOUND, 404 INSTRUCTION_NOT_FOUND, 500 PROVIDER_CONFIRMATION_FAILED.

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