Card controls and digital wallets

These calls act on a card that already exists. To order or cancel a card, see Issue a card.

Prerequisites

A card ID. List cards with GET /v3/finance/cards.
A credential with payments.card:read to read, and payments.card:write to change.

Set or change the PIN

Call POST /v3/finance/cards/{cardId}/set-pin with pin. The same pin field can go in the body of the activate call.

Never send a clear-text PIN. Encrypt it on the client with the card processor's public key and send it base64-encoded. The value must be at least 344 characters. A shorter value, including a plain four-digit PIN, is rejected with 422. A missing pin also returns 422.

The response is the card. Wingspan never returns the PIN.

Read and change spending limits

Read limits with GET /v3/finance/cards/{cardId}/limits.

// 200 OK
{
  "limitType": "Monthly",
  "limit": 5000.00,
  "availableLimit": 3750.00,
  "spendVelocity": 1250.00
}

limit is the cap. spendVelocity is what has been spent in the period, and availableLimit is what's left.

Change a limit with PATCH /v3/finance/cards/{cardId}/limits. Both fields are required, and no others are accepted.

Field	Values
`limitType`	`Transaction`, `Monthly`, `Annually`, or `Forever`
`limit`	The new amount, in major units

curl -X PATCH "https://api.wingspan.app/v3/finance/cards/Cd6Wn3Qk8Lx5Bz2Mh7Rc4T/limits" \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "limitType": "Monthly", "limit": 5000.00 }'

The response has the same shape as the read.

Show card details

The card number, CVV, and expiry never appear in API responses. To show them to the cardholder, call GET /v3/finance/cards/{cardId}/embed-url. It returns a short-lived embedUrl. Put it in an iframe.

Query parameter	Notes
`css`	The URL of a stylesheet applied inside the frame
`targetOrigin`	The origin allowed to receive the frame's messages, as `scheme://host[:port]`

// 200 OK
{ "embedUrl": "https://cards.example-processor.com/embed/..." }

The URL is short-lived. Request a new one each time you show the card. Don't store it.

Add a card to Apple Pay or Google Pay

Call POST /v3/finance/cards/{cardId}/tokenize from the flow that provisions the card into the phone wallet.

Field	Required	Notes
`walletType`	Yes	`ApplePay` or `GooglePay`
`certificate`, `nonce`, `nonceSignature`	No	Values the wallet provider gives your app
`clientDeviceId`, `clientWalletAccountId`	No	Identifiers from the wallet provider

The response has tokenReferenceId, status (Active, Pending, or Failed), and walletType. Pass the result back to the wallet provider.

Errors

Status	Meaning
`403`	Missing scope
`404`	The card doesn't exist or isn't yours
`422`	`pin` is missing or isn't encrypted, a limit field is invalid, or `walletType` isn't `ApplePay` or `GooglePay`