Terminal API checkout always returns NOT_FOUND

Questions
, ,
1

I’m using Square Terminal with the Terminal API.
The device logs in correctly with a 6‑digit device code and shows AVAILABLE in the Devices API.
However, every CreateTerminalCheckout request returns NOT_FOUND and nothing appears on the terminal.
A sanitized Devices API response shows both Terminal API and Square POS applications:

{ "components": [
  { "type": "APPLICATION", "application_details": { "application_type": "TERMINAL_API", "version": "7.13" }},
  { "type": "APPLICATION", "application_details": { "application_type": "SQUARE_POS", "version": "7.10" }}
], "status": { "category": "AVAILABLE" }}

The checkout result is always:

{ "errors": [{ "code": "NOT_FOUND", "detail": "Resource not found." }] }

Could the terminal still be holding a POS session and preventing Terminal API from becoming active?
How can I clear the POS session or refresh the device state?

2

Hey @satoshi can you confirm you’re passing the device ID (and not the device code) into the CreateTerminalCheckout request? The device code logs you into the device but you’ll want the ID for the checkout request.

3

Thank you for your reply.
I tested it using a different method.

I would like to provide some additional information.
Sensitive details are omitted.

Here is the sequence of steps I followed:

• Retrieved my access token and location ID
• Used the access token and location ID to create a device code
• Logged out of the Square POS application on my Square Terminal
• Logged in to the Square Terminal using the device code
• Retrieved the device_id
• Created an order and retrieved the order_id

After that, I sent the following Terminal Checkout request:

curl https://connect.squareup.com/v2/terminals/checkouts \
-X POST \
-H ‘Square-Version: 2026-05-20’ \
-H ‘Authorization: Bearer MY_ACCESS_TOKEN’ \
-H ‘Content-Type: application/json’ \
-d ‘{
“idempotency_key”: “checkout-test-0001”,
“checkout”: {
“amount_money”: {
“amount”: 1,
“currency”: “JPY”
},
“order_id”: “Zp2o7CoOP2HxNkmg8VvxU83EkPPZY”,
“device_options”: {
“device_id”: “device:aaaaa”,
“show_itemized_cart”: true
}
}
}’

The response was:

{
“errors”: [
{
“code”: “BAD_REQUEST”,
“detail”: “Merchant not authorized for device_id=device:aaaaa”,
“category”: “INVALID_REQUEST_ERROR”
}
]
}

What should I do to resolve this issue?

4

Thank you.
I was able to resolve the issue.

Here is the change that fixed it:

In my Terminal Checkout request, I was sending:

“device_id”: “device:XXXX”

However, the Terminal API does not accept the “device:” prefix.
The correct value is the raw device ID:

“device_id”: “XXXX”

After removing the “device:” prefix, the checkout request worked correctly.