Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.borga.is/llms.txt

Use this file to discover all available pages before exploring further.

Borga’s API is REST over HTTPS. Request and response bodies are JSON. Every request authenticates with an API key passed as a Bearer token. The base URL for all endpoints is https://api.borga.is.

​
Base URL

https://api.borga.is
All endpoints are versioned under /v1/. A full endpoint path looks like https://api.borga.is/v1/payments.

​
Authentication

Pass your secret API key in the Authorization header as a Bearer token. Most endpoints also require an X-Merchant-Id header identifying the merchant account. 
Authorization: Bearer sk_live_…
X-Merchant-Id: mer_xxx
Use sk_test_… keys during development — they make no real charges. Switch to sk_live_… when you are ready to process real transactions.
The GET /v1/merchants/current endpoint does not require X-Merchant-Id. Use it to look up your Merchant ID during initial setup.
For full details on key types, scopes, and error handling, see Authentication.

​
Request format

Set Content-Type: application/json and pass parameters as a JSON body on POST and PATCH requests.
curl
curl --request GET \
  --url https://api.borga.is/v1/merchants/current \
  --header "Authorization: Bearer sk_test_YOUR_SECRET_KEY"

​
Pagination

List endpoints use cursor-based pagination. Pass starting_after with the ID of the last object you received to fetch the next page, and use limit to control page size.
ParameterTypeDescription
starting_afterstringReturn objects after this object ID.
limitintegerMaximum number of objects to return.
Store the id of the last item on each page and pass it as starting_after on the next request. This approach handles insertions and deletions more reliably than offset-based pagination.

​
Idempotency

Network failures can leave you uncertain whether a request was processed. Pass an Idempotency-Key header with a unique string on POST requests to safely retry without risking duplicate operations. Borga stores the result of the first request and returns the same response for any subsequent request with the same key. 
Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890
A UUID generated per operation works well as an idempotency key. Do not reuse a key for a different operation — Borga deduplicates on the key alone.

​
Versioning

All endpoints are under /v1/. Breaking changes will be introduced under a new version prefix. The current version will continue to be supported after a new version is released.

​
Rate limits

Rate limits apply to all API endpoints. If you exceed the limit, Borga returns 429 Too Many Requests. Back off and retry after a short delay. See Errors for details on the error response format.