Block Card

POST/cards/{serial}/blockOpen in the API playground →

Warning

Blocking a card prevents all transactions. Use for lost cards, suspected fraud, or at customer request.

Request

Authorizationstringheaderrequired

Bearer olive_live_xxx or Bearer eyJ... (JWT)

Path Parameters

serialstringpathrequired

Card serial number (e.g., OLIV0001)

Body Parameters

reasonstringbodyrequired

Reason for blocking (logged for audit)

pinstringbody

Subscriber's PIN (required for self-service blocking)

---

Response

successboolean

Whether block succeeded

messagestring

Result message

---

Examples

Request

cURL

curl -X POST "https://demo.api.vultlocal.com/api/v1/cards/OLIV0001/block" \
  -H "Authorization: Bearer olive_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Lost card - customer reported",
    "pin": "1234"
  }'

Response

200 Success

{
  "success": true,
  "message": "Card blocked successfully",
  "card": {
    "serial": "OLIV0001",
    "status": "BLOCKED",
    "blocked_at": "2025-01-20T14:45:00Z",
    "blocked_by": "admin@smartpay.sl",
    "block_reason": "Lost card - customer reported"
  }
}

404 Not Found

{
  "error": "Card not found",
  "code": "CARD_NOT_FOUND"
}

---

Block Reasons

Reason	Description	Reversible
Lost	Customer lost card	No (issue new card)
Stolen	Card reported stolen	No
Fraud	Suspected fraud	Yes (after investigation)
Request	Customer requested	Yes
Damaged	Physical damage	No (issue new card)

---

Effects

Transactions Blocked

• POS payments rejected
• NFC tap disabled
• PIN verification fails

Child Cards

• If parent blocked, child cards still work
• Block child cards separately if needed

---

Errors

Status	Code	Description
400	MISSING_REASON	Reason is required
400	INVALID_PIN	PIN verification failed
401	UNAUTHORIZED	Invalid API key
404	CARD_NOT_FOUND	Card serial not found
409	ALREADY_BLOCKED	Card already blocked
500	INTERNAL_ERROR	Server error

---

Related

Unblock Card

Restore a blocked card