Unlink wallet

Unlinks a partner wallet and revokes its active digital card and any associated physical card. The phone number can be issued again later with POST /partner/v1/digital-cards.

POST/partner/v1/unlinks

Request

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"
}

Response

json

{
  "wallet_id": "6a959342454db4ecdc9fef5d",
  "provider": "telebirr",
  "phone_e164": "+251911234567",
  "masked_phone": "+251911234567",
  "card_number": "",
  "masked_card_number": "•••• •••• •••• ••••",
  "card_series": null,
  "card_issued_at": null,
  "issued_on": "digital",
  "status": "unlinked",
  "is_default": false,
  "created_at": "2026-08-31T14:44:18.326623",
  "unlinked_at": "2026-08-31T15:10:00.000000",
  "cardholder_name": "Amina Hassan"
}

If the wallet is already unlinked, the API returns 200 with the current state.

After unlink, issuing a digital card for the same phone reactivates the same wallet_id with a new active card.

Emits wallet.unlinked. See Webhooks.

Errors

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

Example

bash

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