Personalisation API

The personalisation of a terminal is the initial setup routine that transfers all needed cryptographic and other assets to the device. We offer two ways of personalisation :

• Direct TID + Password entry via our UI
• API approach via a QR code

QR Code Personalisation

tip

A QR code generator for development has been created here: QR-Code-Generator

The scanned QR code does have two layers. First there is an outer layer which defines the request type, compression and encoding. It is defined by this JSON Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "properties": {
        "con": {
            "type": "string",
            "$comment": "Content of the inner payload. Mandatory field."
        },
        "com": {
            "enum": ["zlib", "none"],
            "default": "zlib",
            "$comment": "Compression method for content. Can be left blank."
        },
        "enc": {
            "enum": ["base64", "none"],
            "default": "base64",
            "$comment": "Encoding method for encoding. Can be left blank."
        },
        "typ": {
            "enum": ["tran", "pers"],
            "default": "tran",
            "$comment": "Defines the type of the request. Either a transaction (default) or personalisation request."
        }
    },
    "required": [
        "con"
    ]
}

Inside of the con variable the content of the request is placed. The format of the content is defined in this JSON Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "type": {
      "enum": [
        "tidAndPasswordUiInput",
        "automatedEnrolment",
        "tidAndOtp"
      ],
      "default": "tidAndPasswordUiInput",
      "$comment": "Type of personalisation. Can be left blank."
    },
    "environment": {
      "$ref": "#/definitions/environment",
      "$comment": "Fields that identify the environment. If empty, the app's default environment will be used."
    },
    "clientId": {
      "$ref": "#/definitions/clientId",
      "$comment": "Fields that identify the merchant. Different for every personalisation type."
    },
    "options": {
      "$ref": "#/definitions/options",
      "$comment": "Options for the customization of the terminal."
    }
  },
  "definitions": {
    "clientId": {
      "oneOf": [
        {
          "title": "automatedEnrolment",
          "type": "object",
          "properties": {
            "externalDeviceId": { "type": "string" },
            "token": { "type": "string" }
          },
          "required": ["externalDeviceId", "token"],
          "additionalProperties": false
        },
        {
          "title": "tidAndOtp",
          "type": "object",
          "properties": {
            "terminalId": { "type": "string" },
            "otpServiceType": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": ["SMS", "MAIL", "NONE"]
              }
            }
          },
          "required": ["terminalId"],
          "additionalProperties": false
        }
      ]
    },
    "environment": {
      "type": "object",
      "properties": {
        "apiKey": {
          "type": "string",
          "description": "API key"
        },
        "apiSecret": {
          "type": "string",
          "description": "API secret"
        }
      },
      "required": ["apiKey", "apiSecret"],
      "additionalProperties": false
    },
    "options": {
      "type": "object",
      "properties": {
        "additionalData": {
          "type": "object",
          "patternProperties": {
            ".*": { "type": "string" }
          },
          "additionalProperties": false,
          "description": "Free-form additional custom key-value pairs."
        },
        "screenOrientation": {
          "type": "string",
          "enum": ["PORTRAIT", "LANDSCAPE", "NONE"],
          "description": "Orientation of the screen."
        },
        "nfcImagePosition": {
          "type": "string",
          "enum": [
            "NO_IMAGE",
            "POSITION_RIGHT",
            "POSITION_LEFT",
            "POSITION_DOWN",
            "POSITION_UP"
          ],
          "description": "Position of the NFC image."
        },
        "secondaryDisplayEnabled": {
          "type": "boolean",
          "description": "Whether the secondary display is enabled."
        },
        "attestationProvider": {
          "type": "string",
          "enum": ["GOOGLE_PLAY_INTEGRITY", "ZIMPERIUM_ZDEFEND"],
          "description": "Attestation provider type."
        },
        "nfcReaderPlatformSoundsEnabled": {
          "type": "boolean",
          "description": "Enable or disable NFC reader platform sounds."
        },
        "appTheme": {
          "type": "string",
          "description": "Theme applied to the app."
        },
        "terminalTheme": {
          "type": "string",
          "enum": [
            "NONE",
            "BLUE",
            "DARK_BLUE",
            "WHITE_BLACK",
            "DARK_GRAY",
            "DARK_GRAY_ORANGE"
          ],
          "description": "Theme applied to the terminal UI."
        },
        "deepLinkApiEnabled": {
          "type": "boolean",
          "description": "Whether deep link API support is enabled."
        }
      },
      "additionalProperties": false
    }
  }
}