CompanyPaymentConnections

Update the payment connection settings of a NIF

Updates the auto-invoicing settings of the payment connection named by {connection_id} of a company your account owns or manages.

  • Partial by field: a field you omit keeps its current value. The series fields also accept an explicit null, which clears the series and falls back to the company default for that document type. filter_config is the exception: when sent, it replaces the whole object, not just the sub-fields you included — a partial filter_config clears every filter axis you left out.
  • Read-only fields: id, provider, status, environment, external_account_id, connected_at, last_event_at and active_filters are not part of this request and are ignored if sent. status moves through the disconnect operation, never here.
  • Series: each one must exist, be active, belong to this NIF and carry a compatible document type, or the request answers 422.
patch/v1/companies/{company_id}/payment-connections/{connection_id}

Request

  • Base URL: https://app.beel.es/api
  • URL: https://app.beel.es/api/v1/companies/{company_id}/payment-connections/{connection_id}
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Idempotency key to prevent duplicates in sensitive operations.

  • Any unique client-generated string (e.g. an order id). A UUID also works but is not required
  • Allowed characters: letters, digits, _ and - (max 255 chars)
  • Retrying with the same key replays the first response when it was a success (2xx) or a server error (5xx): same status and body, plus the header Idempotency-Replay: true. After a 5xx, check whether the operation took effect before retrying with a new key
  • A 4xx is not stored: the key is released, so the corrected request can reuse it
  • Stored responses expire 24 hours after processing

The key is scoped per user and environment, and bound to the request body, so retrying after a network timeout replays the stored response instead of repeating the operation.

StatusCodeWhen
400INVALID_IDEMPOTENCY_KEYThe key breaks the format rules above.
409IDEMPOTENCY_KEY_PROCESSINGThe first request is still in flight. Wait for the Retry-After seconds (2) and retry with the same key.
409IDEMPOTENCY_KEY_MISMATCHThe key was already used with a different body. Use a new key.

Request body

auto_invoice_enabledboolean

Whether incoming charges are auto-invoiced.

event_source'PAYMENTS' | 'INVOICES' | 'BOTH'

Which family of Stripe events the connection invoices. One webhook endpoint receives everything the connected account emits; whatever falls outside the declared family is recorded as skipped, deliberately ignored, and needs no attention.

  • PAYMENTS: charges, through payment_intent.* and checkout.session.*.
  • INVOICES: Stripe's own billing documents, through invoice.*.
  • BOTH: both families, deduplicated to a single invoice per charge.

Refunds, disputes and credit notes are acted on under every value, because Stripe does not always report a correction through the family the charge came in. A correction whose charge was never invoiced is recorded as skipped and needs no action.

auto_create_customerboolean

Whether customers are created from the fiscal data the provider supplies.

send_invoice_by_emailboolean

Whether the auto-issued invoice is emailed to the payer.

simplificada_thresholdnumber double

Deprecated. No longer affects auto-invoicing: a buyer with a tax ID and full address always gets an ordinary invoice; without them, a simplified one up to 3,000 EUR. Still accepted; between 0.01 and 3000.00.

Example request

{
  "tax_inclusive_tax": {
    "type": "IVA",
    "percentage": 21,
    "regime_key": "01"
  },
  "filter_config": {
    "min_amount": 10,
    "max_amount": 5000,
    "allowed_customer_ids": [
      "cus_abc123",
      "cus_def456"
    ],
    "excluded_description_patterns": [
      ".*donation.*",
      ".*tip.*"
    ],
    "required_description_patterns": [
      ".*subscription.*"
    ],
    "disabled_categories": [
      "SUBSCRIPTION"
    ]
  }
}

Response

Connection updated

successboolean

Example response

{
  "data": {
    "id": "5f2b1c0e-9a3d-4c11-8f6e-7b0d2a4c9e13",
    "provider": "stripe",
    "external_account_id": "acct_1234567890",
    "environment": "PROD",
    "tax_inclusive_tax": {
      "type": "IVA",
      "percentage": 21,
      "regime_key": "01"
    },
    "simplificada_threshold": 400,
    "filter_config": {
      "min_amount": 10,
      "max_amount": 5000,
      "allowed_customer_ids": [
        "cus_abc123",
        "cus_def456"
      ],
      "excluded_description_patterns": [
        ".*donation.*",
        ".*tip.*"
      ],
      "required_description_patterns": [
        ".*subscription.*"
      ],
      "disabled_categories": [
        "SUBSCRIPTION"
      ]
    },
    "active_filters": [
      "amount",
      "description"
    ]
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.