API reference

API basics

Base URL, authentication, errors, idempotency, pagination, and limits for every endpoint.

Base URL

https://indeficient.com/api/v1

Requests and responses are JSON. Times are ISO 8601 in UTC; amounts and ids are strings.

Authentication

Send your key as a bearer token: Authorization: Bearer pp_test_…. The key decides the business and environment; no request names them.

Keys are created, rolled, and revoked in the dashboard. The full key is shown once.
Revoking a key takes effect on the next request. Rolling issues a new key and can keep the old one working for a grace period.
Up to 5 active keys per business and environment.
Requests carrying browser headers (Origin, Sec-Fetch-Site, or cookies) are refused with browser_request. Keep keys on your server.

Rate limit

120 requests per minute per key. Beyond that, requests fail with 429 rate_limited until the minute ends.

Errors

Response

{
  "error": {
    "code": "invalid_request",
    "param": "protectionPeriod",
    "message": "protectionPeriod must be one of oneHour, oneDay, threeDays, sevenDays, fourteenDays, thirtyDays."
  }
}

Status	Code	Meaning
400	`invalid_request`	A parameter is invalid; `param` names it.
400	`bad_request`	The body is not a JSON object, or `Idempotency-Key` is malformed.
401	`unauthorized`	The key is missing, malformed, revoked, or expired.
403	`browser_request`	The request came from a browser. Call the API from your server.
404	`not_found`	No such resource for this key’s business and environment.
409	`reference_in_use`	An open intent already uses this `merchantReference`.
409	`intent_not_cancelable`	The intent is no longer `requires_payment`.
409	`signature_unverified`	The transaction was not found, failed, or did not create a payment for this intent. Not stored against an `Idempotency-Key`: send it again once it is confirmed.
409	`idempotency_conflict`	This `Idempotency-Key` was used with a different request.
409	`idempotency_in_progress`	A request with this key is still running. Retry shortly.
413	`bad_request`	The body is larger than 16 KB.
415	`bad_request`	The body is not sent as `Content-Type: application/json`.
429	`rate_limited`	More than 120 requests in a minute for this key.
500	`internal_error`	Something went wrong on our side. Safe to retry with the same key.
503	`unavailable`	The API is temporarily unavailable. Retry with backoff.
503	`chain_unavailable`	The chain could not be read to verify a payment. Retry with backoff; the periodic sweep also finds it.

Idempotency

Every POST accepts an Idempotency-Key header (1 to 255 printable ASCII characters), scoped to your business and environment and kept for 24 hours. Repeating a request with the same key and body returns the first response again, with the header Idempotent-Replayed: true. The same key with a different body is refused with idempotency_conflict. Server errors are not stored, so retrying runs the request again.

Pagination

List endpoints return { "object": "list", "data": [...], "hasMore": true|false }, newest first. Pass limit (1 to 100, default 20) and, for the next page, starting_after set to the last item’s id.

Check a key

GET/api/v1/me

The business and environment the key acts for.

curl https://indeficient.com/api/v1/me \
  -H "Authorization: Bearer $PP_API_KEY"

Response

{
  "object": "business",
  "id": "biz_m2xk7q4vtc5nhaw3rjpe",
  "name": "Northwind Goods",
  "environment": "test",
  "apiKey": {
    "id": "k5wq3zn7rt2hxmva"
  }
}