HSM PIN Capture Service

Secure PIN capture with OAuth2 authentication

API Documentation

POST /api/pin/request

Initiates a new PIN capture session

{
  "callback_url": "https://your-server.com/webhook",
  "metadata": {
    "document_id": "doc-123",
    "user_email": "user@example.com"
  }
}

Response:

{
  "session_id": "uuid",
  "capture_url": "https://pincode.firmadox.cl/capture/{session_id}"
}

Webhook Payload (on completion)

{
  "session_id": "uuid",
  "status": "completed",
  "pin": "123456",
  "bearer_token": "eyJhbG...",
  "id_token": "eyJhbG...",
  "metadata": { ... },
  "completed_at": "2024-01-15T10:30:00Z"
}

Authentication Flow

  1. Your system calls /api/pin/request
  2. User is redirected to capture_url
  3. User authenticates via Alberto OAuth2 (FirmaDOX IDP)
  4. User enters their HSM certificate PIN
  5. PIN + Bearer Token are sent to your callback_url

Security Features

  • PIN is never displayed on screen
  • OAuth2 with PKCE for secure authentication
  • Sessions expire automatically
  • PIN is transmitted via secure webhook only

HSM PIN Capture Service - FirmaDOX