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"
}'
{
"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"
}
}
{
"error": "Card is already linked to a subscriber",
"code": "CARD_ALREADY_LINKED"
}
{
"error": "Card not found",
"code": "CARD_NOT_FOUND"
}
Cards
Link Card
Link a parent NFC card to a subscriber account
POST
/
cards
/
link
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"
}'
{
"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"
}
}
{
"error": "Card is already linked to a subscriber",
"code": "CARD_ALREADY_LINKED"
}
{
"error": "Card not found",
"code": "CARD_NOT_FOUND"
}
Linking a card associates it with a subscriber’s wallet. The subscriber’s PIN is used for card transactions.
Request
string
required
Bearer olive_live_xxx or Bearer eyJ... (JWT)Body Parameters
string
required
Subscriber UUID to link the card to
string
required
Card serial number (e.g.,
OLIV0001)string
required
Subscriber’s 4-digit PIN for verification
Response
boolean
Whether linking succeeded
string
Result message
object
Linked card details
Examples
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"
}'
{
"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"
}
}
{
"error": "Card is already linked to a subscriber",
"code": "CARD_ALREADY_LINKED"
}
{
"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 |
Authorizations
ApiKeyAuthBearerAuth
API Key for third-party integrations (WhatsApp, Smart PAY, VULT). Format: 'Bearer olive_live_xxxxxxxxxxxxx'
Body
application/json
Link card details
Response
Card linked successfully
The response is of type object.
⌘I