Skip to content

Verify a session from your server

GET/v1/checkout-sessions/{id}

Asks what happened to a session you opened. This is the call that settles an order: the one place a store learns, from a source it can trust, whether a plan was actually signed.

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

Returns the full shape session create returned, including order_reference and checkout_url.

Call it from your session.completed webhook handler and from your return_url page — the same function in both places. See How your store finds out. It is also what to reach for on a support ticket, a nightly reconciliation job, or a delivery you suspect you missed.

Request

Parameter In Notes
id path The session's public token, as returned by session create. 
curl "$SHOTPAY_URL/v1/checkout-sessions/cs_9Xk2mQpR7vLzT4hB1nWsY6dF3jCgA8eU" \
  -H "X-Client-Id: $SHOTPAY_CLIENT_ID" \
  -H "X-Api-Key: $SHOTPAY_API_KEY"

$session = Http::withHeaders([
    'X-Client-Id' => config('shotpay.client_id'),
    'X-Api-Key' => config('shotpay.api_key'),
])->get(config('shotpay.url')."/v1/checkout-sessions/{$token}")->json('data');

Response

200 OK — a Checkout Session.

{
  "data": {
    "id": "cs_9Xk2mQpR7vLzT4hB1nWsY6dF3jCgA8eU",
    "status": "completed",
    "order_reference": "ORD-1001",
    "total_amount": 49999,
    "down_payment_amount": 12500,
    "down_payment_percentage": 25,
    "checkout_url": "https://secure.shotpay.com/checkout/cs_9Xk2mQpR7vLzT4hB1nWsY6dF3jCgA8eU",
    "return_url": "https://store.example/checkout/complete",
    "cancel_url": "https://store.example/cart",
    "expires_at": "2026-08-12T15:30:00+00:00",
    "created_at": "2026-08-12T14:30:00+00:00",
    "metadata": { "order_id": "1001", "warehouse": "SEA-2" }
  }
}

Branch on the status this returns

status is the effective status. A session past its deadline reads as expired here whether or not that has been written down yet, so this value is the one to trust — never a status you cached earlier.

A completed session means the customer accepted the plan and the down payment was collected. The plan itself — the schedule, what is paid, what is left — is carried on the contract.* webhook events.

Errors

Status When
401 The key is missing, unknown, revoked, or paired with a client id from the other mode.
403 The merchant is not cleared to transact.
404 No session of yours has that token.
429 Rate limited. Back off for Retry-After seconds.

A token belonging to another merchant answers 404 rather than 403, and so does one of your own from the other mode.

See Error Handling.