Benji Pays Settings API

openapi: 3.2.0
info:
  title: Benji Pays Merchant Settings API
  description: 'The Benji Pays Merchant API is a JSON over HTTPS API. All endpoints live under `/v2`. Errors follow RFC 7807 and are served as `application/problem+json`. This overview describes the cross-cutting behavior shared by every merchant endpoint. Endpoint-specific schemas live with each operation. ## Authentication


    Merchant endpoints authenticate with an organization-scoped `x-api-key` header issued from the merchant app:


    ```

    x-api-key:

    ```


    The key is scoped to one organization and inherits the permissions of the login that created it. Failures return `401 Unauthorized` (missing/expired/invalid credentials) or `403 Forbidden` (insufficient mapping permission or organization lifecycle restrictions). ## Request and Correlation IDs


    Two header pairs help with tracing:


    | Header | Direction | Purpose |

    | --- | --- | --- |

    | `X-Request-ID` | request (optional) / response (always) | Unique identifier for one request. Generated as a UUID v4 when the client omits it. |

    | `X-Correlation-ID` | request (optional) / response (always) | Identifier that flows across service boundaries for distributed tracing. Generated as a UUID v4 when omitted. |


    Both IDs are echoed on success and included as `requestId` / `correlationId` extensions on `application/problem+json` error responses. These headers are auto-injected on every operation in this spec — do not redeclare them per route. ## Idempotency


    POST, PATCH, and PUT endpoints accept an `Idempotency-Key` header to make retries safe. - Format: 1–255 characters, alphanumeric only (`[a-zA-Z0-9]+`). - Scope: keys are scoped per actor (no cross-tenant collisions). - Cache: the first response for a given key is cached for 24 hours. - Replay: a duplicate request with the same key and the same body returns the cached response with `X-Idempotency-Replayed: true` only after credentials were resolved by the global authenticate middleware (API key or Auth0 JWT signature check) before the idempotency cache lookup. - Conflict: same key with a different body returns `409 Conflict`. - In-flight: a second request with the same key while the first is still being processed returns `429 Too Many Requests` with `Retry-After` and problem `type` `https://api.benjipays.com/problems/idempotency-processing` (distinct from rate-limit `…/rate-limit-exceeded`). `Idempotency-Key` is auto-injected on every POST/PATCH/PUT operation in this spec — do not redeclare it per route. Routes that intentionally opt out set `x-bp-skip-idempotency: true`. The middleware fails open: if the cache layer is unavailable the request proceeds without idempotency protection. Most write routes treat the header as optional. Routes that require it set `x-bp-require-idempotency: true` and return `400 Bad Request` when it is missing — currently `POST /v2/transactions`, `POST /v2/transactions/prepayments`, and `POST /v2/transactions/{transactionId}/retry-accounting`. Those routes are also the exception to the fail-open rule above: when the cache layer is unavailable they return `503 Service Unavailable` with `Retry-After` and problem `type` `https://api.benjipays.com/problems/idempotency-unavailable`, and the request is not processed. Retry with the same key. The two charge routes (`POST /v2/transactions` and `POST /v2/transactions/prepayments`) also save the key on the charge. Recover a charge with `GET /v2/transactions?idempotencyKey={key}` (empty `data` when the key was never used). After the 24-hour replay window, the same key creates a new charge. ## Pagination


    List endpoints use offset-based pagination with two query parameters:


    | Parameter | Type | Default | Bounds |

    | --- | --- | --- | --- |

    | `limit` | integer | `20` | `1`–`1000` |

    | `offset` | integer | `0` | `≥ 0` |


    Some endpoints use different bounds (for example usage/billing and autoprocessing forecast). Check the per-operation schema.'
  version: 2.0.0
  contact:
    name: Benji Pays API Support
    email: benji@benjipays.com
servers:
- url: https://api.benjipays.com
  description: Development server
