Customer Device Management Schemas

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

Endpoints

Method	Endpoint	Description
POST	`/v1/bank/customer/device/link`	Link device to customer phrase
POST	`/v1/bank/customer/device/unlink`	Unlink device from customer
GET	`/v1/bank/devices/list`	List customer devices
POST	`/v1/customer/device/lookup`	Lookup 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

Field	Type	Required	Description
`customerId`	string	Yes	Customer identifier
`phrase`	string	Yes	Customer’s unique phrase
`deviceId`	string	Yes	Device 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

Field	Type	Required	Description
`customerId`	string	Yes	Customer identifier
`phrase`	string	Yes	Customer’s unique phrase
`deviceId`	string	Yes	Device 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

Parameter	Type	Required	Description
`page`	number	No	Page number for pagination (default: 1)
`limit`	number	No	Number of results per page (default: 20)
`search`	string	No	Search by customer or device information
`sortBy`	string	No	Field to sort by
`sortOrder`	string	No	Sort 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

Field	Type	Description
`deviceId`	string	Device identifier
`customerId`	string	Associated customer ID
`phrase`	string	Customer’s unique phrase
`linkedAt`	string	Device linking timestamp

POST /v1/customer/device/lookup

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

Request Body

{
  "deviceId": "string"
}

Request Schema

Field	Type	Required	Description
`deviceId`	string	Yes	Device 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

Field	Type	Description
`deviceId`	string	Device identifier
`phrase`	string	Customer’s lookup ID
`customerId`	string	Customer identifier
`bankId`	string	Bank identifier

Device Management Use Cases

Device Linking Process

Customer registers device with bank app
Bank captures device fingerprint/ID
Bank links device to customer’s unique phrase
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"
}

Account Operations

Customer Management

Customer Device Management

Customer Billing & Subscriptions

Transaction Management

Balance & Financial Operations

schemas

Customer Device Management Schemas

Endpoints

POST /v1/bank/customer/device/link

Request Body

Request Schema

Response Schema

POST /v1/bank/customer/device/unlink

Request Body

Request Schema

Response Schema

GET /v1/bank/devices/list

Query Parameters

Response Schema

Device List Schema

POST /v1/customer/device/lookup

Request Body

Request Schema

Response Schema

Device Lookup Response Schema

Device Management Use Cases

Device Linking Process

Security Considerations

Error Responses

400 Bad Request

404 Not Found

409 Conflict

​Customer Device Management Schemas

​Endpoints

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

​Request Body

​Request Schema

​Response Schema

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

​Request Body

​Request Schema

​Response Schema

​GET /v1/bank/devices/list

​Query Parameters

​Response Schema

​Device List Schema

​POST /v1/customer/device/lookup

​Request Body

​Request Schema

​Response Schema

​Device Lookup Response Schema

​Device Management Use Cases

​Device Linking Process

​Security Considerations

​Error Responses

​400 Bad Request

​404 Not Found

​409 Conflict

Customer Device Management Schemas

Endpoints

POST /v1/bank/customer/device/link

Request Body

Request Schema

Response Schema

POST /v1/bank/customer/device/unlink

Request Body

Request Schema

Response Schema

GET /v1/bank/devices/list

Query Parameters

Response Schema

Device List Schema

POST /v1/customer/device/lookup

Request Body

Request Schema

Response Schema

Device Lookup Response Schema

Device Management Use Cases

Device Linking Process

Security Considerations

Error Responses

400 Bad Request

404 Not Found

409 Conflict