Card Getting Started

Set up single-use virtual payment cards for your agent using the ACP CLI.

Prerequisites

• A registered agent (acp agent whoami)
• An email address (one account can serve multiple agents)

1. Initiate Signup

acp card signup --email "agent@example.com"

This sends a magic link to the provided email. Multiple agents may share one account — each agent's issued cards remain scoped to that agent. The response includes a state token and a nextStep pointing at signup-poll.

2. Verify via Magic Link

Open the inbox for the email you provided and click the magic link. Signup stays pending until the link is clicked.

3. Poll Signup Status

acp card signup-poll --state <state-token>

Poll until done: true. Once verified, the response's nextStep points at profile set so you know exactly what to do next.

4. Set a Profile

acp card profile set \
  --first-name "Ada" \
  --last-name "Lovelace" \
  --phone-number "+14155551234"

Phone numbers must be in E.164 format (+ followed by 1–15 digits). You can also inspect the current profile at any time:

acp card profile

5. Attach a Payment Method

acp card payment-method

Returns a Stripe setup URL. Open it in a browser and complete card setup. In --json mode the URL is also mirrored to stderr (>>> Open this URL to set up your card payment method:) so it surfaces even when the harness buffers stdout. The payment method is account-scoped — every agent on the same account can issue cards against it without re-entering details.

Run the same command again any time to replace the saved payment method: a fresh Stripe setup session is created, and whichever method you complete in the browser becomes the new active one. Accounts hold at most one payment method at a time.

6. Set a Spend Limit

Amounts are in cents (the BE DTO is amountCents). Minimum $1.00 (100 cents):

acp card limit set --amount 50000   # $500.00 total cap

Inspect the current limit and remaining balance with:

acp card limit

7. Issue a Card

Amounts are in cents: $1–$75 in whole-dollar increments (beta cap: 100–7500 cents, divisible by 100):

acp card issue --amount 2500   # $25 single-use card

Returns a single-use virtual card inline — PAN, CVV, expiry (month/year), and ZIP — issued synchronously against the saved payment method. The PAN and CVV are returned exactly once. Store them immediately; there is no way to re-fetch unmasked details later. The card is valid for 30 minutes from issuance.

8. List Issued Cards

acp card list

Lists only this agent's spend-requests, even when the account is shared with other agents.

9. Retrieve a Card

acp card get --request-id <id>

Returns a previously issued spend-request by ID. Returns 404 for requests owned by a different agent on the same account.

10. Handle 3DS Challenges

When a merchant runs a 3D Secure (3DS) challenge against an issued card, the verification code is delivered to your card account — not to the agent directly. Fetch it with:

acp card 3ds

This lists 3DS codes received in the last ~5 minutes, with the amount and how long ago each arrived. Match the code to the merchant's challenge prompt and submit it to complete checkout. Run the command again if the code hasn't arrived yet.

Output is a compact three-column layout (code · USD amount · age):

  123456   USD 19.99   30s ago

The post-acp card issue nextStep hint also points at this command, so agents discover it at the right moment in the flow.

CLI Reference

All commands support --json for machine-readable output. Amount flags are in cents (integer).