Skip to main content

Order Physical Cards

Physical cards carry your program's artwork and ship worldwide. Ordering is a small state machine: you create an order, it is produced and shipped, and the cardholder activates the card on delivery.

API v1 · Legacy

This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: API v2 replaces it, and the platform today works as described in the rest of this manual.

Order states​

created → confirmed → in_production → shipped → delivered → activated

An order can be cancelled while in created or confirmed. After in_production, cancellation is no longer possible.

Create the order​

curl -X POST https://api.web3card.dev/v1/card-orders \
  -H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "usr_9f4c",
    "shippingAddress": {
      "line1": "Av. Paulista 1000",
      "city": "Sao Paulo",
      "state": "SP",
      "postalCode": "01310-100",
      "country": "BR"
    }
  }'
{
  "id": "ord_51de",
  "userId": "usr_9f4c",
  "status": "created",
  "estimatedDelivery": "2026-08-04",
  "createdAt": "2026-07-19T14:00:00Z"
}

Track the order​

curl https://api.web3card.dev/v1/card-orders/ord_51de \
  -H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx"

Order status changes also arrive as card_order.updated webhooks, including the carrier tracking code once shipped.

Activation​

On delivery, the cardholder activates the card by confirming the last four digits and setting a PIN, either in your app through the API or in the secure element UI:

curl -X POST https://api.web3card.dev/v1/cards/card_8a1f/activate \
  -H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "last4": "5678" }'

The physical card settles against the same vault as the user's virtual card, sharing balance and limits.

Last updated on