Skip to content
Developer portal

Renew the terminal's certificate

POST
/v1/terminal/certificate_renewals
curl --request POST \
  --url https://terminal.api.example.com/v1/terminal/certificate_renewals \
  --header 'Content-Type: application/json' \
  --data '{ "csr": "example" }'

Called by a paired terminal, over mutual TLS with its current certificate, for a new certificate for the same key, with no Pairing Code. The current certificate is checked as on any terminal call, so one that was revoked, replaced or has expired cannot be renewed: the terminal is paired again.

Both certificates are honoured until the new one is first used; from then on only the new one is. A retry after a lost answer, with the old certificate and the same key, returns the same new certificate. See Renewing a certificate.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
csr
required

A PKCS#10 certificate signing request in PEM, signed by the key the terminal was paired with. Its subject is ignored. No attestation chain is needed.

string
/\S/
Examplegenerated
{
  "csr": "example"
}

Responses

Section titled “Responses”

201

Section titled “201”

The new certificate. Sent with Cache-Control: no-store.

Media typeapplication/json
object
object
required
string
Allowed value: terminal_certificate_renewal
terminal_id
required

The id of the terminal the certificate is for, the one the current certificate names.

string
certificate
required

The terminal’s new client certificate, in PEM, for the same key. Valid for up to 7 days: expires_at says when it ends. Once it is first used, the certificate it replaces is refused.

string
chain
required

The certificates above it, in PEM, its issuer first.

string
expires_at
required

When the new certificate expires, as a Unix timestamp.

integer
livemode
required

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

boolean
Example
{
  "object": "terminal_certificate_renewal",
  "livemode": true,
  "terminal_id": "3f6c2a9e-8b41-4d7a-9e25-0c1b7d4f8a63",
  "certificate": "-----BEGIN CERTIFICATE-----\nMIIB9TCCAZugAwIBAgIU...\n-----END CERTIFICATE-----\n",
  "chain": "-----BEGIN CERTIFICATE-----\nMIIBvjCCAWSgAwIBAgIU...\n-----END CERTIFICATE-----\n",
  "expires_at": 1791604200
}

400

Section titled “400”

validation_failure with invalid_parameter and param csr: the CSR is missing, is not a PEM certificate signing request, or is not signed by the key this terminal was paired with. A new key needs a new Pairing Code. Also the codes any /v1 call can get for a body that is not JSON.

Media typeapplication/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",
    "code": "invalid_parameter",
    "message": "csr must be signed by the key this terminal was paired with. A new key needs a new Pairing Code.",
    "param": "csr",
    "request_id": "req_2b8d4f6a1c3e"
  }
}

401

Section titled “401”

authentication_failure with terminal_credential_refused: the current certificate does not count, so it cannot be renewed. Pair the terminal again. See Pairing a terminal.

Media typeapplication/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"
  }
}

503

Section titled “503”

dependency_failure with service_unavailable: the platform did not answer, or failed part-way. Whether a new certificate was made is not known. Retry the same request, with the old certificate and the same key: if one was made you get that one back, not a second, and the old certificate stays honoured until the new one is first used.

Media typeapplication/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"
  }
}