GET /invoice/{guid}

Returns the current state of a single invoice. Used both by merchant dashboards (with auth) and by checkout pages on the buyer side (without auth).

Request

GET /invoice/29f3b386-7c4a-4f6e-9d2b-1a8e3c5f7d09

The session-key headers are optional. When present they must validate — useful when the client wants to receive an encrypted response. When absent, the endpoint serves the public invoice record without checking identity, so the same call works as the data source for the hosted checkout page.

For session-signed reads, the signed payload is the request URI (path + query) so a captured signature can't be replayed against a different guid:

sess:{nonce}:{sha256("/invoice/{guid}")}

Response

200 OK

{
  "guid": "29f3b386-7c4a-4f6e-9d2b-1a8e3c5f7d09",
  "createdAt": 1730393820,
  "deadline": 1730480220,
  "status": "partialPaid",
  "value": "100",
  "token": "1:0xdac17f958d2ee523a2206206994597c13d831ec7",
  "chainId": 1,
  "data": {},
  "description": "Hosting plan XLarge",
  "address": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
  "owner": "0xMerchantAddress…",
  "paidAmount": "42.5",
  "payments": [
    {
      "txHash": "0x…",
      "logIndex": 0,
      "chainId": "1",
      "token": "0xdac17f958d2ee523a2206206994597c13d831ec7",
      "from": "0xfeedbeef…",
      "amount": "42.5",
      "vsValue": 42.5,
      "timestamp": 1730393900
    }
  ],
  "acceptedTokens": ["1:0xdac17f958d2ee523a2206206994597c13d831ec7"]
}

status is refreshed on read: an invoice past its deadline with insufficient paidAmount flips to expired lazily on the first GET after the cutoff.

Errors

Status	Body	Cause
404	invoice {guid} not found	The guid does not exist or has been purged.
401	session signature: ...	Auth headers were sent but the signature couldn't be verified.