Overview

The config object on Create transaction declares what should be accepted. Every field is optional and has a default, so "config": {} is valid — you only set what you want to change. Configuration is per transaction, not per account. Two verifications for the same customer can enforce completely different rules, which is what lets you run a strict onboarding check and a lighter step-up check from the same integration.

Shape

{
  "transaction_ttl_minutes": 1440,
  "webhook":          { "url": "https://api.example.com/hooks/chmod" },
  "device_policy":    { "...": "..." },
  "document_policy":  { "...": "..." },
  "biometric_policy": { "...": "..." },
  "blacklist_policy": { "...": "..." }
}

Device policy

Rooted devices, emulators, VPNs and spoofed GPS.

Document policy

Accepted documents, expiry, and matching against expected data.

Biometric policy

Liveness and face-comparison thresholds, age and gender.

Blacklist policy

Faces on an internal or global blocklist.

Which policies apply

A policy that does not apply to the transaction type is ignored:

Policy	`DOCUMENT_AND_BIOMETRIC`	`DOCUMENT_ONLY`	`BIOMETRIC_ONLY`
`device_policy`	Applies	Applies	Applies
`document_policy`	Applies	Applies	Ignored
`biometric_policy`	Applies	Ignored	Applies
`blacklist_policy`	Applies	Applies	Applies

Policy actions

Most policy fields take one of three actions. This is the vocabulary that runs through the whole configuration:

Action	Effect
`REJECT`	Emits a `REJECT` issue. The transaction is `REJECTED`.
`WARN`	Emits a `WARN` issue. The decision is unchanged. Recorded for your review.
`IGNORE`	Emits nothing. The signal is not evaluated.

WARN is how you observe a signal before you start enforcing it. Ship a new rule as WARN, watch how often it fires against real traffic, then move it to REJECT once you know the false-positive rate.

Defaults

What you get when you omit a field entirely:

Field	Default
`transaction_ttl_minutes`	`1440` (24 hours)
`webhook`	none — no notification is sent
`device_policy.on_compromised_device`	`REJECT`
`device_policy.on_developer_mode`	`WARN`
`device_policy.on_emulator`	`REJECT`
`device_policy.on_vpn_or_proxy`	`WARN`
`device_policy.on_gps_mock_location`	`REJECT`
`device_policy.on_gps_ip_location_mismatch`	`WARN`
`document_policy.document_eligibility`	every supported document is accepted
`document_policy.data_matching`	nothing is matched
`biometric_policy.liveness_min_score`	`0.85`
`biometric_policy.face_comparison_min_score`	`0.85`
`biometric_policy.expected_gender`	`null` (any)
`biometric_policy.expected_min_age` / `expected_max_age`	`null` (any)
`biometric_policy.require_face_comparison`	`true`
`biometric_policy.on_another_customer_repeated_face`	`REJECT`
`blacklist_policy.on_internal_face_blacklist_match`	`REJECT`
`blacklist_policy.on_global_face_blacklist_match`	`REJECT`

Transaction lifetime

integer

default:"1440"

How long the user has to complete the flow, counted from creation. Range 1–1440 (24 hours). Once it elapses the transaction moves to EXPIRED and the sdk_token stops working.

Match the TTL to how you deliver the flow. A verification the user starts immediately after tapping a button does not need 24 hours — an hour is plenty, and a short window limits how long a leaked token is useful. A link sent by email is the case that justifies a long TTL.

Webhook

string (HTTPS)

Where chmod notifies you once the decision exists. Must start with https://.

See Webhooks for the payload, the signature and how to verify it.

A complete example

A strict onboarding check for Argentina, matching against data you already hold:

{
  "transaction_ttl_minutes": 60,
  "webhook": {
    "url": "https://api.example.com/hooks/chmod"
  },
  "device_policy": {
    "on_compromised_device": "REJECT",
    "on_developer_mode": "WARN",
    "on_emulator": "REJECT",
    "on_vpn_or_proxy": "REJECT",
    "on_gps_mock_location": "REJECT",
    "on_gps_ip_location_mismatch": "WARN"
  },
  "document_policy": {
    "document_eligibility": {
      "filter_mode": "ALLOW",
      "target_documents": [
        { "country": "AR", "type": "NATIONAL_ID", "allow_expired": false },
        { "country": "AR", "type": "PASSPORT",    "allow_expired": false }
      ]
    },
    "data_matching": {
      "given_names": { "value": "Ana Maria", "similarity_min_score": 0.85 },
      "surnames":    { "value": "Perez",     "similarity_min_score": 0.85 },
      "gender": "F",
      "document_type": "NATIONAL_ID",
      "document_issuing_country": "AR",
      "document_number": "20123456",
      "date_of_birth": "1996-01-09"
    }
  },
  "biometric_policy": {
    "liveness_min_score": 0.9,
    "face_comparison_min_score": 0.9,
    "require_face_comparison": true,
    "expected_min_age": 18,
    "expected_max_age": 120
  },
  "blacklist_policy": {
    "on_internal_face_blacklist_match": "REJECT",
    "on_global_face_blacklist_match": "REJECT"
  }
}

Build the config on your server from your own records. If your mobile app can influence any of these values, a modified client can weaken its own verification.

Getting Started

Customers

Transactions

Transaction configuration

Results

Shape

Device policy

Document policy

Biometric policy

Blacklist policy

Which policies apply

Policy actions

Defaults

Transaction lifetime

Webhook

A complete example

​Shape

Device policy

Document policy

Biometric policy

Blacklist policy

​Which policies apply

​Policy actions

​Defaults

​Transaction lifetime

​Webhook

​A complete example

Shape

Which policies apply

Policy actions

Defaults

Transaction lifetime

Webhook

A complete example