Replace digital card

Replaces the active digital card for a wallet. The previous card is revoked and a new card number and series are issued.

POST/partner/v1/card-replacements

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

Returns the wallet with the new active digital card (same shape as Issue digital card).

json

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

Retrying with the series of an already-replaced card returns the current active card without issuing another replacement.

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 replace card while a payment is processing`
`409`	`Can't replace card while a physical card request is open`
`401`	`Not authenticated` / `Invalid API key`

Example

bash

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