Skip to main content
The Virtual Cards API lets you issue and manage USD virtual debit cards for your users. A card is created on-demand through Checkbook and all subsequent spend activity can be queried through Onion’s API.
Base URL: /v1/virtual-cards

​
Authentication

All endpoints are secured with Onion’s API-Key header (x-api-key). 
x-api-key: <your-client-api-key>

​
Endpoints

​
1. Get or Create Card

Retrieve a user’s virtual card. If the user does not yet have a card one will be created automatically. GET /v1/virtual-cards/:userId

​
Path parameters

nametypedescription
userIdstringOnion user id

​
Response 200 OK

{
  "id": "vc_01hfxe0tqf1c820w3k48qb6g73",
  "userId": "usr_01hfxdz739gfba1xx6xe01qep4",
  "providerId": "cc_00123456789",
  "cardNumber": "4111 1111 1111 1111",
  "cardCVV": "123",
  "cardExpiry": "12/28",
  "createdAt": "2024-05-10T13:37:52.123Z",
  "updatedAt": "2024-05-10T13:37:52.123Z"
}

​
Errors

codeexample payload
400{ "error": "clientId missing" }

​
2. Explicitly Create Card

If you prefer to create the card explicitly use: POST /v1/virtual-cards

​
Body

{
  "userId": "usr_01hfxdz739gfba1xx6xe01qep4"
}
Returns the same payload as Get or Create above. If a card already exists the existing resource is returned.

​
3. List Card Transactions

Fetch a paginated list of transactions performed with the virtual card. GET /v1/virtual-cards/transactions/:userId/:page

​
Path parameters

nametypedescription
userIdstringOnion user id
pageintPage number (starting at 1)

​
Response 200 OK

{
  "page": 1,
  "pages": 4,
  "total": 37,
  "transactions": [
    {
      "amount": 25.48,
      "balance": 974.52,
      "created_ts": "2024-05-11T09:05:12Z",
      "description": "COFFEE SHOP",
      "id": "trxn_0123456789",
      "status": "SETTLED",
      "type": "DEBIT"
    }
  ]
}

​
Errors

codepayload
404{ "error": "virtual card not found" }