---
title: "Update the payment connection settings of a NIF"
method: PATCH
path: "/v1/companies/{company_id}/payment-connections/{connection_id}"
tags: ["CompanyPaymentConnections"]
---

# Update the payment connection settings of a NIF

`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

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`.

## Headers

- `Idempotency-Key` string

## Request body

- UpdateCompanyPaymentConnectionRequest: The settings to change. A field you omit keeps its current value; the series fields and `tax_inclusive_tax` also accept an explicit `null`, which clears them.
  - `auto_invoice_enabled` boolean: 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_customer` boolean: Whether customers are created from the fiscal data the provider supplies.
  - `send_invoice_by_email` boolean: Whether the auto-issued invoice is emailed to the payer.
  - `tax_inclusive_tax` TaxInfo: Complete tax information with cross-validations: - IVA: real rates 4, 10, 21, and the temporary 2, 5 and 7.5 (see below for 0) - IGIC: 0, 3, 5, 7, 9.5, 15, 20 — here 0 is the real "Tipo Cero" - IPSI: real rates 0.5, 1, 2, 4, 8, 10 (see below for 0) - OTHER: any percentage between 0 and 100 **0 % under IVA and IPSI is not a rate, it is the exemption sentinel.** It is accepted on a line, but only together with an `exemption_reason` (exempt or non-subject operation); on its own it says nothing and the line is rejected. That is why `GET /v1/tax-types` publishes the IVA rates without 0: the legitimate way to a 0 % IVA line is through an exemption reason, which the same response also publishes. IGIC is different — its 0 % is a real legal rate (basic necessities) and needs no reason. **IVA 5 %** (the temporary rate applied from 2022 to electricity, gas and certain foodstuffs) is no longer in force for new operations. AEAT only accepts it on operations dated from 2022-07-01 to 2024-09-30: send the `operation_date` of that period, because without one the issue date decides and a line at 5 % is rejected with `422 VAT_RATE_NOT_ACCEPTED_ON_DATE`. Its equivalence surcharge pair is 0.5 up to 2022-12-31 and 0.62 from 2023-01-01. **IVA 2 % and 7.5 %** (temporary rates of the last quarter of 2024) are accepted only on operations dated from 2024-10-01 to 2024-12-31, with surcharges 0.26 and 1. Exception: when regime_key = "17" (OSS/IOSS) the invoice applies the destination country VAT instead of the Spanish one, so any percentage in the EU range [0, 27] is accepted regardless of the tax type set — including 0 without an exemption reason.
    - `type` 'IVA' | 'IGIC' | 'IPSI' | 'OTHER', required: Tax type by territory: - IVA: Iberian Peninsula and Balearic Islands (4%, 10%, 21%; 2%, 5% and 7.5% only on operations of their period) - IGIC: Canary Islands (0%, 3%, 5%, 7%, 9.5%, 15%, 20%) - IPSI: Ceuta and Melilla (0.5%, 1%, 2%, 4%, 8%, 10%) - OTHER: Configurable 0%-100% Under IVA and IPSI, 0% is not one of these rates: it is the exemption/non-subject sentinel and always travels with an `exemption_reason`. IGIC's 0% is a real rate. See `TaxInfo` for the full rules.
    - `percentage` number, required: Tax percentage
    - `regime_key` '01' | '02' | '03' | '04' | '05' | '06' | '07' | '08' | '09' | '10' | '11' | '14' | '15' | '17' | '18' | '19' | '20': Regime key according to VeriFactu regulations. Omitted, `01` (general regime) applies: - 01: General regime operation - 02: Export (IVA and IGIC; not IPSI, whose AEAT list is `01, 08, 11, 18, 19, 20`) - 03: Used goods, art, antiques (not accepted, see below) - 04: Investment gold - 05: Travel agencies - 06: Group of entities (not accepted, see below) - 07: Cash basis - 08: Operation subject to another indirect tax — IPSI or IGIC on an IVA line, IPSI or IVA on an IGIC line. It is **not** the general regime of IGIC, which is `01`. - 09: Mediating agencies - 10: Third-party collections - 11: Local rental - 14: VAT pending in certifications (not accepted, see below) - 15: VAT pending successive tract - 17: OSS and IOSS - 18: Equivalence surcharge - 19: REAGYP - 20: Simplified regime **What AEAT requires with each key** (Validaciones VERI*FACTU 3.1.3.15.6), checked on IVA and IGIC lines before the invoice is numbered. Otherwise the request is rejected with `422` and the code in brackets: - `04`: only reverse charge (an `ISP_ART_84_2_*` reason) or an exemption (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`). - `08`: only `exemption_reason: NO_SUJETA_LOCALIZACION`, at 0 % (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`). - `10`: only `exemption_reason: NO_SUJETA_ART_7_9`, on a `STANDARD` invoice whose recipient has a `nif` (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`, `REGIME_KEY_REQUIRES_STANDARD_INVOICE`, `REGIME_KEY_REQUIRES_RECIPIENT_NIF`). - `11` (IVA): a subject line only at 21 %, and no reverse charge (`REGIME_KEY_REQUIRES_VAT_RATE`, `REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`). - `06` and `14` are not accepted (`REGIME_KEY_NOT_SUPPORTED`): AEAT requires with them data the invoice does not carry (a cost-based taxable base; an operation date after the issue date and a public-administration recipient). - `03` (used goods) is not accepted (`REGIME_KEY_NOT_SUPPORTED`): under it the invoice must not show the tax separately (RD 1619/2012, art. 16.2.c), and it always does. The corrective of an invoice that already carried `03` keeps it. - `05` (travel agencies) and `07` (cash basis) are accepted, and the invoice PDF carries the mention of their regime (RD 1619/2012, art. 6.1 n and p). `07`: no reverse charge, no non-subject reason and, of the exemptions, only art. 20 or `OTRO` (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`). `GET /v1/tax-types` only offers the keys that are accepted. **One exception to "a key you send is the key you get":** when the line ends up carrying an equivalence surcharge — whether you sent `equivalence_surcharge_rate` or it was inherited from the company's tax configuration — a `01` is rewritten to `18`, because a surcharge under the general regime is fiscally incoherent. Send `equivalence_surcharge_rate: 0` explicitly to keep `01`. See `equivalence_surcharge_rate` in the invoice line for the full rules.
  - `series` UpdateCompanyPaymentConnectionSeries: Series to number auto-issued invoices in. Omit a field to keep it, send `null` to clear it and fall back to the company default series for that document type.
    - `ordinaria` string, uuid, nullable: Series for auto-issued ordinary invoices.
    - `simplificada` string, uuid, nullable: Series for auto-issued simplified invoices.
    - `rectificativa` string, uuid, nullable: Series for auto-issued corrective invoices (refunds).
  - `simplificada_threshold` number, 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.
  - `filter_config` CompanyPaymentConnectionFilters: Rules that decide which incoming charges reach auto-invoicing. Every axis is opt-in: a field left out does not filter anything. A charge filtered out produces no invoice and is recorded as skipped.
    - `min_amount` number, double: Charges below this amount are skipped.
    - `max_amount` number, double: Charges above this amount are skipped.
    - `only_mapped_customers` boolean: When true, only charges from customers already mapped to a BeeL customer are invoiced.
    - `allowed_customer_ids` string[]: Provider-side customer ids (e.g. Stripe `cus_...`) allowed through. When set, no other customer is invoiced.
    - `excluded_description_patterns` string[]: Regular expressions matched against the charge description. A charge matching any of them is skipped.
    - `required_description_patterns` string[]: Regular expressions matched against the charge description. A charge must match at least one of them to be invoiced.
    - `disabled_categories` PaymentEventCategory[]: Charge categories opted out of auto-invoicing. An empty list, or the field left out, leaves every category active.

## Response `200`

Connection updated

- CompanyPaymentConnectionResponse
  - `success` boolean
  - `data` CompanyPaymentConnection: A payment provider connection of a NIF with the settings that decide what BeeL does with each incoming charge. Credentials of the provider are never part of this document.
    - `id` string, uuid, required: Unique identifier of the connection, the `{connection_id}` that addresses it.
    - `provider` string, required: Payment provider slug (lowercase).
    - `external_account_id` string, required: Provider-side account id (e.g. Stripe `acct_...`). Read-only.
    - `external_account_name` string, nullable: Provider-side account display name, if any.
    - `environment` 'TEST' | 'PROD', required: Mode a record lives in — its Test/Live twin. It decides where invoices, customers and quota are accounted. For a company it also decides which AEAT its NIF is registered against: switching a company on in `PROD` is what registers it with the real AEAT, so `aeat_environment` is that same mode and uses this same enum.
    - `status` 'PENDING' | 'ACTIVE' | 'DISCONNECTED' | 'ERROR', required: Status of the payment provider connection. - `PENDING`: authorization opened, not completed yet - `ACTIVE`: the connection invoices incoming charges - `DISCONNECTED`: withdrawn — it no longer invoices anything - `ERROR`: the provider rejected the last call, so it needs reconnecting
    - `connected_at` string, date-time, nullable: When the connection was established. Read-only.
    - `last_event_at` string, date-time, nullable: When the last charge from the provider came in through this connection. Read-only, and a signal of **traffic**, not of success: it is stamped even when the charge is filtered out. `null` means no charge has ever arrived.
    - `auto_invoice_enabled` boolean, required: Whether incoming charges are auto-invoiced. Disconnecting the connection does not change it.
    - `event_source` 'PAYMENTS' | 'INVOICES' | 'BOTH', required: 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_customer` boolean, required: Whether customers are created from the fiscal data the provider supplies.
    - `send_invoice_by_email` boolean, required: Whether the auto-issued invoice is emailed to the payer, using the address the provider reported. A charge with no payer email is invoiced all the same and sends nothing.
    - `tax_inclusive_tax` TaxInfo: Complete tax information with cross-validations: - IVA: real rates 4, 10, 21, and the temporary 2, 5 and 7.5 (see below for 0) - IGIC: 0, 3, 5, 7, 9.5, 15, 20 — here 0 is the real "Tipo Cero" - IPSI: real rates 0.5, 1, 2, 4, 8, 10 (see below for 0) - OTHER: any percentage between 0 and 100 **0 % under IVA and IPSI is not a rate, it is the exemption sentinel.** It is accepted on a line, but only together with an `exemption_reason` (exempt or non-subject operation); on its own it says nothing and the line is rejected. That is why `GET /v1/tax-types` publishes the IVA rates without 0: the legitimate way to a 0 % IVA line is through an exemption reason, which the same response also publishes. IGIC is different — its 0 % is a real legal rate (basic necessities) and needs no reason. **IVA 5 %** (the temporary rate applied from 2022 to electricity, gas and certain foodstuffs) is no longer in force for new operations. AEAT only accepts it on operations dated from 2022-07-01 to 2024-09-30: send the `operation_date` of that period, because without one the issue date decides and a line at 5 % is rejected with `422 VAT_RATE_NOT_ACCEPTED_ON_DATE`. Its equivalence surcharge pair is 0.5 up to 2022-12-31 and 0.62 from 2023-01-01. **IVA 2 % and 7.5 %** (temporary rates of the last quarter of 2024) are accepted only on operations dated from 2024-10-01 to 2024-12-31, with surcharges 0.26 and 1. Exception: when regime_key = "17" (OSS/IOSS) the invoice applies the destination country VAT instead of the Spanish one, so any percentage in the EU range [0, 27] is accepted regardless of the tax type set — including 0 without an exemption reason.
      - `type` 'IVA' | 'IGIC' | 'IPSI' | 'OTHER', required: Tax type by territory: - IVA: Iberian Peninsula and Balearic Islands (4%, 10%, 21%; 2%, 5% and 7.5% only on operations of their period) - IGIC: Canary Islands (0%, 3%, 5%, 7%, 9.5%, 15%, 20%) - IPSI: Ceuta and Melilla (0.5%, 1%, 2%, 4%, 8%, 10%) - OTHER: Configurable 0%-100% Under IVA and IPSI, 0% is not one of these rates: it is the exemption/non-subject sentinel and always travels with an `exemption_reason`. IGIC's 0% is a real rate. See `TaxInfo` for the full rules.
      - `percentage` number, required: Tax percentage
      - `regime_key` '01' | '02' | '03' | '04' | '05' | '06' | '07' | '08' | '09' | '10' | '11' | '14' | '15' | '17' | '18' | '19' | '20': Regime key according to VeriFactu regulations. Omitted, `01` (general regime) applies: - 01: General regime operation - 02: Export (IVA and IGIC; not IPSI, whose AEAT list is `01, 08, 11, 18, 19, 20`) - 03: Used goods, art, antiques (not accepted, see below) - 04: Investment gold - 05: Travel agencies - 06: Group of entities (not accepted, see below) - 07: Cash basis - 08: Operation subject to another indirect tax — IPSI or IGIC on an IVA line, IPSI or IVA on an IGIC line. It is **not** the general regime of IGIC, which is `01`. - 09: Mediating agencies - 10: Third-party collections - 11: Local rental - 14: VAT pending in certifications (not accepted, see below) - 15: VAT pending successive tract - 17: OSS and IOSS - 18: Equivalence surcharge - 19: REAGYP - 20: Simplified regime **What AEAT requires with each key** (Validaciones VERI*FACTU 3.1.3.15.6), checked on IVA and IGIC lines before the invoice is numbered. Otherwise the request is rejected with `422` and the code in brackets: - `04`: only reverse charge (an `ISP_ART_84_2_*` reason) or an exemption (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`). - `08`: only `exemption_reason: NO_SUJETA_LOCALIZACION`, at 0 % (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`). - `10`: only `exemption_reason: NO_SUJETA_ART_7_9`, on a `STANDARD` invoice whose recipient has a `nif` (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`, `REGIME_KEY_REQUIRES_STANDARD_INVOICE`, `REGIME_KEY_REQUIRES_RECIPIENT_NIF`). - `11` (IVA): a subject line only at 21 %, and no reverse charge (`REGIME_KEY_REQUIRES_VAT_RATE`, `REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`). - `06` and `14` are not accepted (`REGIME_KEY_NOT_SUPPORTED`): AEAT requires with them data the invoice does not carry (a cost-based taxable base; an operation date after the issue date and a public-administration recipient). - `03` (used goods) is not accepted (`REGIME_KEY_NOT_SUPPORTED`): under it the invoice must not show the tax separately (RD 1619/2012, art. 16.2.c), and it always does. The corrective of an invoice that already carried `03` keeps it. - `05` (travel agencies) and `07` (cash basis) are accepted, and the invoice PDF carries the mention of their regime (RD 1619/2012, art. 6.1 n and p). `07`: no reverse charge, no non-subject reason and, of the exemptions, only art. 20 or `OTRO` (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`). `GET /v1/tax-types` only offers the keys that are accepted. **One exception to "a key you send is the key you get":** when the line ends up carrying an equivalence surcharge — whether you sent `equivalence_surcharge_rate` or it was inherited from the company's tax configuration — a `01` is rewritten to `18`, because a surcharge under the general regime is fiscally incoherent. Send `equivalence_surcharge_rate: 0` explicitly to keep `01`. See `equivalence_surcharge_rate` in the invoice line for the full rules.
    - `series` CompanyPaymentConnectionSeries: Invoice series the connection numbers its auto-issued invoices in, one per document type. A series left out falls back to the company default series for that type.
      - `ordinaria` string, uuid, nullable: Series for auto-issued ordinary invoices.
      - `simplificada` string, uuid, nullable: Series for auto-issued simplified invoices.
      - `rectificativa` string, uuid, nullable: Series for auto-issued corrective invoices (refunds).
    - `simplificada_threshold` number, 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 and returned.
    - `filter_config` CompanyPaymentConnectionFilters: Rules that decide which incoming charges reach auto-invoicing. Every axis is opt-in: a field left out does not filter anything. A charge filtered out produces no invoice and is recorded as skipped.
      - `min_amount` number, double: Charges below this amount are skipped.
      - `max_amount` number, double: Charges above this amount are skipped.
      - `only_mapped_customers` boolean: When true, only charges from customers already mapped to a BeeL customer are invoiced.
      - `allowed_customer_ids` string[]: Provider-side customer ids (e.g. Stripe `cus_...`) allowed through. When set, no other customer is invoiced.
      - `excluded_description_patterns` string[]: Regular expressions matched against the charge description. A charge matching any of them is skipped.
      - `required_description_patterns` string[]: Regular expressions matched against the charge description. A charge must match at least one of them to be invoiced.
      - `disabled_categories` PaymentEventCategory[]: Charge categories opted out of auto-invoicing. An empty list, or the field left out, leaves every category active.
    - `active_filters` string[], required: Filter axes that currently hold a value, so you can tell a connection that filters nothing from one that does without reading every field. An empty list means every charge reaches auto-invoicing. - `amount`: `min_amount` or `max_amount` is set. - `customer`: `only_mapped_customers` is on or `allowed_customer_ids` has entries. - `description`: `excluded_description_patterns` or `required_description_patterns` has entries. - `category`: `disabled_categories` has entries.
  - `meta` ResponseMeta
    - `timestamp` string, date-time
    - `request_id` string

## Other responses

- `401`: Missing or invalid authentication. Like every other error, `message`/`detail` is localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English when the header is missing or asks for none of those.
- `403`: Your account does not own or manage this company. The same answer is given for a NIF that does not exist. Nothing is updated. That case answers `error.code` `ACTIVE_COMPANY_NOT_ACCESSIBLE`.
- `404`: `CONNECTION_NOT_FOUND` — no connection of this NIF carries this `{connection_id}`. It speaks of the connection, never of the NIF: a NIF you cannot reach answers `403`, while a connection of another NIF answers this same `404` so that naming it reveals nothing.
- `422`: A setting is not acceptable, and nothing is updated. Branch on `error.code`: - `CONNECTION_SERIE_NOT_FOUND` — a series in `series` does not exist or belongs to another NIF. - `CONNECTION_SERIE_INACTIVE` — the series exists but is inactive. - `CONNECTION_SERIE_TIPO_INCOMPATIBLE` — the series' document type does not fit the slot it was sent for. - `FILTER_PATTERNS_TOO_MANY` — more than 20 patterns in one of `excluded_description_patterns` or `required_description_patterns`. - `FILTER_PATTERN_TOO_LONG` — a pattern over 200 characters. - `FILTER_PATTERN_INVALID` — a pattern that is not a valid regular expression. - `FILTER_CATEGORY_NOT_ACTIONABLE` — `disabled_categories` names `REFUND` or `CREDIT_NOTE`, which the rules never evaluate, so disabling them would do nothing. - `VALIDATION_ERROR` — a field breaks its declared constraint.
- `429`: Rate limit exceeded. `RATE_LIMIT_EXCEEDED` when the request rate of your credential is over its limit; `TOO_MANY_REQUESTS` when an email the operation sends is held back because too many went out to that recipient in a short time. Either way, retry after the `Retry-After` seconds. `QUOTA_EXCEEDED` is the other `429`: the operation would go over a quota of your plan for the current period (issued invoices, for instance). Retrying does not help until the quota resets or the plan changes. `error.details` carries `feature_code`, `current_usage`, `quota_limit` and `reset_date`, and `RateLimit-Reset` the seconds until the reset when it is known.
- `500`: Internal server error
- `default`: Any status code the operation does not list above. Every operation declares it, so a generated client always has a branch to fall into and never loses the cause of a failure it did not anticipate. This is where the transport-level answers land — `405`, `406`, `415` and `429` — together with any status a future version of the API starts returning. All of them carry the same error envelope as the codes listed explicitly, so `error.code` is what tells them apart: switching on the status code alone is not enough. See «Transport-level errors» in the API description for when each one is produced. A `402` carrying `SUBSCRIPTION_REQUIRED` lands here when the account has no active subscription. `error.details` says why and what to do: `current_status` (absent if it never had one), `required_permission` and `action`. A `503` carrying `SERVICE_UNAVAILABLE` lands here too, with a `Retry-After` header: a dependency of BeeL itself (the database, the email provider) was momentarily unavailable and nothing was done. Retry after those seconds. A `502` carrying `EXTERNAL_SERVICE_ERROR` also lands here: an outbound integration the operation depends on failed or did not answer in time. It is a transient condition — retry with the same `Idempotency-Key` where the operation accepts one. One exception to the envelope: a failure of the network edge that never reaches the application (`502`, `503`, `504`, `524`) is generated by Cloudflare and its body is not BeeL's — it may not even be JSON. Treat those as "no answer", and retry.

---

[API](https://skmtc.dev/beel/apis/beel-public-api.md) · [All operations](https://skmtc.dev/beel/apis/beel-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/beel/apis/beel-public-api/revisions/ffbc0ae31f79?raw)