PayShards Partner API

Integrate PayShards to let your users spend their shard balance in your app. Three endpoints: check balance, deduct, refund. Shards are integers — 100 shards = $1.

Authentication

Every partner request must include your secret key in the x-api-key header. Keys are issued per partner and identify you for billing and rate limits. Never expose your key in client-side code.

x-api-key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Requests are rate limited per key. On limit you receive 429 rate_limited.

The purchase flow

Users buy shards on PayShards directly (you don’t handle payments). The balance they top up is the same balance your app spends from:

User signs in to PayShards and buys a pack — their balance is credited.
In your app, the user takes a paid action.
Your server calls POST /api/partner/deduct with the user’s id, the amount, and a unique reference.
If they have enough shards, the balance is debited and you proceed.
Need to reverse it? Call POST /api/partner/refund with the same (or a related) reference.

Idempotency: deduct and refund are idempotent on reference (scoped to your partner account). Retrying a request with the same reference never double-charges — you get the original result.

Endpoints

GET/api/partner/balance?userId=USER_ID

Returns a user’s current shard balance.

curl https://payshards.app/api/partner/balance?userId=u_123 \
  -H "x-api-key: $PAYSHARDS_KEY"

200 OK
{ "userId": "u_123", "balance": 1500 }

POST/api/partner/deduct

Atomically checks and deducts shards. Idempotent on reference.

curl -X POST https://payshards.app/api/partner/deduct \
  -H "x-api-key: $PAYSHARDS_KEY" \
  -H "content-type: application/json" \
  -d '{
    "userId": "u_123",
    "amount": 250,
    "reference": "order_abc_001",
    "description": "Pro export"
  }'

200 OK
{ "success": true, "newBalance": 1250, "idempotent": false }

402 Payment Required
{ "error": "insufficient_balance", "balance": 100 }

POST/api/partner/refund

Credits shards back to the user. Idempotent on reference.

curl -X POST https://payshards.app/api/partner/refund \
  -H "x-api-key: $PAYSHARDS_KEY" \
  -H "content-type: application/json" \
  -d '{
    "userId": "u_123",
    "amount": 250,
    "reference": "refund_abc_001"
  }'

200 OK
{ "success": true, "newBalance": 1500, "idempotent": false }

Error codes

Status	error	Meaning
400	`invalid_request`	Missing/invalid userId, amount, or reference.
401	`missing_api_key`	No `x-api-key` header.
401	`invalid_api_key`	Key not recognized.
402	`insufficient_balance`	User lacks shards; current `balance` returned.
403	`partner_inactive`	Partner account disabled.
404	`unknown_user`	No such user id.
429	`rate_limited`	Too many requests; back off and retry.

Amounts are always in whole shards (integers). Final copy and your issued API key will be provided during onboarding.