Documents & biometrics

How RDCPASS delivers document images and biometric templates, and how to handle them safely.

When your application is granted a document or biometric scope, the response carries files: scans of identity documents, the enrollment selfie, fingerprint and iris templates. Every one of them is delivered as the same file object, in one of two modes you choose per request with document_delivery. Files are among the most sensitive data RDCPASS shares — this page explains how to fetch them, what formats to expect, and how to store them.

At a glance

Choosing a delivery mode

Set the mode per request with document_delivery. In a batch, the batch-level value applies to every item unless an item overrides it.

File object shapes

The file object has the same place in the response in both modes — only its fields change.

{
  "content_type": "image/jpeg",
  "url": "https://files.rdcpass.cd/d/9f2c41e8b7a3?sig=Qm9fX2t5Y19zaWc&exp=1790418002",
  "expires_at": "2026-09-26T10:20:02Z"
}

{
  "content_type": "image/jpeg",
  "data": "/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJChQODwwQFxQYGBcUFhYaHSUfGhsjHBYWICwgIyYnKSopGR8tMC0oMCUoKSj/2wBDAQcHBwoIChMKChMoGhYaKCgoKCgo..."
}

Where files appear

Working with signed URLs

• Valid for 5 minutes. Download each file as soon as you receive the response; if the window has passed, retrieve the validation again with GET /v1/kyc/validations/{id} to receive fresh URLs.
• Single-tenant. A URL is bound to the application that received it and cannot be used on behalf of another application.
• Fetch server-side. Never pass a signed URL to a browser, mobile app or third party — anyone holding it can download the file until it expires.
• Never persist the URL. Store the downloaded bytes, not the link: a stored URL is useless five minutes later and a liability until then.
• Do not follow redirects, and check that the returned Content-Type matches content_type.

Fetching a file

A helper that handles both delivery modes, checks expiry and content type, and returns the bytes:

// Turn any RDCPASS file object into bytes, on your server, right away.
// Works for both document_delivery modes.
export async function loadFile(file) {
  if (file.data) {
    // base64 delivery — the bytes are already in the response.
    return Buffer.from(file.data, 'base64')
  }

  // signed_url delivery — valid for 5 minutes from issue.
  if (Date.parse(file.expires_at) <= Date.now()) {
    throw new Error('Signed URL expired — retrieve the validation again for a fresh one')
  }

  const res = await fetch(file.url, { redirect: 'error' })
  if (!res.ok) {
    throw new Error(`File download failed with HTTP ${res.status}`)
  }

  const contentType = res.headers.get('content-type')
  if (contentType !== file.content_type) {
    throw new Error(`Unexpected content type: ${contentType}`)
  }

  return Buffer.from(await res.arrayBuffer())
}

// Usage — `validation` is a decrypted kyc_validation response.
// Store the bytes in your own encrypted storage, never the URL.
const image = await loadFile(validation.kyc.documents.primary.image)
await documentStore.putEncrypted(`kyc/${validation.id}/primary.jpg`, image)

base64 limits

base64 inlines every file into the response, so a single identity with documents and biometrics can produce a response of several megabytes. For that reason base64 is not available for batch results over 100 items — use signed_url for larger batches. Decode with a standard base64 decoder; the data contains no line breaks and no data: URI prefix.

Biometric templates

Fingerprints and iris data are delivered as templates in international standard formats, not as images. Each template entry wraps a file object:

{
  "fingerprints": [
    {
      "format": "ISO_19794_2",
      "finger": "right_index",
      "file": {
        "content_type": "application/octet-stream",
        "url": "https://files.rdcpass.cd/d/e2f47b91ac06?sig=Qm9fX2t5Y19zaWc&exp=1790418002",
        "expires_at": "2026-09-26T10:20:02Z"
      }
    }
  ],
  "iris": [
    {
      "format": "ISO_19794_6",
      "eye": "left",
      "file": {
        "content_type": "application/octet-stream",
        "url": "https://files.rdcpass.cd/d/5c09a2e7f13d?sig=Qm9fX2t5Y19zaWc&exp=1790418002",
        "expires_at": "2026-09-26T10:20:02Z"
      }
    }
  ]
}

Templates are designed to be compared by an ISO/IEC 19794-compliant matching engine. The enrollment selfie (kyc.biometrics.selfie) is a JPEG image with its captured_at date. If all you need is to confirm that a live person matches an identity, use Face Recognition instead of receiving biometric data at all.

Storage & retention

• Store only what your purpose requires. If you only need to confirm a document exists, keep the document fields and discard the image.
• Encrypt files at rest with keys held in a KMS or HSM, separate from your application database.
• Keep files out of logs, analytics, error trackers and caches. Log the validation id, never the file, URL or base64 data.
• Restrict access to the staff roles that need it, and audit every access.
• Apply a documented retention period and delete files when it ends or when the customer relationship closes, whichever comes first.
• Keep biometric templates in a dedicated store with the strictest controls, and never repurpose them beyond the purpose declared for the request.

Security notes

• Downloads are served over TLS 1.2 or higher from files.rdcpass.cd only. Reject any file URL on another host.
• Every file download is recorded against your application in the RDCPASS audit trail, alongside the validation that issued it.
• Your retention and deletion policy, and the controls above, are part of the application due diligence reviewed before production — see Going to production.

Next steps

• KYC scopes & subscriptions — which scopes return files, and their tiers.
• KYC Validation — a full response with every file object.
• Security model — how RDCPASS protects data in transit.
• Going to production — storage and retention requirements.