Verify PIN

POST/subscribers/{id}/verify-pinOpen in the API playground →

Info

Use this endpoint to verify a subscriber's PIN before processing sensitive operations.

Request

Authorizationstringheaderrequired

Bearer olive_live_xxx or Bearer eyJ... (JWT)

Path Parameters

idstringpathrequired

Subscriber UUID (e.g., sub_abc123)

Body Parameters

pinstringbodyrequired

4-digit PIN to verify

---

Response

successboolean

Whether PIN is valid

messagestring

Result message

---

Examples

Request

cURL

curl -X POST "https://demo.api.vultlocal.com/api/v1/subscribers/sub_abc123/verify-pin" \
  -H "Authorization: Bearer olive_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "pin": "1234"
  }'

Response

200 Valid PIN

{
  "success": true,
  "message": "PIN verified successfully"
}

401 Invalid PIN

{
  "success": false,
  "message": "Invalid PIN",
  "attempts_remaining": 2
}

403 Account Locked

{
  "success": false,
  "message": "Account locked due to too many failed attempts",
  "locked_until": "2025-01-20T16:00:00Z"
}

---

PIN Security

Attempt Limits

• 3 failed attempts allowed
• Account locked for 30 minutes
• Counter resets on success

Audit Logging

• All attempts logged
• IP address recorded
• Used for fraud detection

---

Use Cases

Use Case	Description
POS Payment	Verify before deducting funds
P2P Transfer	Confirm sender identity
Cash-Out	Authenticate withdrawal
Profile Change	Verify before sensitive updates

---

Errors

Status	Code	Description
400	INVALID_PIN_FORMAT	PIN must be 4 digits
401	UNAUTHORIZED	Invalid or missing API key
401	INVALID_PIN	PIN does not match
403	ACCOUNT_LOCKED	Too many failed attempts
404	NOT_FOUND	Subscriber not found
500	INTERNAL_ERROR	Server error

---

Related

Change PIN

Change subscriber's PIN to a new value