API Overview

The Payre API powers the @payre/pay SDK. You don't need to call it directly -- the SDK handles everything. This reference is for advanced use cases or building custom integrations.

Base URL: https://api.payre.dev

Core Endpoints

Endpoint	Method	Auth	Description
/v1/charges	POST	Developer secret key	Create a charge (SDK calls this)
/v1/balance	GET	Consumer API key	Check consumer balance
/v1/usage	GET	Consumer API key	Get charge history
/v1/top-up	POST	Consumer API key	Add credits to balance
/v1/earnings	GET	Developer secret key	Get developer earnings
/v1/tools	GET	Developer secret key	List registered tools
/v1/tools	POST	Developer secret key	Register a tool

Authentication

Two types of keys:

• Developer secret key (pyr_sk_live_xxx): Sent as Authorization: Bearer pyr_sk_live_xxx
• Consumer API key (pyr_ck_live_xxx): Sent as Authorization: Bearer pyr_ck_live_xxx

The API determines whether you're a developer or consumer based on the key prefix.

Errors

All errors return JSON with this shape:

{
  "error": "error_code",
  "message": "Human-readable description"
}

HTTP Status	Error Code	Meaning
401	unauthorized	Missing or invalid API key
402	insufficient_balance	Consumer balance too low
403	forbidden	Key doesn't have permission for this endpoint
404	not_found	Resource not found
500	internal_error	Server error

Rate Limits

• 1,000 requests per minute per key
• POST /v1/charges is optimized for high throughput (avg 0.5ms processing time)