Benji Pays Payment Links API

openapi: 3.2.0
info:
  title: Benji Pays Merchant Payment Links 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: Payment Links
  description: Unapplied (no-invoice) and applied (invoice-tied) payment links for authenticated organizations
paths:
  /v2/payment-links/applied/{invoiceId}:
    post:
      summary: Create an applied (invoice-tied) payment link
      description: '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, we recommend passing `allowSavedPaymentMethods: false` unless you have independently authenticated the user and are certain they are authorized to use the invoice customer’s saved payment methods. Setting it to `true` may display existing on-file payment methods and allows the user to pay with them. Does not email the link — the caller sends `url`. Requires `organizations:payment-links:create`.'
      tags:
      - Payment Links
      security:
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/RequestIdHeader'
      - $ref: '#/components/parameters/CorrelationIdHeader'
      - $ref: '#/components/parameters/IdempotencyKeyHeader'
      - in: path
        name: invoiceId
        schema:
          type: string
          minLength: 1
          maxLength: 200
          description: The accounting system invoice ID (e.g. the QuickBooks Id, Xero InvoiceID, or Business Central id). This is the value exposed as `id` on the invoice object.
          example: '1042'
        required: true
        description: The accounting system invoice ID (e.g. the QuickBooks Id, Xero InvoiceID, or Business Central id). This is the value exposed as `id` on the invoice object.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                gatewayId:
                  description: Optional gateway selector. Accepts a gateway store identifier or a hash from GET /v2/gateways/capabilities. If omitted, gateway is chosen from the invoice currency / defaults (same as unapplied).
                  type: string
                  minLength: 1
                  maxLength: 100
                allowSavedPaymentMethods:
                  description: 'Security recommendation: pass false to create a guest checkout unless you have independently authenticated the user and are certain they are authorized to use the invoice customer’s saved payment methods. When true, the pay-now page may display existing on-file payment methods and allow the user to pay with them. When omitted or false (default), saved payment methods are not shown or available.'
                  type: boolean
      responses:
        '200':
          description: Payment link created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAppliedPaymentLinkResponse'
        '400':
          description: Bad Request — invalid body/params, missing invoice customer/currency, or gateway/currency configuration
          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: RFC 7807 Problem Details error response
        '401':
          description: Unauthorized — invalid or missing authentication, or API access is not active for this organization (disabled or missing).
          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: RFC 7807 Problem Details error response
        '403':
          description: Forbidden — missing required OAuth scope (`organizations:payment-links:create`) and/or insufficient live mapping permission on the API key owner (e.g. `companyAdmin`). Scope and mapping are independent gates; see response `detail`.
          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: RFC 7807 Problem Details error response
                examples:
                  missingScope:
                    summary: Missing OAuth scope
                    value:
                      type: https://api.benjipays.com/problems/forbidden
                      title: Forbidden
                      status: 403
                      detail: 'Missing required scope: organizations:payment-links:create'
                      instance: /v2/payment-links/applied/{invoiceId}
                  insufficientMappingPermission:
                    summary: Insufficient live mapping permission (API key owner)
                    value:
                      type: https://api.benjipays.com/problems/forbidden
                      title: Forbidden
                      status: 403
                      detail: Insufficient permission for this resource
                      instance: /v2/payment-links/applied/{invoiceId}
        '404':
          description: Organization not found
          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: RFC 7807 Problem Details error response
        '429':
          description: Too Many Requests
          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: RFC 7807 Problem Details error response
      operationId: postV2PaymentLinksAppliedByInvoiceId
      x-operation-id-source: derived
  /v2/payment-links/unapplied:
    post:
      summary: Create an unapplied (no-invoice) payment link
      description: 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 and does not email the link — the caller sends `url` to the payer. Requires `organizations:payment-links:create`.
      tags:
      - Payment Links
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                source:
                  type: string
                  enum:
                  - default
                  - quoter
                  description: Who the link is for. Controls allowed returnUrl domains when returnUrl is sent.
                amount:
                  type: number
                  exclusiveMinimum: 0
                  maximum: 999999.99
                  description: Amount to charge. Must be > 0, max 999999.99, up to 2 decimal places.
                currency:
                  description: 3-letter currency code (e.g. USD). Used to pick the gateway.
                  type: string
                  minLength: 3
                  maxLength: 3
                  pattern: ^[A-Za-z]{3}$
                gatewayId:
                  description: Optional gateway selector. Accepts a gateway store identifier or a hash from GET /v2/gateways/capabilities. If omitted, gateway is chosen from currency / defaults.
                  type: string
                  minLength: 1
                  maxLength: 100
                name:
                  type: string
                  minLength: 1
                  maxLength: 200
                  description: Payer / customer display name on the pay page.
                reference:
                  type: string
                  minLength: 1
                  maxLength: 100
                  description: Human-readable label (e.g. quote number). Shown in UI / emails.
                dataId:
                  description: Machine id from the partner (e.g. Quoter quote id). Not an accounting invoice id.
                  type: string
                  maxLength: 100
                returnUrl:
                  description: 'Optional. Where to send the customer after a successful payment. Omit for no post-pay redirect. When set: must be https. For integration partners, only the expected return URL hosts for that `source` are accepted; otherwise open-redirect hardening still applies.'
                  type: string
                  maxLength: 2048
                  format: uri
                savePaymentMethod:
                  description: Optional override for the save-card checkbox. Omit = normal form. true = force save on. false = force save off.
                  type: boolean
                disableSurcharging:
                  description: 'Optional. When true, disable Benji Pays managed surcharging for this link. Does not affect surcharging managed by your payment gateway. When omitted: falls back to the integration configuration for that `source`, then to payment gateway settings (`source=default` leaves surcharge enabled / `false`).'
                  type: boolean
                customerEmail:
                  description: Prefills receipt email(s) on the pay page. Does not send the payment link.
                  type: string
                  maxLength: 500
              required:
              - source
              - amount
              - currency
              - name
              - reference
      responses:
        '200':
          description: Payment link created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateUnappliedPaymentLinkResponse'
        '400':
          description: Bad Request — invalid body or gateway/currency/returnUrl configuration
          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: RFC 7807 Problem Details error response
        '401':
          description: Unauthorized — invalid or missing authentication, or API access is not active for this organization (disabled or missing).
          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: RFC 7807 Problem Details error response
        '403':
          description: Forbidden — missing required OAuth scope (`organizations:payment-links:create`) and/or insufficient live mapping permission on the API key owner (e.g. `companyAdmin`). Scope and mapping are independent gates; see response `detail`.
          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: RFC 7807 Problem Details error response
                examples:
                  missingScope:
                    summary: Missing OAuth scope
                    value:
                      type: https://api.benjipays.com/problems/forbidden
                      title: Forbidden
                      status: 403
                      detail: 'Missing required scope: organizations:payment-links:create'
                      instance: /v2/payment-links/unapplied
                  insufficientMappingPermission:
                    summary: Insufficient live mapping permission (API key owner)
                    value:
                      type: https://api.benjipays.com/problems/forbidden
                      title: Forbidden
                      status: 403
                      detail: Insufficient permission for this resource
                      instance: /v2/payment-links/unapplied
        '404':
          description: Organization not found
          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: RFC 7807 Problem Details error response
        '429':
          description: Too Many Requests
          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: RFC 7807 Problem Details error response
      parameters:
      - $ref: '#/components/parameters/RequestIdHeader'
      - $ref: '#/components/parameters/CorrelationIdHeader'
      - $ref: '#/components/parameters/IdempotencyKeyHeader'
      operationId: postV2PaymentLinksUnapplied
      x-operation-id-source: derived
