Getting Started

The Benji Pays API is a JSON-over-HTTPS API. All endpoints live under /v2, all error responses follow RFC 7807, and cross-cutting behavior (request IDs, idempotency, pagination, rate limits, errors) is shared across the platform.

What this API is for

The API exposes the Benji Pays platform to two audiences:

• Merchant-facing integrations (per-organization) authenticate with an x-api-key issued from the merchant app and act on behalf of a single organization.
• Distributor and partner integrations (e.g. marketplaces, MSP tooling) authenticate with an Auth0 M2M token and operate on resources tied to their actor.

These audiences mostly use different /v2 routes (merchant org routes vs partner/distributor routes). They share the same cross-cutting behavior. GET /v2/whoami is shared and accepts either auth method.

Before you start

You need:

• An x-api-key issued from the merchant app, or Auth0 M2M client_id/client_secret for partner/distributor access.
• An HTTP client that can send custom headers (x-api-key, Authorization, Idempotency-Key, X-Request-ID, etc.).

A typical first call (merchant)

Call a merchant org route with your API key — for example list gateways:

curl -X GET https://api.benjipays.com/v2/gateways \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

A successful response returns the organization's enabled gateways (see the OpenAPI merchant spec for the full schema).

You can also call GET /v2/whoami with the same API key to confirm the actor:

curl -X GET https://api.benjipays.com/v2/whoami \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Partners and distributors

Exchange Auth0 client credentials for an access token (see Authentication), then call GET /v2/whoami to confirm the token's actor and scopes:

curl -X GET https://api.benjipays.com/v2/whoami \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

What to read next

Each cross-cutting topic has its own guide:

• Authentication — Auth0 M2M tokens and the x-api-key flow.
• Rate Limits — sliding-window limits and the X-RateLimit-* headers.
• Idempotency — making POST/PATCH/PUT safe to retry.
• Request Tracing — X-Request-ID and X-Correlation-ID.
• Pagination — offset-based pagination and response envelope.
• Dates and Times — UTC calendar-day + ISO filters; timestamps in responses are UTC (…Z); some fields are date-only (YYYY-MM-DD).
• Errors — RFC 7807 problem details and common status codes.
• Charge an Invoice — POST /v2/transactions and when to poll GET /v2/transactions.

The per-endpoint reference is generated from the OpenAPI specs at /docs/bp-api-openapi-partner.{json,yaml} (Auth0 M2M / partner endpoints) and /docs/bp-api-openapi-merchant.{json,yaml} (x-api-key / merchant endpoints).