Virtual cards give your agents the ability to make purchases autonomously. Create a card, fund it through a checkout flow, and assign it to agents who need to spend on behalf of the company.
CLI First
# Create cardholder and card
naive cards create-cardholder --first-name John --last-name Doe --billing-line1 "123 Main St" --billing-city "SF" --billing-state CA --billing-postal-code 94105
naive cards create --name "Marketing" --spending-limit 10000
# Check funding/issuance state
naive cards check-payment <card-id>
| Tool | Type | Description |
|---|
cards_cardholder | Setup | View the company’s cardholder |
cards_create_cardholder | Setup | Create a virtual card cardholder |
cards_update_cardholder | Setup | Update cardholder details |
cards_list | Core | List all virtual cards |
cards_create | Core | Create a virtual card (returns checkout URL) |
cards_details | Core | Get card credentials (PAN/CVC or redeem code) |
cards_check_payment | Core | Check if funding completed and issue card |
cards_retry_issue | Recovery | Retry failed card issuance |
cards_topup | Core | Top up card spending limit (returns checkout URL) |
cards_refund | Recovery | Refund a failed card’s payment |
cards_cancel | Core | Cancel/deactivate a card |
cards_assign | Management | Assign an agent to a card |
cards_unassign | Management | Remove agent assignment |
cards_assignments | Management | List agents assigned to a card |
cards_log_transaction | Tracking | Log a manual spend transaction |
cards_transactions | Tracking | List card transactions |
Card Providers
Provider (provider value) | Card Type | Limit | Cardholder Required? |
|---|
Prepaid gift cards (prepaid_gift) — default | Prepaid gift card (Visa) | $150.00 max | No |
Managed virtual cards (managed_virtual) | Virtual Visa/Mastercard | No maximum | Yes |
If you omit provider, cards default to prepaid_gift (prepaid Visa, no cardholder required). Pass provider: "managed_virtual" for a full virtual card with no spending cap — that path requires a cardholder to be created first.
Cardholder Setup (managed virtual cards)
Before creating managed virtual cards, you must create a cardholder once per company. This registers identity information for KYC compliance.
curl -X POST https://api.usenaive.ai/v1/cards/cardholder \
-H "Authorization: Bearer nv_sk_your_key" \
-H "Content-Type: application/json" \
-d '{
"firstName": "John",
"lastName": "Doe",
"email": "john@acme.com",
"billingLine1": "123 Main St",
"billingCity": "San Francisco",
"billingState": "CA",
"billingPostalCode": "94105",
"dobDay": 15,
"dobMonth": 6,
"dobYear": 1990
}'
Prepaid gift cards do not require a cardholder. You can skip this step if you only use provider: "prepaid_gift".
Creating a Card
Card creation follows a checkout flow — you receive a checkout_url for the card’s initial funding.
Create the card
curl -X POST https://api.usenaive.ai/v1/cards \
-H "Authorization: Bearer nv_sk_your_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Marketing Card",
"spending_limit_cents": 10000,
"provider": "managed_virtual"
}'
{
"card": {
"id": "card-uuid",
"name": "Marketing Card",
"status": "pending_payment",
"spendingLimitCents": 10000,
"provider": "managed_virtual"
},
"checkout_url": "https://checkout.usenaive.ai/c/pay/cs_live_...",
"session_id": "cs_live_...",
"expires_at": "2026-05-04T07:00:00.000Z",
"hint": "Open the checkout URL to fund the card. After payment, use check-payment to issue.",
"next_steps": [{ "command": "naive cards check-payment card-uuid", "description": "Check payment and issue card" }]
}
Complete payment
Open the checkout_url in a browser and complete the payment. The checkout session expires after 30 minutes.
Issue the card
After payment, check the status and issue the card:curl -X POST https://api.usenaive.ai/v1/cards/card-uuid/check-payment \
-H "Authorization: Bearer nv_sk_your_key"
status: "active". Get card credentials
Once active, retrieve the full card number and CVC:curl https://api.usenaive.ai/v1/cards/card-uuid/details \
-H "Authorization: Bearer nv_sk_your_key"
{
"card_id": "card-uuid",
"name": "Marketing Card",
"provider": "managed_virtual",
"number": "4242424242424242",
"cvc": "123",
"exp_month": 12,
"exp_year": 2028,
"last4": "4242",
"brand": "Visa",
"spending_limit_cents": 10000,
"spent_cents": 0,
"remaining_cents": 10000
}
Top-Up
Add more funds to an active card’s spending limit:
curl -X POST https://api.usenaive.ai/v1/cards/card-uuid/top-up \
-H "Authorization: Bearer nv_sk_your_key" \
-H "Content-Type: application/json" \
-d '{ "amount_cents": 5000 }'
checkout_url for the top-up payment, just like card creation.
Agent Assignments
Cards can be assigned to specific agents, controlling which agents have access to spend:
# Assign an agent
curl -X POST https://api.usenaive.ai/v1/cards/card-uuid/assign \
-H "Authorization: Bearer nv_sk_your_key" \
-H "Content-Type: application/json" \
-d '{ "agent_id": "agent-uuid" }'
# List assignments
curl https://api.usenaive.ai/v1/cards/card-uuid/assignments \
-H "Authorization: Bearer nv_sk_your_key"
# Remove assignment
curl -X DELETE https://api.usenaive.ai/v1/cards/card-uuid/assign/agent-uuid \
-H "Authorization: Bearer nv_sk_your_key"
Transaction Logging
Track agent spending by logging manual transactions:
curl -X POST https://api.usenaive.ai/v1/cards/card-uuid/log-transaction \
-H "Authorization: Bearer nv_sk_your_key" \
-H "Content-Type: application/json" \
-d '{
"amount_cents": 2500,
"merchant_name": "AWS",
"description": "Cloud hosting payment",
"agent_id": "agent-uuid"
}'
Managed virtual cards also capture transactions automatically via payment webhooks. Manual logging is for non-card purchases (e.g., prepaid gift cards or offline transactions).
Card Statuses
| Status | Meaning |
|---|
pending_payment | Checkout created, waiting for payment |
active | Card is issued and ready to use |
issuing_failed | Payment succeeded but card issuance failed (can retry) |
payment_failed | Checkout expired or payment failed |
refunded | Payment was refunded |
canceled | Card was deactivated |
Error Handling
| Error | Cause | Recovery |
|---|
duplicate_record | Cardholder already exists for this company | Use GET to view or PATCH to update |
invalid_input (no cardholder) | Tried to create managed virtual cards card without a cardholder | Create a cardholder first |
invalid_input (limit too low) | Spending limit below $1.00 (100 cents) | Increase the spending limit |
invalid_input (prepaid max) | prepaid gift card exceeds $150 limit | Use managed virtual cards for higher limits |
resource_not_found | Card ID doesn’t exist or belongs to another company | Use GET /v1/cards for valid IDs |
provider_error | Card provider API error during issuance | Use retry-issue or refund |
Typical Workflows (Agent Perspective)
Creating and using a managed virtual cards card
1. GET /v1/cards/cardholder
→ cardholder: null — need to create one
2. POST /v1/cards/cardholder { firstName, lastName, billing..., dob... }
→ cardholder created
3. POST /v1/cards { name: "Agent Card", spending_limit_cents: 10000 }
→ checkout_url: "https://checkout.usenaive.ai/..."
→ Share with user: "Fund the card at this URL"
4. [User completes checkout]
5. POST /v1/cards/<id>/check-payment
→ status: "active", last4: "4242"
6. GET /v1/cards/<id>/details
→ number, cvc, expMonth, expYear — ready to use
7. POST /v1/cards/<id>/log-transaction { amount_cents: 2500, merchant_name: "AWS" }
→ Transaction logged
Creating a prepaid gift card
1. POST /v1/cards { name: "Prepaid Card", spending_limit_cents: 5000, provider: "prepaid_gift" }
→ checkout_url — fund via hosted checkout
2. [User completes checkout]
3. POST /v1/cards/<id>/check-payment
→ status: "active" — prepaid gift cards gift card issued
4. GET /v1/cards/<id>/details
→ number (redeem code), pin, redeem_instructions
