Skip to main content
Issuing gives your agent a card number. Your server creates a virtual card for a user, and your agent types it into any checkout. The user verifies their identity once, then you can create as many cards for them as you need. The flow in one line: authenticate the user → they complete KYC → you fund the balance → your server creates a card → your agent pays with it. Steps 1 to 4 are setup. Steps 5 and 6 happen on every purchase.

1. Get your credentials

You need an Agentcard organization client_id and client_secret from the dashboard. Exchange them for an access token:
Use the returned token as $ORG_TOKEN. Sandbox credentials create sandbox users and test cards. Start there.

2. Authenticate a user

Send the user a one-time code, then verify it. In sandbox the code is always 111111.
Store user.id. Every card call names the user with it, using your org token. You don’t need the access_token or refresh_token for the steps below. Record consent once:
More on authenticating →

3. Complete KYC

Issued cards require identity verification. Read the status, and hand the user the hosted page it returns:
The user completes document capture and a face scan on that page. You learn the outcome from identity.verification.updated or by reading the status again. In sandbox nothing is reviewed, so approve the test user directly:
More on KYC →

4. Fund the company balance

Your company balance funds this card. If your organization is user-funded, switch it to company-funded once, in the dashboard under Settings, Issuing. An org owner has to do this. The change takes effect in sandbox immediately, and sandbox needs no plan or subscription. Until you switch, creating the card below is refused with company_flow_unavailable. Then add test money. In sandbox it is a mock balance and never real money:
To have users pay for their own cards instead, see Fund the card.

5. Create a card

Create the card with the user’s id:
Sandbox issues a test card immediately. In production a create can be refused first, for example with kyc_required or org_wallet_funding_required, which point back to steps 3 and 4. More on issuing →

6. Use the card

Read the credentials when your agent is at the checkout, not before:
Type them into the merchant’s form. A single-use card closes itself after its first approved charge. transaction.authorized tells your server money moved. More on using cards →

What’s next

Authenticating a user

Tokens, consent, refresh, and what each credential may call.

Completing a KYC

Hosted or custom verification, statuses, sandbox simulation.

Issuing a card

Funding, single-use and multi-use cards, merchant locks.

Using the cards

Reading credentials, paying, pausing, closing, webhooks.