Skip to main content

​
Customer Device Management Schemas

API endpoints for linking and managing customer devices for seamless merchant interactions.

​
Endpoints

MethodEndpointDescription
POST/v1/bank/customer/device/linkLink device to customer phrase
POST/v1/bank/customer/device/unlinkUnlink device from customer
GET/v1/bank/devices/listList customer devices
POST/v1/customer/device/lookupLookup customer by device

​
POST /v1/bank/customer/device/link

Link a customer’s device to their unique phrase for merchant recognition.

​
Request Body

{
  "customerId": "string",
  "phrase": "string",
  "deviceId": "string"
}

​
Request Schema

FieldTypeRequiredDescription
customerIdstringYesCustomer identifier
phrasestringYesCustomer’s unique phrase
deviceIdstringYesDevice identifier to link

​
Response Schema

{
  "statusCode": 200,
  "success": true,
  "message": "Device linked successfully"
}

​
POST /v1/bank/customer/device/unlink

Remove the link between a customer’s device and their phrase.

​
Request Body

{
  "customerId": "string",
  "phrase": "string",
  "deviceId": "string"
}

​
Request Schema

FieldTypeRequiredDescription
customerIdstringYesCustomer identifier
phrasestringYesCustomer’s unique phrase
deviceIdstringYesDevice identifier to unlink

​
Response Schema

{
  "statusCode": 200,
  "success": true,
  "message": "Device unlinked successfully"
}

​
GET /v1/bank/devices/list

Retrieve list of customer devices linked to your bank.

​
Query Parameters

ParameterTypeRequiredDescription
pagenumberNoPage number for pagination (default: 1)
limitnumberNoNumber of results per page (default: 20)
searchstringNoSearch by customer or device information
sortBystringNoField to sort by
sortOrderstringNoSort order (asc or desc)

​
Response Schema

{
  "statusCode": 200,
  "success": true,
  "data": {
    "devices": [
      {
        "deviceId": "string",
        "customerId": "string",
        "phrase": "string",
        "linkedAt": "string"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }
}

​
Device List Schema

FieldTypeDescription
deviceIdstringDevice identifier
customerIdstringAssociated customer ID
phrasestringCustomer’s unique phrase
linkedAtstringDevice linking timestamp

​
POST /v1/customer/device/lookup

Lookup customer information using device identifier (used by merchants).

​
Request Body

{
  "deviceId": "string"
}

​
Request Schema

FieldTypeRequiredDescription
deviceIdstringYesDevice identifier for lookup

​
Response Schema

{
  "statusCode": 200,
  "success": true,
  "message": "Device lookup successful",
  "data": {
    "deviceId": "string",
    "phrase": "string",
    "customerId": "string",
    "bankId": "string"
  }
}

​
Device Lookup Response Schema

FieldTypeDescription
deviceIdstringDevice identifier
phrasestringCustomer’s lookup phrase
customerIdstringCustomer identifier
bankIdstringBank identifier

​
Device Management Use Cases

​
Device Linking Process

  1. Customer registers device with bank app
  2. Bank captures device fingerprint/ID
  3. Bank links device to customer’s unique phrase
  4. Merchants can now identify customer by device

​
Security Considerations

  • Device IDs are anonymized and encrypted
  • No sensitive customer data exposed to merchants
  • Phrase associations are securely stored
  • Regular security monitoring for suspicious activity

​
Error Responses

​
400 Bad Request

{
  "statusCode": 400,
  "success": false,
  "message": "Invalid device ID format"
}

​
404 Not Found

{
  "statusCode": 404,
  "success": false,
  "message": "Device not found in system"
}

​
409 Conflict

{
  "statusCode": 409,
  "success": false,
  "message": "Device already linked to another customer"
}