Link Card

POST/cards/linkOpen in the API playground →

Info

Linking a card associates it with a subscriber's wallet. The subscriber's PIN is used for card transactions.

Request

Authorizationstringheaderrequired

Bearer olive_live_xxx or Bearer eyJ... (JWT)

Body Parameters

subscriber_idstringbodyrequired

Subscriber UUID to link the card to

card_serialstringbodyrequired

Card serial number (e.g., OLIV0001)

pinstringbodyrequired

Subscriber's 4-digit PIN for verification

---

Response

successboolean

Whether linking succeeded

messagestring

Result message

cardobject

Linked card details

---

Examples

Request

cURL

curl -X POST "https://demo.api.vultlocal.com/api/v1/cards/link" \
  -H "Authorization: Bearer olive_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber_id": "sub_abc123",
    "card_serial": "OLIV0001",
    "pin": "1234"
  }'

Response

200 Success

{
  "success": true,
  "message": "Card linked successfully",
  "card": {
    "serial": "OLIV0001",
    "mac_address": "AA:BB:CC:DD:EE:01",
    "type": "PARENT",
    "status": "ACTIVE",
    "subscriber_id": "sub_abc123",
    "linked_at": "2025-01-15T10:30:00Z"
  }
}

400 Already Linked

{
  "error": "Card is already linked to a subscriber",
  "code": "CARD_ALREADY_LINKED"
}

404 Not Found

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

---

Prerequisites

Card Exists

Card must be uploaded via CSV first

Card Unassigned

Card status must be "Unassigned"

---

Errors

Status	Code	Description
400	INVALID_PIN	PIN verification failed
400	CARD_ALREADY_LINKED	Card linked to another subscriber
401	UNAUTHORIZED	Invalid or missing API key
404	CARD_NOT_FOUND	Card serial doesn't exist
404	SUBSCRIBER_NOT_FOUND	Subscriber ID invalid
500	INTERNAL_ERROR	Server error