NewProvince is only required for addresses in Spain
BeeL
Get startedMulti-NIFVeriFactuRulesStripeAPI referenceChangelog
Payment Connections

List the payment connections of a NIF

Scopepayment-connections:read

Returns the payment provider connections of a company your account owns or manages, with the provider-side account each one points at and its status. Use it to check whether a NIF you provisioned has completed its connection.

  • A NIF with no connections: answers 200 with an empty list.
  • environment: Test and Live connections are independent, so only the ones living in the mode of the key you ask with are returned; this field states which.

Closed catalogue. A NIF is not limited to one connection per provider: within a single environment it may hold several of the same provider, one per external account. What is unique is the external account itself — one live connection per provider, environment and external account. The set is still bounded and unpaginated: the collection carries no pagination and takes no page/limit, and every response holds the whole set for the environment of the key you ask with.

GET
/v1/companies/{company_id}/payment-connections

Authorization

AuthorizationBearer <token>

Keys are prefixed beel_sk_, and each one carries the scopes it was created with: a key short of the scope an operation needs is answered 403. The scope an operation requires is shown next to its title, and the full catalogue lives in the Scopes reference.

Keys are created from the BeeL dashboard. They are secret credentials: do not share them or commit them to source control.

In: header

Path Parameters

company_idstring

Unique identifier (UUID) of the company the operation acts on — its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the BeeL-Active-Company header plays no part. A company you do not reach answers 403, and so does a company that does not exist, so the existence of a company in another account is never disclosed.

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/payment-connections"
{
  "success": true,
  "data": {
    "connections": [
      {
        "id": "5f2b1c0e-9a3d-4c11-8f6e-7b0d2a4c9e13",
        "provider": "stripe",
        "external_account_id": "acct_1234567890",
        "external_account_name": "string",
        "environment": "PROD",
        "status": "PENDING",
        "connected_at": "2019-08-24T14:15:22Z"
      }
    ]
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The parameter 'invoice_id' has an invalid type. Expected: UUID.",
    "details": {
      "field": "invoice_id",
      "invalid_value": "deliveries",
      "expected_format": "UUID"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided data is not valid",
    "details": {
      "field": "specific error message"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  },
  "type": "https://docs.beel.es/errors/INVOICE_NO_LINES",
  "title": "INVOICE_NO_LINES",
  "detail": "The invoice must have at least one line",
  "instance": "/v1/invoices/abc-123"
}
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again in 60 seconds."
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_MEDIA_TYPE",
    "message": "Unsupported media type: text/plain. Supported: application/json"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Open an authorization to connect a payment provider POST

Opens an authorization session so the holder of a company your account **manages** can connect a payment provider (`stripe`), and returns the `authorization_url` where they authorize it. - **`return_url`:** once the holder authorizes, BeeL's callback finalizes the connection and redirects back to the `return_url` of your portal, if you supplied one, with the parameters described under `return_url`. - **When the connection appears:** it is created only when the holder authorizes, so it does not appear in `GET /v1/companies/{company_id}/payment-connections` until then. It is sealed under the NIF in the path, so auto-invoicing issues under that NIF. - **The NIF must be activated in the mode of your API key** (`beel_sk_test_*` → Test, `beel_sk_live_*` → Live); otherwise the request answers `400` `COMPANY_NOT_ACTIVATED_IN_ENVIRONMENT` and no `authorization_url` is issued, because without activation there is no invoice series or tax configuration to invoice with. Test and Live activations are independent — a NIF activated in one mode still needs activating in the other. - **One provider account, one NIF:** a provider account (`acct_...`) can be connected to a single NIF across the whole platform. Authorizing the same provider account from a second NIF does not move it: the callback fails with `OAUTH_ACCOUNT_CONNECTED_TO_OTHER_COMPANY`, and the existing connection keeps invoicing under the NIF it was sealed with. To move it, first `DELETE /v1/companies/{company_id}/payment-connections/{connection_id}` on the NIF that holds it, then open a new authorization on the NIF you want it under.

Update the payment connection settings of a NIF PATCH

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