Search devices

Browse API reference

GET/devicessearchDevices

Use this method to return a paginated list of devices associated with a merchant's API key or an ISV's API key.

Use the query parameters to filter the list of results that we return, for example, to search for devices by their model.

Our gateway returns the following information about each device in the list:

Unique identifier that we assigned to the device.
Serial number of the device.
Key serial identifier (KSI) of the device.
Device model or type of device.
Date that our gateway added the device to our systems.
Information about the last transaction that the device processed.

Parameters

Name	In	Type	Description
`before`	query	`string`	Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter.
`after`	query	`string`	Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter.
`limit`	query	`integer`	Limit the maximum number of results that we return for each page.
`active`	query	`boolean`	Filter by the device status. Send one of the following values: `true` – Return only active devices. `false` – Return only inactive devices.
`serialNumber`	query	`string`	Filter by the serial number of the device.
`ksi`	query	`string`	Filter by the key serial identifier (KSI) of the device.
`model`	query	`string`	Filter by the model or type of the device.

Responses

Successful request. Returns a list of devices associated with the API key.

200 OK · application/json

{
  "count": 0,
  "data": [],
  "hasMore": false,
  "limit": 10,
  "links": []
}

Response schema · 25 fields

countintegerrequired
Number of results we returned on this page. Note: This might not be the total number of results that match your query.
hasMorebooleanrequired
Indicates whether there is another page of results available.
limitintegerrequired
Maximum number of results that we return for each page.
linksobject[]
Reference links to navigate to the previous page of results or to the next page of results.
- hrefstringrequired
  URL of the target resource.
- methodstringrequired
  HTTP method that you need to use with the target resource.
- relstringrequired
  Indicates the relationship between the current resource and the target resource.
dataobject[]required
Array of device objects. Each object contains information about a device.
- createdDatestringdate-time
  Date and time that our gateway added the device to our systems. Our gateway returns this value in the ISO 8601 format.
- deactivatedDatestringdate-time
  Date and time that we deactivated the device. Our gateway returns this value in the ISO 8601 format. Note: If the device is active, our gateway doesn't return a value for deactivatedDate.
- deviceIdstring
  Unique identifier that we assigned to the device.
- deviceTypeobject
  Object that contains information about the device.
  - manufacturerstring
    Company that manufactured the device.
  - modelstring
    Model or type of the device.
- ksistring
  Key serial identifier (KSI) of the device.
- lastTransactionobject
  Object that contains information about the last transaction that the device processed.
  - dateTimestringdate-time
    Date and time that the processing terminal processed the last transaction. Our gateway returns this value in the ISO 8601 format.
  - orderIdstring
    Unique identifier that the merchant assigned to the order.
  - processingTerminalIdstring
    Unique identifier that we assigned to the processing terminal.
- linksobject[]
  - hrefstringrequired
    URL of the target resource.
  - methodstringrequired
    HTTP method that you need to use with the target resource.
  - relstringrequired
    Indicates the relationship between the current resource and the target resource.
- serialNumberstring
  Serial number of the device.
- tenderstring
  Payment methods accepted by the device. creditDebit – Credit and debit card payments. ebt – Electronic Benefit Transfer (EBT) payments.creditDebitebt

Invalid request

400 Bad Request · application/problem+json

{
  "detail": "One or more validation errors occurred, see error section for more info",
  "errors": [
    {
      "detail": "invalid date",
      "message": "Expected time, got '' for start_time",
      "parameter": "start_time"
    }
  ],
  "status": 400,
  "title": "Bad request",
  "type": "https://docs.payroc.com/api/errors#bad-request"
}

Response schema · 8 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- detailstring
  Short detail of the validation errors
- messagestring
  Error message
- parameterstring
  The parameter or field causing the issues
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Identity could not be verified

401 Unauthorized · application/problem+json

{
  "detail": "Your identity could not be verified",
  "status": 401,
  "title": "Not Authorized",
  "type": "https://docs.payroc.com/api/errors#not-authorized"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Do not have permissions to perform this action

403 Forbidden · application/problem+json

{
  "detail": "You do not have the required permissions to perform this action",
  "instance": "https://api.payroc.com/v1/exampleResource/3",
  "resource": "exampleResource",
  "status": 403,
  "title": "Forbidden",
  "type": "https://docs.payroc.com/api/errors#forbidden"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
instancestring
Resource path the action was attempted on
resourcestring
Resource the action was attempted on
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Not acceptable

406 Not Acceptable · application/problem+json

{
  "detail": "Resource does not support the representation requested",
  "status": 406,
  "title": "Not acceptable",
  "type": "https://docs.payroc.com/api/errors#not-acceptable"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

An error has occured

500 Internal Server Error · application/problem+json

{
  "detail": "We are unable to process your request at this time",
  "errors": [
    {
      "message": "Service offline"
    }
  ],
  "status": 500,
  "title": "Api error",
  "type": "https://docs.payroc.com/api/errors#api-error"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- messagestring
  Error message
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Used in workflows

run-a-sale-on-a-device