Create a card

curl --request POST \
  --url https://api.agentcard.sh/api/v2/cards \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amount_cents": 2500,
  "currency": "usd",
  "description": "Order #1042"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({amount_cents: 2500, currency: 'usd', description: 'Order #1042'})
};

fetch('https://api.agentcard.sh/api/v2/cards', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.agentcard.sh/api/v2/cards"

payload = {
    "amount_cents": 2500,
    "currency": "usd",
    "description": "Order #1042"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "object": "card",
  "id": "<string>",
  "status": "approval_pending",
  "spend_limit_cents": 123,
  "balance_cents": 123,
  "connected_card_id": "<string>",
  "last4": "<string>",
  "expiry": "12/30",
  "created_at": "2023-11-07T05:31:56Z",
  "approval_url": "<string>",
  "expires_at": "2023-11-07T05:31:56Z",
  "closed_reason": "<string>",
  "credentials": {
    "number": "<string>",
    "exp_month": 123,
    "exp_year": 123,
    "cvc": "<string>"
  },
  "credentials_status": "<string>"
}

{
  "object": "card",
  "id": "<string>",
  "status": "approval_pending",
  "spend_limit_cents": 123,
  "balance_cents": 123,
  "connected_card_id": "<string>",
  "last4": "<string>",
  "expiry": "12/30",
  "created_at": "2023-11-07T05:31:56Z",
  "approval_url": "<string>",
  "expires_at": "2023-11-07T05:31:56Z",
  "closed_reason": "<string>",
  "credentials": {
    "number": "<string>",
    "exp_month": 123,
    "exp_year": 123,
    "cvc": "<string>"
  },
  "credentials_status": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

Member cards

Create a card

Create a one-time virtual card against the member’s added card, then key its credentials into your checkout and close it when you’re done. Sandbox answers 201 with an open test card. Production answers 202 approval_pending with an approval_url the member confirms with a passkey; retry with the SAME Idempotency-Key (or watch flow status) until the card is open, then read it once on Get a card. Credentials stay valid for about an hour, so create the card right before checkout.

POST

api

cards

Create a card

curl --request POST \
  --url https://api.agentcard.sh/api/v2/cards \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amount_cents": 2500,
  "currency": "usd",
  "description": "Order #1042"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({amount_cents: 2500, currency: 'usd', description: 'Order #1042'})
};

fetch('https://api.agentcard.sh/api/v2/cards', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.agentcard.sh/api/v2/cards"

payload = {
    "amount_cents": 2500,
    "currency": "usd",
    "description": "Order #1042"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "object": "card",
  "id": "<string>",
  "status": "approval_pending",
  "spend_limit_cents": 123,
  "balance_cents": 123,
  "connected_card_id": "<string>",
  "last4": "<string>",
  "expiry": "12/30",
  "created_at": "2023-11-07T05:31:56Z",
  "approval_url": "<string>",
  "expires_at": "2023-11-07T05:31:56Z",
  "closed_reason": "<string>",
  "credentials": {
    "number": "<string>",
    "exp_month": 123,
    "exp_year": 123,
    "cvc": "<string>"
  },
  "credentials_status": "<string>"
}

{
  "object": "card",
  "id": "<string>",
  "status": "approval_pending",
  "spend_limit_cents": 123,
  "balance_cents": 123,
  "connected_card_id": "<string>",
  "last4": "<string>",
  "expiry": "12/30",
  "created_at": "2023-11-07T05:31:56Z",
  "approval_url": "<string>",
  "expires_at": "2023-11-07T05:31:56Z",
  "closed_reason": "<string>",
  "credentials": {
    "number": "<string>",
    "exp_month": 123,
    "exp_year": 123,
    "cvc": "<string>"
  },
  "credentials_status": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "docs": "<string>",
    "field_errors": {},
    "warnings": [
      "<string>"
    ]
  }
}

Create a one-time virtual card against the member’s added card. This is the bring-your-own-checkout flow: create the card, key its credentials into the merchant’s payment form yourself, then close it. Sandbox answers 201 with an open test card, credentials included. Production answers 202 approval_pending with an approval_url the member confirms with a passkey; retry with the same Idempotency-Key until the card is open. Credentials stay valid for about an hour, so create the card right before checkout, not ahead of time.

Authorizations

Authorization

string

header

required

The user's connection access_token (user authentication), or an org-minted buy_token for org-owned accounts.

Headers

Idempotency-Key

string

required

Stable key for THIS card intent (your order id). Retries with the same key resume the same card; they never create a second one.

Body

application/json

amount_cents

integer

required

Exact amount in cents the card can spend, e.g. 2500 = $25.00.

Required range: 100 <= x <= 2000000

currency

enum<string>

Available options:

usd

connected_card_id

string

Draw on a specific added card. Omit to use the newest active one.

merchant

object

Show child attributes

description

string

Maximum string length: 200

metadata

object

Response

The card is open (sandbox, and frictionless production mints).

A one-time virtual card created against the member's added card.

object

string

Example:

"card"

string

status

enum<string>

Envelope status. open carries credentials; approval_pending carries approval_url.

Available options:

approval_pending,

open,

in_use,

paused,

closed

spend_limit_cents

integer

balance_cents

integer

connected_card_id

string | null

The attachment this card draws on.

last4

string

expiry

string

Example:

"12/30"

created_at

string<date-time>

approval_url

string

Only while approval_pending: the page where the member approves this purchase with a passkey.

expires_at

string<date-time>

Only while approval_pending: when the approval window closes.

closed_reason

string

Only when closed: used, canceled, expired, or declined.

credentials

object

Only on an open card: the one-time credential to key into a checkout. Never persist it.

Show child attributes

credentials_status

string

protected when the member requires an approval per reveal; retry when the credential read should be retried.

⌘I

Authentication

Connect

Add a card

Member cards

Balance

Withdrawals

Identity verification

Platform connect

Create a card

Authorizations

Headers

Body

Response