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.

Customer Portal SSO is a separate, interactive login surface. If you want customers to sign in through your application or identity provider, start with Customer Portal SSO instead of using API credentials.

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.
• Customer Portal SSO — interactive customer login with a custom JWT or OAuth/OIDC provider.
• 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).