Consumer Endpoints

Endpoints for consumers to manage their balance and usage.

GET /v1/balance

Check your current balance.

Auth: Consumer API key (Authorization: Bearer pyr_ck_live_xxx)

curl https://api.payre.dev/v1/balance \
  -H "Authorization: Bearer pyr_ck_live_xxx"

Response:

{
  "balance": 12.50,
  "consumerId": "cns_xxx"
}

GET /v1/usage

Get your charge history.

Auth: Consumer API key

curl https://api.payre.dev/v1/usage \
  -H "Authorization: Bearer pyr_ck_live_xxx"

Response:

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

POST /v1/top-up

Add credits to your balance.

Auth: Consumer API key

curl -X POST https://api.payre.dev/v1/top-up \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pyr_ck_live_xxx" \
  -d '{"amount": 10.00}'

Response:

{
  "topUpId": "tu_xxx",
  "amount": 10.00,
  "balance": 22.50,
  "status": "completed"
}

For Stripe Checkout integration (used by the Dashboard), see POST /v1/checkout.

POST /v1/checkout

Create a Stripe Checkout session for top-up.

Auth: Consumer API key

curl -X POST https://api.payre.dev/v1/checkout \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pyr_ck_live_xxx" \
  -d '{"amount": 10.00}'

Response:

{
  "sessionUrl": "https://checkout.stripe.com/...",
  "topUpId": "tu_xxx"
}

Redirect the consumer to sessionUrl. On successful payment, the balance is credited automatically via webhook.