# Benji Pays Documentation > Sits between accounting and payment rails for reminders, Pay Now, autopay, portal, and book sync. ## Guides: getting-started - [Getting Started](https://developer.benjipays.com/docs/getting-started.md): A 5-minute overview of the Benji Pays API for new integrators. - [Authentication](https://developer.benjipays.com/docs/authentication.md): Authenticate with an x-api-key (merchant-scoped) or Auth0 M2M tokens. - [Errors](https://developer.benjipays.com/docs/errors.md): RFC 7807 problem details, common status codes, and how to interpret error bodies. - [Idempotency](https://developer.benjipays.com/docs/idempotency.md): Make POST/PATCH/PUT requests safe to retry with the Idempotency-Key header. - [Pagination](https://developer.benjipays.com/docs/pagination.md): Offset-based pagination, response envelope, and how to iterate through pages. - [Rate Limits](https://developer.benjipays.com/docs/rate-limits.md): Sliding-window rate limits and how to read the X-RateLimit headers and 429 responses. - [Request Tracing](https://developer.benjipays.com/docs/request-tracing.md): Use X-Request-ID and X-Correlation-ID to trace individual requests and distributed flows. - [MCP Server](https://developer.benjipays.com/docs/mcp.md): Connect AI clients directly to the Benji Pays API using the Model Context Protocol (MCP). - [Dates and Times](https://developer.benjipays.com/docs/dates-and-times.md): How date-range filters and response timestamps work in the Benji Pays API. - [Charge an Invoice](https://developer.benjipays.com/docs/charge-invoice.md): Charge a stored payment method against an invoice with POST /v2/transactions, then poll GET /v2/transactions when the status is not final. - [Customer Portal SSO](https://developer.benjipays.com/docs/customer-portal-sso.md): Choose a custom JWT or OAuth/OIDC flow to sign customers in to the Benji Pays Customer Portal. - [Customer Portal SSO with a Custom JWT](https://developer.benjipays.com/docs/customer-portal-sso-jwt.md): Sign customers in to the Benji Pays Customer Portal with a short-lived HS256 JWT. - [Customer Portal SSO with OAuth/OIDC](https://developer.benjipays.com/docs/customer-portal-sso-oauth.md): Connect an OpenID Connect identity provider to the Benji Pays Customer Portal. ## API Reference: Benji Pays Merchant API - Whoami - [Get current actor information](https://developer.benjipays.com/reference/get_v2-whoami-1.md): **Access:** Requires any authenticated actor (Auth0 JWT or organization API key) Returns authenticated actor details and permissions. Accepts either an Auth0 Bearer token or an organization-scoped… - Gateways - [List payment gateways for an Organization](https://developer.benjipays.com/reference/get_v2-gateways.md): Returns enabled payment gateways for the organization associated with the authenticated API key. - [List gateway capabilities for an Organization](https://developer.benjipays.com/reference/get_v2-gateways-capabilities.md): Returns gateway capabilities (`data`) and company default hashes by currency (`defaults`) for the organization. - Invoices - [List invoices for an Organization](https://developer.benjipays.com/reference/get_v2-invoices.md): Returns paginated Benji-controlled camelCase invoice summaries for the authenticated organization. Field names match filter/query params (`invoiceNumber`, `dueDate`, `customerId` → `customer.id`).… - [Get a single invoice by accounting ID](https://developer.benjipays.com/reference/get_v2-invoices-invoiceid.md): Returns the Benji summary DTO for an invoice by its accounting system ID (`id` on the invoice object). Pass `?include=accounting` to nest the full stored invoice under `data.accounting` (fields from… - [Download an invoice PDF](https://developer.benjipays.com/reference/get_v2-invoices-invoiceid-pdf.md): Returns the official invoice PDF from the organization accounting system (QBO / Xero / BC / integration priority). The caller downloads and attaches it — this endpoint does not email the PDF. - Customers - [List customers for an Organization](https://developer.benjipays.com/reference/get_v2-customers.md): Returns paginated Benji-controlled camelCase customer summaries for the organization associated with the authenticated API key. Mirrors the data set shown in the merchant-app customers table. List… - [Get a single customer by accounting ID](https://developer.benjipays.com/reference/get_v2-customers-customerid.md): Returns the Benji summary DTO for a customer by its accounting system ID (`id` on the customer object). Pass `?include=accounting` to nest the full stored customer under `data.accounting` (fields… - [Update a customer's settings](https://developer.benjipays.com/reference/patch_v2-customers-customerid.md): Updates the settings of a customer by its accounting system ID (`id` on the customer object). Accepts only the settings defined in the request schema, using the same field names and nesting that GET… - Accounting Accounts - [List Xero accounts for deposits](https://developer.benjipays.com/reference/get_v2-accounting-accounts.md): Returns live Xero chart accounts for the organization on the API key. `purpose=prepayment` returns the revenue-account set. The `id` is the value accepted as `revenueAccountId` on the deposit charge.… - Notes - [List note categories](https://developer.benjipays.com/reference/get_v2-notes-categories.md): Returns enabled system categories plus custom categories for the authenticated organization only. - [List note statuses](https://developer.benjipays.com/reference/get_v2-notes-statuses.md): Returns enabled system statuses plus custom statuses for the authenticated organization only. - [List customer note threads](https://developer.benjipays.com/reference/get_v2-customers-customerid-notes.md): Lists paginated root note threads with reply counts and latest activity for a customer. - [Create a customer note thread](https://developer.benjipays.com/reference/post_v2-customers-customerid-notes.md) - [Get a customer note thread](https://developer.benjipays.com/reference/get_v2-customers-customerid-notes-noteid.md) - [Update a root note or comment](https://developer.benjipays.com/reference/patch_v2-customers-customerid-notes-noteid.md) - [Soft-delete a root note or comment](https://developer.benjipays.com/reference/delete_v2-customers-customerid-notes-noteid.md): Comments may be deleted only by their author or a full admin, and only before a later reply exists. - [Add a comment to a customer note thread](https://developer.benjipays.com/reference/post_v2-customers-customerid-notes-noteid-replies.md): Adds a one-level comment to a root note. Replying to another comment is rejected. - [Set root note status](https://developer.benjipays.com/reference/post_v2-customers-customerid-notes-noteid-status.md) - [Pin a root note as customer alert](https://developer.benjipays.com/reference/post_v2-customers-customerid-alert.md) - [Remove customer alert](https://developer.benjipays.com/reference/delete_v2-customers-customerid-alert.md): Unpins the standing customer alert without deleting the note. - Payment Methods - [List payment methods for an Organization](https://developer.benjipays.com/reference/get_v2-payment-methods.md): Returns paginated saved payment methods (profiles) for the organization associated with the authenticated API key. Filter by accounting `customerId` (QuickBooks Id, Xero ContactID, etc.) to list… - [Get a payment method for an Organization](https://developer.benjipays.com/reference/get_v2-payment-methods-id.md): Returns a single saved payment method (profile) by its `id` (from `GET /v2/payment-methods`), scoped to the organization associated with the authenticated API key. Includes the nested `mandate` — the… - Payment Links - [Create an unapplied (no-invoice) payment link](https://developer.benjipays.com/reference/post_v2-payment-links-unapplied.md): Creates a no-invoice payment link for the organization associated with the authenticated API key. The payment will be added to the payment to apply table. Does not create/attach an accounting invoice… - [Create an applied (invoice-tied) payment link](https://developer.benjipays.com/reference/post_v2-payment-links-applied-invoiceid.md): Creates a tokenized payment link tied to an existing accounting invoice for the organization associated with the authenticated API key. After pay, the payment applies to that invoice. For security,… - Payment Method Requests - [List payment-method-on-file requests](https://developer.benjipays.com/reference/get_v2-payment-method-requests.md): Returns paginated customer payment-method-on-file requests for the organization associated with the authenticated API key. Excludes generic (no-customer) portal-link submissions. Filter by customer,… - [Create a payment-method-on-file request](https://developer.benjipays.com/reference/post_v2-payment-method-requests.md): Creates a customer payment-method-on-file request for the organization associated with the authenticated API key. Returns a portal URL. Does not email or SMS — the caller sends `url` to the customer.… - [Get a payment-method-on-file request](https://developer.benjipays.com/reference/get_v2-payment-method-requests-paymentmethodrequestid.md): Returns a single customer payment-method-on-file request by its `id` (from create or list). Scoped to the organization associated with the authenticated API key. Generic (no-customer) portal-link… - Transactions - [List transactions for an Organization](https://developer.benjipays.com/reference/get_v2-transactions.md): Returns paginated payment transactions for the organization associated with the authenticated API key. Matches the data visible in the merchant-app transaction reporting table, including enriched… - [Charge an invoice (create transaction)](https://developer.benjipays.com/reference/post_v2-transactions.md): Charges a stored payment method against an accounting invoice for the organization associated with the authenticated API key (off-session AR collection). The charge is attempted once against the… - [Retry the accounting writeback for a charge](https://developer.benjipays.com/reference/post_v2-transactions-transactionid-retry-accounting.md): Retries **only** the accounting writeback (QBO / Xero / Business Central) for a charge that already succeeded — for example when `POST /v2/transactions` returned… - [Download a transaction receipt PDF](https://developer.benjipays.com/reference/get_v2-transactions-transactionid-receipt.md): Returns a receipt PDF for a payment transaction (`data.id` from `POST /v2/transactions` or `GET /v2/transactions`). Default is the customer copy. Pass `?type=merchant` for the merchant copy. Same… - [Resend the customer receipt email](https://developer.benjipays.com/reference/post_v2-transactions-transactionid-resend-receipt.md): Regenerates and resends the customer receipt email for a transaction. No charge, void, or accounting writeback. Recipients come from the accounting customer enabled emails (including parent-customer… - [Charge a deposit / prepayment](https://developer.benjipays.com/reference/post_v2-transactions-prepayments.md): Charges a stored payment method with **no invoice** (unallocated deposit / prepayment) for the organization associated with the authenticated API key. The charge is attempted once against the… - Organization - [Get profile for an Organization](https://developer.benjipays.com/reference/get_v2-organization.md): Returns the normalized profile for the organization associated with the authenticated API key. - Users - [List users for an Organization](https://developer.benjipays.com/reference/get_v2-users.md): Returns a paginated list of login accounts for the organization associated with the authenticated API key, including MFA enabled status. - Emails - [List sent emails for an Organization](https://developer.benjipays.com/reference/get_v2-emails.md): Returns paginated sent emails for the organization associated with the authenticated API key. Matches the merchant-app email history, restricted to merchant-facing email types. Filter by customer,… - [Get a single sent email](https://developer.benjipays.com/reference/get_v2-emails-emailid.md): Returns a single sent email by its `id` (from the list endpoint), including the body content and the full delivery event timeline. Scoped to the authenticated organization and restricted to… - Autoprocessing - [List the auto-processing forecast for an Organization](https://developer.benjipays.com/reference/get_v2-autoprocessing-forecast.md): Returns a paginated auto-processing forecast: for each open invoice, whether it will be auto-charged on the supplied run date and the reasons behind that decision. Matches the merchant-app batch… - Settings - [Get settings for an Organization](https://developer.benjipays.com/reference/get_v2-settings.md): Returns the normalized settings for the organization associated with the authenticated API key. ## API Reference: Benji Pays Partner API - Whoami - [Get current actor information](https://developer.benjipays.com/reference/get_v2-whoami.md): **Access:** Requires any authenticated actor (Auth0 JWT or organization API key) Returns authenticated actor details and permissions. Accepts either an Auth0 Bearer token or an organization-scoped… - [Echo request body](https://developer.benjipays.com/reference/post_v2-whoami-echo.md): **Access:** Requires any authenticated actor (DISTRIBUTOR, PARTNER, or ORGANIZATION) Validates and echoes back the request body. Requires JWT authentication. - Plans - [List plans for authenticated distributor](https://developer.benjipays.com/reference/get_v2-plans.md): **Access:** Requires DISTRIBUTOR actor type Returns a paginated list of plans visible to the authenticated distributor. Plans can be filtered by status and partnerId (for custom-priced plans).… - [Get a single plan by ID](https://developer.benjipays.com/reference/get_v2-plans-planid.md): **Access:** Requires DISTRIBUTOR actor type Returns details for a specific plan by its MongoDB ObjectId. The plan must be visible to the authenticated distributor. **Visibility:** - Returns 404 if… - Partners - [Create a new Partner](https://developer.benjipays.com/reference/post_v2-partners.md): **Access:** Requires DISTRIBUTOR actor type Creates a Partner entity (MSP, accountant, ISO) under the authenticated distributor. The authenticated distributor's external ID becomes the… - [List all partners for authenticated distributor](https://developer.benjipays.com/reference/get_v2-partners.md): **Access:** Requires DISTRIBUTOR actor type Lists all Partners (MSP, accountant, ISO) under the authenticated distributor with pagination and optional filtering. **Features:** - Sorted… - [Get a specific partner by ID](https://developer.benjipays.com/reference/get_v2-partners-partnerid.md): **Access:** Requires DISTRIBUTOR actor type Retrieves details for a specific Partner by its MongoDB ObjectId. Only returns partners that belong to the authenticated distributor (enforces isolation).… - Organizations - [List Organizations](https://developer.benjipays.com/reference/get_v2-organizations.md): **Access:** Requires DISTRIBUTOR or PARTNER actor type. Lists Organizations with optional filtering and pagination. - **Distributor:** Returns all organizations under the distributor. Use… - [Create a new Organization](https://developer.benjipays.com/reference/post_v2-organizations.md): **Access:** Requires DISTRIBUTOR or PARTNER actor type. Creates an Organization (Benji Pays company). Supports three flows: - **Distributor direct** (no `partnerId` in body) — org owned directly by… - [Get single Organization by ID](https://developer.benjipays.com/reference/get_v2-organizations-organizationid.md): **Access:** Requires DISTRIBUTOR or PARTNER actor type Gets details for a specific Organization. - **Distributor:** Can access any organization under their distributor. - **Partner:** Can only… - [Suspend an Organization](https://developer.benjipays.com/reference/post_v2-organizations-organizationid-suspend.md): **Access:** Requires DISTRIBUTOR actor type Suspends an Organization by disabling access and billing. Used when a Partner (MSP) is not paying their distributor bill. Requires JWT authentication and… - [Activate an Organization](https://developer.benjipays.com/reference/post_v2-organizations-organizationid-activate.md): **Access:** Requires DISTRIBUTOR actor type Re-activates a suspended Organization by enabling access and billing. Requires JWT authentication and 'partners:organizations:activate' scope. - [Close an Organization](https://developer.benjipays.com/reference/post_v2-organizations-organizationid-close.md): **Access:** Requires DISTRIBUTOR actor type Closes an Organization by disabling access, billing, and marking as closed. This is a permanent state change (unlike suspend which is temporary).… - [Change organization plan](https://developer.benjipays.com/reference/patch_v2-organizations-organizationid-plan.md): **Access:** Requires DISTRIBUTOR actor type Changes the billing plan assigned to an Organization. Used when an MSP upgrades or downgrades a customer's subscription. **Workflow:** 1. Validates… - [Resend admin invite for an Organization](https://developer.benjipays.com/reference/post_v2-organizations-organizationid-resend-invite.md): **Access:** Requires DISTRIBUTOR actor type Resends the admin onboarding invite email for an Organization. Deletes any existing incomplete invites and creates a new one. **Workflow:** 1. Deletes… - Usage - [Get usage snapshot for a month](https://developer.benjipays.com/reference/get_v2-usage.md): **Access:** Requires DISTRIBUTOR actor type Returns usage data for all Organizations under the authenticated distributor for a specified month. Used by distributors (e.g., Sherweb) to show… - Billing - [Get finalized billing data for a month](https://developer.benjipays.com/reference/get_v2-billing.md): **Access:** Requires DISTRIBUTOR actor type Returns finalized billing data for a completed month. Used by distributors for invoicing and reconciliation. Data is locked and should match what was…