Merchant Device Registration

Register or update a merchant’s device information. This endpoint is typically called during transaction requests to maintain device tracking and security measures for point-of-sale systems.

API Endpoint

URL: /v1/merchant-device
Method: POST

Request Body

The request must include a JSON payload with the device details:


{
  "merchantId": "string",
  "userId": "string",
  "id": "string",
  "deviceId": "string",
  "fingerprint": "string",
  "sessionKey": "string",
  "name": "string",
  "type": "string",
  "source": "string",
  "host": "string",
  "userAgent": "string",
  "remoteIP": "string",
  "status": "ACTIVE",
  "lastLoginAttempt": 1734167723000,
  "lastLoginSuccess": true,
  "lastSeen": 1734167723000,
  "firstSeen": 1734167723000,
}

Successful Response Format

A successful response will return a JSON object with the status of the registration:


{
  "status": "string",
  "message": "string"
}

Error Response Format

See the Error Reference section for a full description of API errors. All API errors follow a consistent JSON structure:


{
  "error": {
    "type": "ERROR_TYPE",
    "message": "Human-readable error description",
    "details": ["Additional error details (optional)"]
  },
  "timestamp": 1755602195137
}

In the case of a validation error, the format will be as follows:


{
    "error": {
        "type": "VALIDATION_ERROR",
        "message": "Request validation failed",
        "details": [
            "/amount: Expected number to be greater or equal to 0"
        ]
    },
    "timestamp": 1755602195137
}

Schema

Request Schema


{
  "type": "object",
  "properties": {
    "merchantId": {
      "type": "string"
    },
    "userId": {
      "type": "string"
    },
    "id": {
      "type": "string"
    },
    "deviceId": {
      "type": "string"
    },
    "fingerprint": {
      "type": "string"
    },
    "sessionKey": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "source": {
      "type": "string"
    },
    "host": {
      "type": "string"
    },
    "userAgent": {
      "type": "string"
    },
    "remoteIP": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": ["ACTIVE", "BLOCKED", "SUSPICIOUS"]
    },
    "lastLoginAttempt": {
      "type": "number"
    },
    "lastLoginSuccess": {
      "type": "boolean"
    },
    "lastSeen": {
      "type": "number"
    },
    "firstSeen": {
      "type": "number"
    },
    }
  },
  "required": ["merchantId", "id"]
}

Device Fields

Property	Type	Required	Description
id	string	No	Unique identifier for the device entity
deviceId	string	No	Unique device identifier
userId	string	Yes	User identifier
fingerprint	string	No	Unique device fingerprint identifier
sessionKey	string	No	Unique session identifier
name	string	No	Device name
type	string	No	Device type (e.g., mobile, desktop)
source	string	No	Fingerprinting provider (e.g., SHIELD, FingerprintJS)
host	string	No	Hostname of the device
userAgent	string	No	User agent of the device
remoteIP	string	No	Remote IP address of the device
status	string	No	Device status (ACTIVE, BLOCKED, SUSPICIOUS)
lastLoginAttempt	number	No	Unix timestamp in milliseconds of last login attempt
lastLoginSuccess	boolean	No	Whether the last login attempt succeeded
lastSeen	number	No	Unix timestamp in milliseconds
firstSeen	number	No	Unix timestamp in milliseconds

Response Schema


{
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "required": ["status", "message"]
}