Driverscan / Guides

How to decode the encrypted South African driver's licence barcode

Published 11 September 2026 · 6 minute read

The barcode on the back of a South African driver's licence card is a PDF417 symbol carrying 720 bytes of binary data, and almost all of it is encrypted. Any PDF417 scanner can read the symbol, but what comes out is encrypted binary that looks like noise. To get the licence number, names, dates, vehicle codes and photo, the payload has to be decrypted and parsed by a licence decoder such as Driverscan.

This guide explains what is in the barcode, where people usually go wrong, and how to decode it with one HTTP request.

What is in the barcode

The raw payload is always 720 bytes. Written as hexadecimal, which is how most integrations pass it around, that is 1,440 characters. Once decoded, the licence record holds:

  • Surname and initials (initials only, not full first names)
  • South African ID number and the licence number
  • The vehicle licence codes held, each with its first issue date
  • Vehicle restrictions and driver restriction codes
  • Professional Driving Permit (PrDP) categories and expiry date
  • Licence valid-from and valid-to dates, birth date and gender
  • The licence holder's photo, compressed in a wavelet image format

Why a normal barcode reader shows gibberish

A PDF417 reader only undoes the barcode symbology. It hands you the 720 bytes exactly as printed, which are still encrypted. Many scanners then try to show those bytes as text, which mangles them further. Two rules avoid most failed integrations:

  • Keep the bytes raw. Configure the scanner or SDK to return binary, and convert it to hexadecimal yourself. A payload that has been through a text conversion cannot be recovered.
  • Send hex, not base64. The Driverscan API expects the 1,440-character hex string in a field called encrypted. Base64 of the same bytes will fail.

Decoding it with Driverscan

Post the hex payload to the decode endpoint with your API token:

curl -H 'Authorization: Bearer YOUR_API_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{"encrypted": "HEX_PAYLOAD_FROM_SCANNER"}' \
     https://driverscan.co.za/api/decode

The same endpoint accepts every supported document and works out which one it has been given. A decoded licence comes back as JSON under a license key, with fields such as surname, initials, idNumber, licenseNumber, codes, licenseValidFrom, licenseValidTo and prdpExpiryDate.

If you only have a photo or scan of the barcode rather than the raw bytes, post the image instead. The /api/pdf417 endpoint takes a JPG, PNG or PDF of up to 10 MB, reads the barcode and returns the same decoded licence.

Formats worth knowing before you map the fields

  • Dates are YYYYMMDD strings: a birth date comes back as 19790211, not 1979-02-11.
  • gender is a two-character code such as 01, not a letter.
  • Array fields such as codes always have the same length. Unused slots are empty strings, so filter them out rather than counting the array.

Getting the photo

The photo on the card is stored inside the barcode in a compressed wavelet format that ordinary image libraries cannot open. Add "outputFormat": "png" to the same request and the response includes an image field holding a PNG of the licence holder:

curl -H 'Authorization: Bearer YOUR_API_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{"encrypted": "HEX_PAYLOAD_FROM_SCANNER", "outputFormat": "png", "imageEncoding": "base64"}' \
     https://driverscan.co.za/api/decode

The image is hex-encoded by default; "imageEncoding": "base64" returns base64, which most front ends can display directly. Some cards store the photo upside down, and "flipImage": "true" corrects it.

When decoding fails

A payload that is empty, too short to be a licence, or not valid hex is rejected with HTTP 400 and a message saying what is wrong. A failed decode is not charged. The usual causes are a scanner in text mode, a payload that was base64-encoded, or a barcode that was only partly read.

Other South African documents

The licence card is not the only barcode you are likely to meet at a counter or gate:

  • Vehicle licence disc. Not encrypted. The text starts with %MVL and is split by % characters. It carries the registration number, make, model, colour, VIN, engine number and expiry date.
  • Temporary driver's licence. Text starting with %TDL.
  • Smart ID card. Plain pipe-separated text. See what the smart ID card barcode contains.
  • Namibian driver's licence. A different binary format, decoded by the same endpoint.

If you are choosing between building this yourself and using a service, the decoder options comparison covers the trade-offs.

Try Driverscan

Driverscan is a REST API run by Apex Technology. Register for an account to get an API token and the full documentation, or contact sales about volume pricing.

Related guides