Retrieve the calling terminal

GET

/v1/terminal/me

const url = 'https://terminal.api.example.com/v1/terminal/me';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://terminal.api.example.com/v1/terminal/me

Called by a paired terminal, over mutual TLS with its certificate, to learn who that certificate says it is: the terminal, and the merchant and store it is assigned to. The certificate is checked on this call, so a revoked, replaced or expired one is refused here as on any terminal call.

Authorizations

TerminalCertificate

Responses

200

The terminal. Sent with Cache-Control: no-store.

application/json

object

object

string

Allowed value: terminal

The terminal’s id, as its pairing answered it.

string

tenant_id

The tenant of the merchant the terminal is assigned to.

string

merchant_id

The merchant the terminal is assigned to.

string

store_label

The store it is assigned to, as the operations team labelled it. Empty when none was given.

string

certificate

The certificate this call presented.

object

serial_number

Its serial number, in lower case hex.

string

expires_at

When it expires, as a Unix timestamp.

integer

livemode

Always true. A terminal is a live device; there are no test terminals.

boolean

Example

{
  "object": "terminal",
  "id": "3f6c2a9e-8b41-4d7a-9e25-0c1b7d4f8a63",
  "store_label": "Front counter",
  "certificate": {
    "serial_number": "5e1f0c9a3b7d2e48",
    "expires_at": 1790999400
  },
  "livemode": true
}

401

authentication_failure with terminal_credential_refused: the certificate does not count, because it is unknown, was revoked or replaced, or has expired, or the terminal was moved to another store or merchant since it was paired. Pair the terminal again. See Pairing a terminal.

application/json

object

error

required

object

type

required

string

Allowed values: validation_failure authentication_failure authorization_failure not_found conflict timeout_or_in_progress policy_rejection invariant_violation rate_limited dependency_failure

code

required

A stable name for this refusal. Branch on this, never on message.

string

message

required

For the developer reading a log. May be reworded.

string

param

required

The field or parameter at fault, when there is one.

string | null

request_id

required

string | null

Example

{
  "error": {
    "type": "authentication_failure",
    "code": "terminal_credential_refused",
    "message": "This terminal's certificate is not honoured. Pair the terminal again with a new Pairing Code.",
    "param": null,
    "request_id": "req_7a2e91c04b5d"
  }
}

503

dependency_failure with service_unavailable: something on our side, or a payment network behind it, did not answer. This call only reads, so nothing was changed; retry.

application/json

object

error

required

object

type

required

string

Allowed values: validation_failure authentication_failure authorization_failure not_found conflict timeout_or_in_progress policy_rejection invariant_violation rate_limited dependency_failure

code

required

A stable name for this refusal. Branch on this, never on message.

string

message

required

For the developer reading a log. May be reworded.

string

param

required

The field or parameter at fault, when there is one.

string | null

request_id

required

string | null

Example

{
  "error": {
    "type": "validation_failure"
  }
}