Freeze card

Temporarily disables a partner card for payments. Freeze and unfreeze apply to the digital card and any associated physical card.

Freeze

POST/partner/v1/freezes

http

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
Idempotency-Key: <optional>

Field	Type	Required	Description
`wallet_id`	string	Yes	Partner wallet ID
`card_series`	string	Yes	Series of the current active digital card

json

{
  "wallet_id": "6a959342454db4ecdc9fef5d",
  "card_series": "3GGEN3QVVV"
}

json

{
  "wallet_id": "6a959342454db4ecdc9fef5d",
  "provider": "telebirr",
  "phone_e164": "+251911234567",
  "masked_phone": "+251911234567",
  "card_number": "6288881234567890",
  "masked_card_number": "•••• •••• •••• 7890",
  "card_series": "3GGEN3QVVV",
  "card_issued_at": "2026-08-31T14:44:18.326623",
  "issued_on": "digital",
  "status": "verified",
  "card_status": "frozen",
  "is_default": true,
  "created_at": "2026-08-31T14:44:18.326623",
  "unlinked_at": null,
  "cardholder_name": "Amina Hassan"
}

If the card is already frozen, the API returns 200 with the current state.

Emits wallet.frozen.

Unfreeze

POST/partner/v1/unfreezes

Use the same request body. Returns the wallet with card_status: "active". If already active, returns 200 with the current state.

Emits wallet.unfrozen.

See Webhooks.

Errors

Status	Detail
`400`	`Active digital card required`
`400`	`Frozen digital card required`
`400`	`card_series does not match wallet`
`400`	`card_series must be 10 characters`
`404`	`Wallet not found`
`409`	`Can't change card state while a payment is processing`
`409`	`Can't freeze card while a physical card request is open`
`401`	`Not authenticated` / `Invalid API key`

Example

bash

curl https://api.taappa.com/partner/v1/freezes \
  -H "Authorization: Bearer $TAAPPA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_id": "6a959342454db4ecdc9fef5d",
    "card_series": "3GGEN3QVVV"
  }'

bash

curl https://api.taappa.com/partner/v1/unfreezes \
  -H "Authorization: Bearer $TAAPPA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_id": "6a959342454db4ecdc9fef5d",
    "card_series": "3GGEN3QVVV"
  }'