FiscoBridge SDC v3 – Verify PIN Endpoint Migration Guide (E-SDC)

This document explains how POS systems must migrate from the obsolete v2 Verify PIN endpoint to the current v3 standard for E-SDC.

It is intended for POS developers and resellers integrating cashier PIN verification with FiscoBridge E-SDC.

Official documentation reference (v3)

For the authoritative API definition, refer to the official FRCS documentation:

1. What is being replaced (important)

Obsolete v2 endpoint

The following endpoint is obsolete and must not be used anymore:

  • POST /api/Status/VerifyPin

This endpoint is fully replaced in v3.

2. New v3 endpoint (mandatory)

In v3, POS systems must use the following endpoint:

Purpose Endpoint Method
Verify cashier PIN /api/v3/pin POST

The endpoint:

  • Is a local E-SDC endpoint
  • Requires no authentication
  • Uses application/json headers
  • Sends and receives plain text PIN and status codes

3. Endpoint migration summary

Old v2 endpoint Status New v3 replacement
/api/Status/VerifyPin Obsolete /api/v3/pin

POS software must remove the old endpoint entirely.

4. Request format changes

Old v2 request (obsolete)

POST /api/Status/VerifyPin
Content-Type: application/json
Accept: application/json

{
  "VPIN": "1234"
}

New v3 request

POST /api/v3/pin
Content-Type: application/json
Accept: application/json

1234

Key differences

  • JSON object → plain text
  • Field name VPIN removed
  • PIN must contain exactly 4 ASCII digits (0–9)

5. Response format changes

Old v2 response (obsolete)

{
  "VPIN_GSC": "0100"
}

New v3 response

"0100"

Key differences

  • JSON object → plain text
  • Wrapper field VPIN_GSC removed
  • Response content is directly the status code

6. PIN handling behavior (unchanged but important)

  • Successful verification (0100) stores PIN in volatile memory (RAM)
  • POS does not need to resend PIN for each operation
  • PIN is cleared when:
    • Smart card is removed
    • E-SDC is restarted or powered off

If POS receives error code 1500, it must request PIN again and call /api/v3/pin.

7. Common response codes (v3)

Code Meaning
0100 PIN verified successfully
2100 PIN is incorrect
2110 PIN retry limit exceeded – card locked
1300 Smart card not inserted or inaccessible
2220 Secure Element applet not reachable
2400 E-SDC not fully configured
2806 PIN format invalid
1999 Unknown verification error

8. Migration checklist for POS developers

  1. Remove usage of /api/Status/VerifyPin
  2. Implement POST /api/v3/pin
  3. Change request body to plain text PIN
  4. Change response handling to plain text code
  5. Enforce 4-digit numeric PIN format
  6. Cache PIN verification until card removal or restart

9. Summary

  • Old Verify PIN endpoint is obsolete
  • v3 introduces a simpler, cleaner API
  • Functional behavior remains the same
  • All POS systems must use /api/v3/pin