components:
  parameters:
    IdempotencyKeyHeader:
      name: Idempotency-Key
      in: header
      required: false
      description: 'Optional client-supplied key that makes retries safe for POST/PATCH/PUT. Scoped per actor; cached for 24 hours. Replays return the cached response with `X-Idempotency-Replayed: true`. Same key with a different body returns 409. In-flight duplicates return 429 with `Retry-After`. See the Idempotency section in the API overview.'
      schema:
        type: string
        pattern: ^[a-zA-Z0-9]+$
        minLength: 1
        maxLength: 255
      example: a1b2c3d4e5f6
    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
    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
  schemas:
    CreateAppliedPaymentLinkResponse:
      type: object
      properties:
        url:
          type: string
          description: Portal pay-now link tied to the invoice (tokenized).
        expiresAt:
          type: string
          description: ISO 8601 expiry timestamp for the payment link token.
      required:
      - url
      - expiresAt
      additionalProperties: false
      description: Applied payment link response
    CreateUnappliedPaymentLinkResponse:
      type: object
      properties:
        url:
          type: string
          description: Portal pay-now link to send to the customer.
        expiresAt:
          type: string
          description: ISO timestamp when the link expires.
      required:
      - url
      - expiresAt
      additionalProperties: false
      description: Unapplied payment link 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