Charges

The charge endpoint is the core of Payre. The @payre/pay SDK calls this automatically -- you only need this reference if you're building a custom integration.

POST /v1/charges

Create a charge. Validates the consumer's key, checks balance, deducts the amount, and returns a signed receipt.

Auth: Developer secret key (Authorization: Bearer pyr_sk_live_xxx)

curl -X POST https://api.payre.dev/v1/charges \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pyr_sk_live_xxx" \
  -d '{
    "apiKey": "pyr_ck_live_xxx",
    "tool": "search",
    "amount": 0.005
  }'

Request Body:

Field	Type	Required	Description
apiKey	string	Yes	Consumer's API key (pyr_ck_live_xxx)
tool	string	Yes	Tool name being charged for
amount	number	Yes	Amount in USD (e.g. 0.005)

Response 200:

{
  "chargeId": "chg_abc123",
  "receipt": "hmac_sha256_signature_here",
  "balance": 4.995
}

Error Responses:

Status	Code	When
401	unauthorized	Invalid developer secret key
401	invalid_api_key	Invalid consumer API key
402	insufficient_balance	Consumer balance < amount

Performance: Average processing time 0.5ms, P99 < 4ms.

GET /v1/charges

List charges for the authenticated developer.

curl https://api.payre.dev/v1/charges \
  -H "Authorization: Bearer pyr_sk_live_xxx"

Response:

{
  "charges": [
    {
      "id": "chg_abc123",
      "tool": "search",
      "amount": 0.005,
      "consumerId": "cns_xxx",
      "receipt": "hmac_sha256_...",
      "createdAt": "2026-04-04T12:00:00Z"
    }
  ]
}