security:
- ApiKeyAuth: []
tags:
- name: Settings
paths:
  /v2/settings:
    get:
      summary: Get settings for an Organization
      description: Returns the normalized settings for the organization associated with the authenticated API key.
      tags:
      - Settings
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Successful response with organization settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationSettingsResponse'
        '401':
          description: Unauthorized — invalid or missing authentication, or organization is not active.
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: number
                  detail:
                    type: string
                  instance:
                    type: string
                required:
                - type
                - title
                - status
                - detail
                additionalProperties: false
                description: Error response (RFC 7807 Problem Details)
                examples:
                  invalidToken:
                    summary: Invalid or missing authentication
                    value:
                      type: https://api.benjipays.com/problems/unauthorized
                      title: Unauthorized
                      status: 401
                      detail: Invalid or missing authentication token
                      instance: /v2/settings
                  organizationNotActive:
                    summary: Organization is not active
                    value:
                      type: https://api.benjipays.com/problems/unauthorized
                      title: Unauthorized
                      status: 401
                      detail: API access is not active for this organization
                      instance: /v2/settings
        '403':
          description: Forbidden — missing required scope (`organizations:settings:read`), insufficient mapping permission (`companyAdmin` required), or free trial ended without billing.
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: number
                  detail:
                    type: string
                  instance:
                    type: string
                required:
                - type
                - title
                - status
                - detail
                additionalProperties: false
                description: Error response (RFC 7807 Problem Details)
                examples:
                  missingScope:
                    summary: Missing OAuth scope
                    value:
                      type: https://api.benjipays.com/problems/forbidden
                      title: Forbidden
                      status: 403
                      detail: 'Missing required scope: organizations:settings:read'
                      instance: /v2/settings
                  insufficientPermission:
                    summary: Insufficient mapping permission
                    value:
                      type: https://api.benjipays.com/problems/forbidden
                      title: Forbidden
                      status: 403
                      detail: Insufficient permission for this resource
                      instance: /v2/settings
        '429':
          description: Too Many Requests — rate limit exceeded.
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: number
                  detail:
                    type: string
                  instance:
                    type: string
                required:
                - type
                - title
                - status
                - detail
                additionalProperties: false
                description: Error response (RFC 7807 Problem Details)
      parameters:
      - $ref: '#/components/parameters/RequestIdHeader'
      - $ref: '#/components/parameters/CorrelationIdHeader'
      operationId: getV2Settings
      x-operation-id-source: derived
