List a NIF's payment connections
Scopepayment-connections:readLists the payment provider connections of a NIF (company) that your account owns or manages. Use it to check whether a NIF you provisioned has completed its connection.
API Key authentication.
Format: Authorization: Bearer beel_sk_<key>
Scopes: API Keys use the same scopes as OAuth2 tokens. Each key is created with
specific scopes that limit which endpoints it can access. The required scope for each
endpoint is documented in the operation's security section under OAuth2.
Obtaining Keys: API Keys are managed from the BeeL dashboard
Security: API Keys are secret credentials. Do not share them or store them in source code
In: header
Path Parameters
NIF (company) the operation acts on. 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 NIF you do not reach answers 403, and so does a NIF that does not exist, so the existence of a NIF in another account is never disclosed.
uuidResponse Body
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": [
{
"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": "UNAUTHORIZED",
"message": "Authentication required"
},
"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": "La factura debe tener al menos una línea",
"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"
}
}Open an authorization to connect a payment provider POST
Opens an authorization session so the holder of a NIF (company) your platform **manages** can connect a payment provider (`stripe`), white-label by API. Returns an `authorization_url` where the holder authorizes the connection. After authorization, BeeL's callback finalizes the connection and redirects back to the `return_url` of your portal (if provided) with rich params (see `return_url`). The connection itself is created only once the holder authorizes, so it appears in `GET /v1/companies/{company_id}/payment-connections` afterwards, not before — which is why this is a sibling sub-resource and not a `POST` on the collection. The connection is sealed under the NIF's holder, so the auto-invoicing runs under the correct NIF. The NIF must be **activated in the mode of your API key** (`beel_sk_test_*` → Test, `beel_sk_live_*` → Live). Opening an authorization on a NIF that is not activated in that mode returns `400` with code `COMPANY_NOT_ACTIVATED_IN_ENVIRONMENT` and no `authorization_url`: activation is what creates the invoice series and tax configuration, so without it every incoming charge would be skipped instead of invoiced. Test and Live activations are independent — a NIF live in one mode still needs activating in the other.
Disconnect a NIF's payment provider DELETE
Disconnects the payment provider connection (`stripe`) of a NIF (company) that your account **owns or manages**. BeeL deletes the stored credentials and auto-invoicing stops at once: charges arriving afterwards are ignored and produce no invoice. Already-issued invoices are not affected. The authorization the holder granted at the provider is **not** revoked on the provider's side. To withdraw it, the holder must remove BeeL's access from the provider's own dashboard (in Stripe, *Settings → Connected applications*).