Get Card Data

Retrieve the Holyheld card details an agent may need for checkout flows, including the card number, expiration date, CVV, cardholder name, and billing address.

Sensitive card details

GET /card-data returns full payment card data. Only call it when the agent genuinely needs to complete a payment flow, never log the response, and avoid storing it longer than necessary.

Endpoint

GET https://apicore.holyheld.com/v4/ai-agents/card-data

Request

No request body. Authentication is the only required input.

Header	Required	Value
Authorization	✅	Bearer <token>

Response

200 OK

{
  "status": "ok",
  "payload": {
    "cardNumber": "5200828282828210",
    "expirationDate": "03/29",
    "cardholderName": "JOHN DOE",
    "CVV": "089",
    "billingAddress": "33 OUDEGRACHT, UTRECHT, 3511 AD, NETHERLANDS"
  }
}

Field	Type	Description
status	"ok"	Always "ok" on success
payload.cardNumber	string	Card number in compact format
payload.expirationDate	string	Expiration date in MM/YY format
payload.cardholderName	string	Cardholder name
payload.CVV	string	Card verification value
payload.billingAddress	string	Billing address string

Examples

curl

curl https://apicore.holyheld.com/v4/ai-agents/card-data \
  -H "Authorization: Bearer $HOLYHELD_AGENT_TOKEN"

JavaScript

async function getCardData(token) {
  const response = await fetch(
    'https://apicore.holyheld.com/v4/ai-agents/card-data',
    {
      headers: { Authorization: `Bearer ${token}` },
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`${error.errorCode}: ${error.error}`);
  }

  const { payload } = await response.json();
  return payload;
}

Python

import httpx

def get_card_data(token: str) -> dict:
    response = httpx.get(
        'https://apicore.holyheld.com/v4/ai-agents/card-data',
        headers={'Authorization': f'Bearer {token}'},
    )
    response.raise_for_status()
    return response.json()['payload']

When to call this endpoint

During checkout — fetch card details right before submitting a payment form on the user's behalf.

After balance checks — combine this with Get Balance when the agent needs to ensure funds exist before attempting payment.

Only when needed — do not prefetch or cache card data for convenience. Treat it as short-lived secret material.

Error responses

HTTP status	Error code	Meaning
401	AI_AUTHORIZATION_INVALID	Authorization header missing
403	AI_AUTHORIZATION_INVALID	Token invalid or agent access disabled
500	INTERNAL_SERVER_ERROR	Server error — retry with backoff

All error responses follow the standard shape:

{
  "status": "error",
  "errorCode": "AI_AUTHORIZATION_INVALID",
  "error": "Authorization header missing"
}

See Error Reference for recovery guidance.