Skip to main content
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"
  }
}
Linking a card associates it with a subscriber’s wallet. The subscriber’s PIN is used for card transactions.

​
Request

​
Authorization
string
required
Bearer olive_live_xxx or Bearer eyJ... (JWT)

​
Body Parameters

​
subscriber_id
string
required
Subscriber UUID to link the card to
​
card_serial
string
required
Card serial number (e.g., OLIV0001)
​
pin
string
required
Subscriber’s 4-digit PIN for verification

​
Response

​
success
boolean
Whether linking succeeded
​
message
string
Result message
​
card
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"
  }
}

​
Prerequisites

Card Exists

Card must be uploaded via CSV first

Card Unassigned

Card status must be “Unassigned”

​
Errors

StatusCodeDescription
400INVALID_PINPIN verification failed
400CARD_ALREADY_LINKEDCard linked to another subscriber
401UNAUTHORIZEDInvalid or missing API key
404CARD_NOT_FOUNDCard serial doesn’t exist
404SUBSCRIBER_NOT_FOUNDSubscriber ID invalid
500INTERNAL_ERRORServer error

Authorizations

​
Authorization
string
header
required

API Key for third-party integrations (WhatsApp, Smart PAY, VULT). Format: 'Bearer olive_live_xxxxxxxxxxxxx'

Body

application/json

Link card details

​
card_serial
string
required

Supports any alphanumeric: CARD0001, 48290173K, etc.

Example:

"OLIV0001"

​
pin
string
required
Example:

"1234"

​
subscriber_id
string
required
Example:

"subscriber-uuid"

Response

Card linked successfully

The response is of type object.