Issue a card

A card is a debit card tied to your Wingspan Wallet. Spending comes out of the Wallet balance. This page covers ordering a card and managing its status. For PINs, limits, showing card details, and phone wallets, see Card controls and digital wallets.

These are cards Wingspan issues to you. They aren't the cards you save to pay with. For those, see Payment and payout methods.

Prerequisites

• A Wallet. See Internal accounts and balances.
• A credential with payments.card:write to change cards, and payments.card:read to read them.

Order a card

Call POST /v3/finance/cards.

curl -X POST "https://api.wingspan.app/v3/finance/cards" \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-card-2026-10-20" \
  -d '{
    "cardType": "Physical",
    "customName": "Travel card",
    "shippingAddress": {
      "line1": "123 Market St",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94105",
      "country": "US"
    }
  }'

// 201 Created (trimmed)
{
  "id": "Cd6Wn3Qk8Lx5Bz2Mh7Rc4T",
  "status": "PendingFulfillment",
  "cardType": "Physical",
  "customName": "Travel card",
  "last4": "4821",
  "expirationMonth": 10,
  "expirationYear": 2030,
  "internalAccountId": "Ia4Kq9Wn2Lx7Tz5Bm8Hc3V",
  "events": { "createdAt": "2026-10-20T15:02:11Z" }
}

Card statuses

events holds a timestamp for each change: activatedAt, suspendedAt, cancelledAt, reportedLostStolenAt, and reissuedAt.

Activate a card

Call POST /v3/finance/cards/{cardId}/activate. The body is optional. It can carry an encrypted pin to set the first PIN. See Card controls and digital wallets for how to encrypt it. The response is the card.

List and read cards

• GET /v3/finance/cards lists your cards. Filter with filter[status][eq] and one of the statuses above. An unknown status returns 422.
• GET /v3/finance/cards/{cardId} reads one.

Card responses show only last4 and the expiry. The full card number and CVV are never in an API response. To show them to the cardholder, see Show card details.

Rename a card

Call PATCH /v3/finance/cards/{cardId} with customName. That is the only field you can change. metadata returns 422.

Suspend or cancel

• POST /v3/finance/cards/{cardId}/suspend pauses the card. The reference says it can be reactivated later.
• POST /v3/finance/cards/{cardId}/cancel closes the card for good. You can't undo it.

Both return the card. A 409 means the card's current status doesn't allow the change.

Replace a lost or damaged card

Order a new card with replacesCardId set to the old card's id. The cardType must match. Cards carry replacesCardId and replacedByCardId so you can follow the chain. Cancel the old card with the call above if it is lost.

Errors

Webhook events

Card.Created, Card.Activated, Card.Suspended, Card.Cancelled, Card.ReportedLostStolen, Card.Reissued and Card.Updated are published. See Webhooks and events to subscribe.

Related pages

• Card controls and digital wallets
• Internal accounts and balances