Blocking and cancelling cards

Both physical and virtual cards may be either canceled or blocked. The difference between canceling and blocking is mainly that cancelation is an irreversible action. Once a card is cancelled it can never be uncanceled, whereas a blocked card may be unblocked through the API.

Card Cancelation

A card may be cancelled through the POST /wallets/:walletId/cards/:cardId/cancel endpoint. A cancelation reason must be passed in the payload in the reason field. The accepted values for the cancelation reason are as given on the table below:

Available Reasons

Additionally the payload also contains the fields comment allowing the user to add any additional information regarding the card cancelation reason and the field asset which specifies the code for the card's asset. If the field asset is not specified it defaults to the root asset. If the resolved asset (either the asset with the given code or the root asset if none is specified) does not support the cards feature or the card was emitted with a different asset, the API shall return an error response.

A card may only be canceled once it has been embossed, delivered and activated (corresponding to phaseId equal to or larger than 5). Any request to cancel a card before that shall return an error response.

A card cancelation may be requested using the SDK by following the example code:

const walletId = '988da95f-985f-4ebd-aa39-3e71cf0656dd';
const cardId = '4f9bc5f9-05fb-47fe-99f0-0465782d5e78 ';

await bicapital.cards().cancel({ walletId, cardId, reason: 6 /* DAMAGED */ });

curl --location --request POST "$BASE_URL/wallets/$WALLET_ID/cards/$CARD_ID/cancel" \
  --header 'Authorization: Bearer 0000000000000000000000000000000000000000'\
  --header "Content-Type: application/json" \
  --data "{
   \"comment\": \"Damaged\",
   \"reason\": 9
}"

Card Blocking

A card may be blocked through the POST /wallets/:walletId/cards/:cardId/block endpoint. It accepts a payload containing a comment field adding additional info regarding the card's blocking and an optional asset field containing the code of the card's asset. If the asset is not specified the root asset is assumed.

A card may only be blocked if its state is AVAILABLE.

Code examples using the javascript SDK are presented below.

const walletId = '';
const cardId = '';
const password = '';

// Blocking a card
await bitcapital.cards().block({ walletId, cardId, password })

Card Unblocking.

Blocked cards may be unblocked through the POST /wallets/:walletId/cards/:cardId/unblock endpoint. As all the card enpoints it accepts an optional body parameter asset specifying the card's asset, if the parameter is not passed the card's asset is assumed or the root asset.

For cards which have been blocked due to exceeding the maximum number of incorrect password attempts it is necessary to pass in an additional body parameter unblockIncorrectPassword: true to unblock it. Trying to unblock a card blocked due to incorrect password attempts without this flag or trying to unblock a card blocked for other reasons while passing this flag will both result in error codes with messages instructing you to either include or remove the flag.

A card may only be unblocked if it is blocked. trying to unblock a card which is either unblocked or canceled will return an error.

Code examples using the javascript SDK are presented below.

const walletId = '';
const cardId = '';
const password = '';

// Unblocking a card blocked due to exceeding max incorrect password attempts
await bitcapital.cards().unblock({ walletId, cardId, password, unblockIncorrectPassword: true })

// Unblocking a card blocked due to other reasons.
await bitcapital.cards().unblock({ walletId, cardId, password });