Terminal API device code sign-in always fails on Square Terminal in Japan (production)

Questions
1

Hello,

I am a seller in Japan building my own POS app that uses the Terminal API.
I cannot pair my Square Terminal using a device code, and I would like help.

What I did:

  1. Created a device code with CreateDeviceCode (product_type: TERMINAL_API)
    in PRODUCTION, using my production access token and my own location.
  2. The code appears in Seller Dashboard > Devices > Device codes
    under the correct location, so the code was created on the right account.
  3. On the Square Terminal, I chose “Sign in with device code”
    and entered the code before it expired.

Result:
The Terminal always shows “Sign in failed / The device code is incorrect”.
The code then shows as expired in the dashboard.

What I already tried:

  • Several new device codes, each entered within the time limit
  • Factory reset of the Terminal, then tried again (same error)
  • Signing in with email and password works fine (same business account)
  • Terminal OS updated to the latest version

Device info:

  • Square Terminal (1st Gen, v2), app version 7.26, OS 5.67.0105
  • Country: Japan (JP / JPY), location status ACTIVE

Questions:

  1. What could cause a valid production Terminal API device code to be rejected?
  2. Does a Japanese seller account need any extra setting or approval
    to use device codes for the Terminal API?

Thank you for your help.

3

Can you confirm which value you’re entering on the Terminal? For Terminal API pairing, the Terminal should receive the device_code.code value returned by CreateDeviceCode, not the device code object id, and not a Devices API device_id. The device_id is only used later, after

Terminal API pairing codes should be 6 characters. If the code you’re entering is longer, or was generated from Dashboard rather than CreateDeviceCode with product_type: TERMINAL_API, it’s probably a POS/Register device code rather than a Terminal API code.

Japan should not require a separate approval just to use Terminal API device codes, assuming the production token, seller account, location, and hardware are all in the same production JP account.

4

Thank you for your reply.

Yes, I am entering the 6-character device_code.code value
returned by CreateDeviceCode (product_type: TERMINAL_API).
I am not using the id or any device_id.
The codes were created by the API, not from the Dashboard.
Examples of codes I tried: DSCCYW, MKZCTB, TBYJTT
(all 6 characters, entered before pair_by, all now expired).

The token, seller account, location and the Terminal are all
in the same production JP account. Email/password sign-in on
the Terminal works with this account.

On the Terminal I choose “Sign in” > “Use a device code”
and type the 6 characters. It always says the code is incorrect.

Is there anything else I should check on the Terminal side,
or could you look up these codes on your side?
If you need the device code IDs, I can share them.

Thank you.

5

Thanks for the detail! The codes themselves look correct.

On the Terminal, the Terminal API pairing entry is the Device Code button on the Sign in Page itself, not an option you reach after tapping “Sign in.” If you go through the “Sign in” flow first, that code field belongs to the Square Point of Sale sign-in, which only accepts Dashboard-generated REGISTER codes (12 characters). A valid 6-character Terminal API code will be rejected there as “incorrect.” Since you factory reset the device, it’s easy to land in the POS onboarding flow instead.

Please try: from the Sign in Page, tap Device Code directly (don’t tap “Sign in” / email path first), then enter the 6 characters.

Also confirm the timing-- the device code must be used within 5 minutes of creation, which can be shorter than what pair_by suggests if there’s any delay getting the code to the person at the Terminal. Generate a code and enter it immediately.

If both of those check out, please share one device code id plus the approximate timestamp of a failed attempt and I’ll trace it on our side.

8

Thank you. I tried again following both points, and it still fails. I will post the details in my next reply.

9

Here is the path I followed on the Terminal (after factory reset, not signed in):

  1. Welcome screen. It only shows “Create account”, “Sign in” and a gear icon. There is no Device Code button here.
  2. I tapped “Sign in”. The Sign in page appears, with an email/phone field, “Continue”, “Use a device code” and “Sign in with another device”.
  3. I tapped “Use a device code” directly, without entering an email. The “Sign in with device code” screen appears.
  4. I entered the 6-character code and tapped “Sign in”.

Result: “Sign in failed. The device code is incorrect.”

The code was entered about 22 seconds after it was created, so well within 5 minutes.

10

Details of the failed attempt:

Device code id: 9QQWSJRF5FR7V
Environment: production
Product type: TERMINAL_API
Code created at 03:03:22 UTC on October 2, 2026
Failed attempt at about 03:03:44 UTC (12:03:44 JST)
Device: Square Terminal 1st Gen v2, app version 7.26, OS 5.67.0105, language Japanese

Is there a different entry point for Terminal API pairing on this app version that I am missing? If not, could you please trace this attempt on your side? I can share screenshots of each screen if that helps.

11

Update: it is now working. The Terminal paired successfully and my POS shows the device as paired.

The likely cause was on my side. The Terminal keyboard was in Japanese input mode, so the code was typed in full-width letters instead of normal half-width letters. When I typed the same kind of code in half-width letters, it paired at once.

The entry point was the same as before: Sign in, then Use a device code. Thank you very much for your help.