# Valet by Storey — full API reference

> Detailed companion to https://storeypos.com/llms.txt. Generated from the same source as https://storeypos.com/valet/docs and https://storeypos.com/openapi.json. All example values are fake.

Valet lets point-of-sale software you built run real card payments on a Storey terminal. Base URL: https://storeypos.com. All endpoints are POST and return JSON.

## Authentication

Every request sends two headers:
```
X-Valet-Key: vk_live_XXXXXXXXXXXXXXXXXXXXXXXX
X-Valet-Tag: vt_XXXXXXXXXXXXXXXXXXXX
```
- X-Valet-Key: per-location API key.
- X-Valet-Tag: per-station device ID (terminal or key-entry station).
Keep both server-side. Requests are rate limited (HTTP 429) and logged.

## Errors

Validation, auth and state errors return a non-200 status with:
```json
{
  "error": "No such Valet Ticket for this account."
}
```
Status codes: 400 invalid request or state, 401 bad credentials, 403 refunds disabled, 404 unknown ticket, 409 missing terminal/transaction on record, 429 rate limited, 500 server error.

Card declines are NOT HTTP errors: they return 200 with status "declined" (or "no_connection" / "error"), the processor's real reason in `error`, and `declineCategory`.

Decline categories (null otherwise):
- retain_card: 04, 07, 41, 43, 208, 209, 704, 767 — pick-up, lost or stolen card. Hold the card.
- suspected_fraud: 34, 129, 246
- invalid_cvv: N7, 82, E78, E122, 517, 954, 958
- invalid_card: 14, E06, VI, 540, 564, 605, 606
- insufficient_funds: 51
- expired_card: 54

## Create a sale

POST https://storeypos.com/api/public/valet/sale

Runs a card sale on the terminal behind the Valet Tag. referenceId is your idempotency key: repeating it returns the original result with replayed: true instead of charging twice. subtotal is required; taxAmount, tipAmount and shippingAmount default to 0; total must equal their sum (checked to the cent). Terminal stations only — a key-entry Valet Tag is rejected with 400 and must use POST /api/public/valet/session. A card number can never be sent over this API. A decline is still HTTP 200 with status "declined" and the processor's reason in error.

Auth: X-Valet-Key and X-Valet-Tag headers.

Parameters:
- referenceId (string, 1–64, required): your idempotency key.
- subtotal (number, required)
- taxAmount, tipAmount, shippingAmount (number, default 0)
- total (number > 0, required): must equal the sum above.
- cashDiscountPercent (number 0–25, optional): reserved.
- saveCard (boolean, optional) + customerRef (string, required if saveCard): keep card on file after approval; response then adds paymentMethod and saveCardError.

Example request:
```
curl -X POST https://storeypos.com/api/public/valet/sale \
  -H "X-Valet-Key: vk_live_XXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-Valet-Tag: vt_XXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"referenceId":"order-10482","subtotal":40,"taxAmount":2.5,"total":42.5}'
```

Example response (HTTP 200):
```json
{
  "storeyTransactionId": "vlt_9f2c8e1a4b3d",
  "referenceId": "order-10482",
  "status": "approved",
  "authCode": "0F3C21",
  "rrn": "042619005831",
  "card": {
    "brand": "visa",
    "last4": "4242",
    "entryMode": "contactless"
  },
  "amounts": {
    "subtotal": 40,
    "taxAmount": 2.5,
    "tipAmount": 0,
    "shippingAmount": 0,
    "total": 42.5
  },
  "refundedAmount": 0,
  "voidedAt": null,
  "receipt": {
    "batchNo": "12",
    "tranNo": "VC07",
    "responseText": "SUCCESS",
    "surchargeAmount": "0.00",
    "cashDiscount": "0.00",
    "cardholderName": "JANE SAMPLE",
    "terminal": "2319993484"
  },
  "error": null,
  "declineCategory": null,
  "channel": "terminal",
  "capturedAt": "2026-09-16T18:22:04Z",
  "createdAt": "2026-09-16T18:21:58Z",
  "replayed": false
}
```

Declined example:
```json
{
  "storeyTransactionId": "vlt_2b7e40c19d55",
  "referenceId": "order-10483",
  "status": "declined",
  "authCode": null,
  "rrn": "042619005831",
  "card": {
    "brand": "visa",
    "last4": "4242",
    "entryMode": "contactless"
  },
  "amounts": {
    "subtotal": 40,
    "taxAmount": 2.5,
    "tipAmount": 0,
    "shippingAmount": 0,
    "total": 42.5
  },
  "refundedAmount": 0,
  "voidedAt": null,
  "receipt": null,
  "error": "51 - INSUFFICIENT FUNDS",
  "declineCategory": "insufficient_funds",
  "channel": "terminal",
  "capturedAt": null,
  "createdAt": "2026-09-16T18:21:58Z",
  "replayed": false
}
```

## Refund a sale

POST https://storeypos.com/api/public/valet/sale/{storeyTransactionId}/refund

Refunds an approved sale on the same terminal that took it. Send amount for a partial refund, or omit the body to refund everything remaining. A refund beyond what remains is rejected before anything is sent to the terminal. Refunds can be disabled per location (403). The response carries refundedTotal and remaining.

Auth: X-Valet-Key and X-Valet-Tag headers.

Parameters:
- storeyTransactionId (path, required): the Valet Ticket from the sale.
- amount (number > 0, optional body): omit to refund everything remaining.

Example request:
```
curl -X POST https://storeypos.com/api/public/valet/sale/vlt_9f2c8e1a4b3d/refund \
  -H "X-Valet-Key: vk_live_XXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-Valet-Tag: vt_XXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"amount":42.5}'
```

Example response (HTTP 200):
```json
{
  "storeyTransactionId": "vlt_9f2c8e1a4b3d",
  "referenceId": "order-10482",
  "reversalId": "rvs_5d71b09c2e44",
  "kind": "refund",
  "amount": 42.5,
  "status": "approved",
  "authCode": "1A7D04",
  "rrn": "042619005831",
  "error": null,
  "declineCategory": null,
  "channel": "terminal",
  "refundedTotal": 42.5,
  "remaining": 0,
  "createdAt": "2026-09-17T09:14:31Z"
}
```

## Void a sale

POST https://storeypos.com/api/public/valet/sale/{storeyTransactionId}/void

No body. Cancels an approved sale the same day, before settlement. A settled or partially refunded sale cannot be voided — refund it instead (400).

Auth: X-Valet-Key and X-Valet-Tag headers.

Parameters:
- storeyTransactionId (path, required). No body.

Example request:
```
curl -X POST https://storeypos.com/api/public/valet/sale/vlt_9f2c8e1a4b3d/void \
  -H "X-Valet-Key: vk_live_XXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-Valet-Tag: vt_XXXXXXXXXXXXXXXXXXXX"
```

Example response (HTTP 200):
```json
{
  "storeyTransactionId": "vlt_9f2c8e1a4b3d",
  "referenceId": "order-10482",
  "reversalId": "rvs_8c20e5f71a93",
  "kind": "void",
  "amount": 42.5,
  "status": "approved",
  "authCode": null,
  "rrn": "042619005831",
  "error": null,
  "declineCategory": null,
  "channel": "terminal",
  "refundedTotal": 0,
  "remaining": 0,
  "createdAt": "2026-09-16T18:26:12Z"
}
```