Skip to content

Confirm a key authenticates

GET/v1/ping

The diagnostic to run after pasting a freshly issued key. It says which merchant the key speaks for and whether that merchant may currently sell.

Authentication — X-Client-Id and X-Api-Key.

Request

No parameters.

curl "$SHOTPAY_URL/v1/ping" \
  -H "X-Client-Id: $SHOTPAY_CLIENT_ID" \
  -H "X-Api-Key: $SHOTPAY_API_KEY"

$ping = Http::withHeaders([
    'X-Client-Id' => config('shotpay.client_id'),
    'X-Api-Key' => config('shotpay.api_key'),
])->get(config('shotpay.url').'/v1/ping')->json('data');

Response

200 OK

{
  "data": {
    "client_id": "mch_test_7fL2qXn4WbTzR9kD1sVyH6mCgA8eUpJ3",
    "legal_name": "Frontier Firearms LLC",
    "dba": "Frontier Range",
    "scopes": ["checkout:read", "checkout:write"],
    "key_prefix": "sk_test_a1b2",
    "layaway": { "available": true, "reason": null, "message": null }
  }
}
Field Type Notes
client_id string The merchant the key resolved to. Check it against the one you configured.
legal_name string
dba string or null
scopes array of string What this key is allowed to do.
key_prefix string The first 12 characters of the key, for telling two keys apart in a list.
layaway Layaway Availability Whether this merchant may sell right now.

A 200 here proves the pair authenticates. It does not promise the merchant can sell — read layaway.available for that.

Errors

Status When
401 The key is missing, unknown, or revoked.
403 The merchant is not cleared to transact.
429 Rate limited. Back off for Retry-After seconds.

See Error Handling.