components:
  parameters:
    CorrelationIdHeader:
      name: X-Correlation-ID
      in: header
      required: false
      description: Optional ID that flows across service boundaries for distributed tracing. The server generates a UUID v4 if omitted and always echoes the value in the response.
      schema:
        type: string
        format: uuid
    RequestIdHeader:
      name: X-Request-ID
      in: header
      required: false
      description: Optional client-supplied unique ID for one request. The server generates a UUID v4 if omitted and always echoes the value in the response.
      schema:
        type: string
        format: uuid
  schemas:
    OrganizationSettingsResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            autoProcessing:
              type: object
              properties:
                enabled:
                  type: boolean
                runHour:
                  type: number
                delayDays:
                  type: number
                startDate:
                  anyOf:
                  - type: string
                  - type: 'null'
                processCreditMemos:
                  type: boolean
                useParentProfiles:
                  type: boolean
                skips:
                  type: object
                  properties:
                    noTermsDisabled:
                      type: boolean
                    skipDueDateNotMet:
                      type: boolean
                    memoSkip:
                      anyOf:
                      - type: object
                        properties:
                          text:
                            anyOf:
                            - type: string
                            - type: 'null'
                          action:
                            anyOf:
                            - type: string
                            - type: 'null'
                        required:
                        - text
                        - action
                        additionalProperties: false
                      - type: 'null'
                    skipSurcharge:
                      type: object
                      properties:
                        enabled:
                          type: boolean
                        min:
                          anyOf:
                          - type: number
                          - type: 'null'
                        max:
                          anyOf:
                          - type: number
                          - type: 'null'
                      required:
                      - enabled
                      - min
                      - max
                      additionalProperties: false
                    autoProcessAmountSkip:
                      type: object
                      properties:
                        enabled:
                          type: boolean
                        min:
                          anyOf:
                          - type: number
                          - type: 'null'
                        max:
                          anyOf:
                          - type: number
                          - type: 'null'
                      required:
                      - enabled
                      - min
                      - max
                      additionalProperties: false
                    invoicePrefixSkip:
                      type: object
                      properties:
                        enabled:
                          type: boolean
                        prefixes:
                          type: array
                          items:
                            type: string
                        action:
                          anyOf:
                          - type: string
                          - type: 'null'
                      required:
                      - enabled
                      - prefixes
                      - action
                      additionalProperties: false
                  required:
                  - noTermsDisabled
                  - skipDueDateNotMet
                  - memoSkip
                  - skipSurcharge
                  - autoProcessAmountSkip
                  - invoicePrefixSkip
                  additionalProperties: false
              required:
              - enabled
              - runHour
              - delayDays
              - startDate
              - processCreditMemos
              - useParentProfiles
              - skips
              additionalProperties: false
            email:
              type: object
              properties:
                sendReceipts:
                  type: boolean
                attachInvoice:
                  type: boolean
                sendInvoiceAttachments:
                  type: boolean
                disableCompanyEmailResults:
                  type: boolean
                onlySendAttemptedBatchResults:
                  type: boolean
                displayInvoiceEmails:
                  type: boolean
                selectInvoiceEmails:
                  type: boolean
                autoPaySendReceiptsInvoiceEmails:
                  type: boolean
                invoiceCcEmails:
                  type: array
                  items:
                    type: string
                invoiceBccEmails:
                  type: array
                  items:
                    type: string
                receiptCcEmails:
                  type: array
                  items:
                    type: string
                receiptBccEmails:
                  type: array
                  items:
                    type: string
                useSmtp:
                  type: boolean
              required:
              - sendReceipts
              - attachInvoice
              - sendInvoiceAttachments
              - disableCompanyEmailResults
              - onlySendAttemptedBatchResults
              - displayInvoiceEmails
              - selectInvoiceEmails
              - autoPaySendReceiptsInvoiceEmails
              - invoiceCcEmails
              - invoiceBccEmails
              - receiptCcEmails
              - receiptBccEmails
              - useSmtp
              additionalProperties: false
            customerPortal:
              type: object
              properties:
                enabled:
                  type: boolean
                url:
                  anyOf:
                  - type: string
                  - type: 'null'
                name:
                  anyOf:
                  - type: string
                  - type: 'null'
                theme:
                  type: object
                  properties:
                    colour:
                      anyOf:
                      - type: string
                      - type: 'null'
                  required:
                  - colour
                  additionalProperties: false
                accessDisabled:
                  type: boolean
                forceSaveCards:
                  type: boolean
                disableSaveCards:
                  type: boolean
                autoEnableProfiles:
                  type: boolean
                allowPortalChangeAutoPay:
                  type: boolean
                allowPortalManageEmails:
                  type: boolean
                allowPortalManageAddress:
                  type: boolean
                allowPortalSchedulePayment:
                  type: boolean
                allowAllProfileDeleteOnPortal:
                  type: boolean
                limitOpenInvoicesView:
                  type: boolean
                showInvoicesAfterDate:
                  anyOf:
                  - type: string
                  - type: 'null'
                displayInvoiceAttachments:
                  type: boolean
                sendInvoiceAttachments:
                  type: boolean
                disablePortalEmailLinks:
                  type: boolean
                disablePaymentAmountInput:
                  type: boolean
                disablePartialPayments:
                  type: boolean
                disableGenericPaymentLink:
                  type: boolean
                payNowAmountRequired:
                  type: boolean
                customDomain:
                  anyOf:
                  - type: string
                  - type: 'null'
                preAuthAgreements:
                  type: object
                  properties:
                    card:
                      type: object
                      properties:
                        en:
                          anyOf:
                          - type: string
                          - type: 'null'
                        fr:
                          anyOf:
                          - type: string
                          - type: 'null'
                      required:
                      - en
                      - fr
                      additionalProperties: false
                    ach:
                      type: object
                      properties:
                        en:
                          anyOf:
                          - type: string
                          - type: 'null'
                        fr:
                          anyOf:
                          - type: string
                          - type: 'null'
                      required:
                      - en
                      - fr
                      additionalProperties: false
                    eft:
                      type: object
                      properties:
                        en:
                          anyOf:
                          - type: string
                          - type: 'null'
                        fr:
                          anyOf:
                          - type: string
                          - type: 'null'
                      required:
                      - en
                      - fr
                      additionalProperties: false
                    bacs:
                      type: object
                      properties:
                        en:
                          anyOf:
                          - type: string
                          - type: 'null'
                        fr:
                          anyOf:
                          - type: string
                          - type: 'null'
                      required:
                      - en
                      - fr
                      additionalProperties: false
                    sepa:
                      type: object
                      properties:
                        en:
                          anyOf:
                          - type: string
                          - type: 'null'
                        fr:
                          anyOf:
                          - type: string
                          - type: 'null'
                      required:
                      - en
                      - fr
                      additionalProperties: false
                  required:
                  - card
                  - ach
                  - eft
                  - bacs
                  - sepa
                  additionalProperties: false
              required:
              - enabled
              - url
              - name
              - theme
              - accessDisabled
              - forceSaveCards
              - disableSaveCards
              - autoEnableProfiles
              - allowPortalChangeAutoPay
              - allowPortalManageEmails
              - allowPortalManageAddress
              - allowPortalSchedulePayment
              - allowAllProfileDeleteOnPortal
              - limitOpenInvoicesView
              - showInvoicesAfterDate
              - displayInvoiceAttachments
              - sendInvoiceAttachments
              - disablePortalEmailLinks
              - disablePaymentAmountInput
              - disablePartialPayments
              - disableGenericPaymentLink
              - payNowAmountRequired
              - customDomain
              - preAuthAgreements
              additionalProperties: false
            accountingSystem:
              type: object
              properties:
                emailAutoEnable:
                  type: boolean
                autoEnableNewCustomers:
                  type: boolean
                surchargeAutoEnable:
                  type: boolean
                bcAutoPostJournals:
                  type: boolean
              required:
              - emailAutoEnable
              - autoEnableNewCustomers
              - surchargeAutoEnable
              - bcAutoPostJournals
              additionalProperties: false
            security:
              type: object
              properties:
                disableNonSsoLogin:
                  type: boolean
                enforceMfa:
                  type: boolean
              required:
              - disableNonSsoLogin
              - enforceMfa
              additionalProperties: false
          required:
          - autoProcessing
          - email
          - customerPortal
          - accountingSystem
          - security
          additionalProperties: false
      required:
      - data
      additionalProperties: false
      description: Organization settings response
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Organization-scoped API key. Send it in the x-api-key header. Available on organization endpoints only.
x-speakeasy-retries:
  strategy: backoff
  backoff:
    initialInterval: 500
    maxInterval: 60000
    maxElapsedTime: 3600000
    exponent: 1.5
  statusCodes:
  - 5XX
  retryConnectionErrors: true
