Credits and Payments

Overview

Credits pay for production SMS segments. Billing endpoints use the authenticated dashboard session, not an API key. Payment operations additionally require approved production access. Credit mutations are ledger-backed; a successful payment webhook is applied idempotently and cannot credit an account twice.

GET /v1/credits/balance

curl https://api.bar9.dev/v1/credits/balance \
  --cookie "$BAR9_SESSION_COOKIE"

Returns 200 OK with the current owner-scoped balance in the standard { "ok": true, "data": ... } envelope. A missing or expired session returns 401.

POST /v1/payments/checkouts

curl https://api.bar9.dev/v1/payments/checkouts \
  --cookie "$BAR9_SESSION_COOKIE" \
  -H 'Content-Type: application/json' \
  -d '{"amount":2000}'

Creates a Chargily checkout for the authenticated account and returns 201 Created. The response contains the payment identifier, checkout URL, amount, currency, provider, status, creation timestamp, and nullable payment timestamp. amount must be a positive integer; currency defaults to DZD, the only currently supported currency. Production access must be approved; otherwise the route returns 403. Invalid input returns 400, and provider failures return 502 or 503 without adding credits.

GET /v1/payments

curl 'https://api.bar9.dev/v1/payments?page=1&per_page=25' \
  --cookie "$BAR9_SESSION_COOKIE"

Lists only the authenticated account's payments, newest first. page defaults to 1 and per_page to 25, with a maximum of 100. Each row contains its amount, currency, provider, status (pending, paid, or failed), checkout URL, creation timestamp, and nullable payment timestamp. The response uses the standard list envelope with pagination.limit, offset, total, has_more, and next_offset.

GET /v1/payments/:payment_id/receipt

Downloads a standalone HTML record for an owner-scoped payment. Pending and failed checkouts remain downloadable for audit purposes. Once a signed Chargily webhook commits the payment and its credit-ledger entry, the same URL returns a paid receipt with the provider references and paid timestamp. The response uses Content-Disposition: attachment; another account receives 404.

Payment completion

The checkout URL sends the customer to Chargily. Bar9 changes the local payment to paid and creates its credit-ledger entry only after a correctly signed Chargily webhook. Repeated delivery of the same event is idempotent. Treat the browser return URL as navigation only; poll GET /v1/payments and GET /v1/credits/balance for authoritative state.

Common errors

Errors use { "ok": false, "error": { "code", "message" } }.