x-provenance:
  method: searched
  source: https://developer.benjipays.com/reference
  harvested: '2026-11-02'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://developer.benjipays.com/reference/delete_v2-customers-customerid-alert.md
  - https://developer.benjipays.com/reference/delete_v2-customers-customerid-notes-noteid.md
  - https://developer.benjipays.com/reference/get_v2-accounting-accounts.md
  - https://developer.benjipays.com/reference/get_v2-autoprocessing-forecast.md
  - https://developer.benjipays.com/reference/get_v2-customers-customerid-notes-noteid.md
  - https://developer.benjipays.com/reference/get_v2-customers-customerid-notes.md
  - https://developer.benjipays.com/reference/get_v2-customers-customerid.md
  - https://developer.benjipays.com/reference/get_v2-customers.md
  - https://developer.benjipays.com/reference/get_v2-emails-emailid.md
  - https://developer.benjipays.com/reference/get_v2-emails.md
  - https://developer.benjipays.com/reference/get_v2-gateways-capabilities.md
  - https://developer.benjipays.com/reference/get_v2-gateways.md
  - https://developer.benjipays.com/reference/get_v2-invoices-invoiceid-pdf.md
  - https://developer.benjipays.com/reference/get_v2-invoices-invoiceid.md
  - https://developer.benjipays.com/reference/get_v2-invoices.md
  - https://developer.benjipays.com/reference/get_v2-notes-categories.md
  - https://developer.benjipays.com/reference/get_v2-notes-statuses.md
  - https://developer.benjipays.com/reference/get_v2-organization.md
  - https://developer.benjipays.com/reference/get_v2-payment-method-requests-paymentmethodrequestid.md
  - https://developer.benjipays.com/reference/get_v2-payment-method-requests.md
  - https://developer.benjipays.com/reference/get_v2-payment-methods-id.md
  - https://developer.benjipays.com/reference/get_v2-payment-methods.md
  - https://developer.benjipays.com/reference/get_v2-settings.md
  - https://developer.benjipays.com/reference/get_v2-transactions-transactionid-receipt.md
  - https://developer.benjipays.com/reference/get_v2-transactions.md
  - https://developer.benjipays.com/reference/get_v2-users.md
  - https://developer.benjipays.com/reference/get_v2-whoami-1.md
  - https://developer.benjipays.com/reference/patch_v2-customers-customerid-notes-noteid.md
  - https://developer.benjipays.com/reference/patch_v2-customers-customerid.md
  - https://developer.benjipays.com/reference/post_v2-customers-customerid-alert.md
  - https://developer.benjipays.com/reference/post_v2-customers-customerid-notes-noteid-replies.md
  - https://developer.benjipays.com/reference/post_v2-customers-customerid-notes-noteid-status.md
  - https://developer.benjipays.com/reference/post_v2-customers-customerid-notes.md
  - https://developer.benjipays.com/reference/post_v2-payment-links-applied-invoiceid.md
  - https://developer.benjipays.com/reference/post_v2-payment-links-unapplied.md
  - https://developer.benjipays.com/reference/post_v2-payment-method-requests.md
  - https://developer.benjipays.com/reference/post_v2-transactions-prepayments.md
  - https://developer.benjipays.com/reference/post_v2-transactions-transactionid-resend-receipt.md
  - https://developer.benjipays.com/reference/post_v2-transactions-transactionid-retry-accounting.md
  - https://developer.benjipays.com/reference/post_v2-transactions.md
  merge:
    pages: 40
    deduped: 167
    conflicts_kept_first: 0