CompanyPaymentConnections

Open an authorization to connect a payment provider

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.
post/v1/companies/{company_id}/payment-connections/authorizations

Request

  • Base URL: https://app.beel.es/api
  • URL: https://app.beel.es/api/v1/companies/{company_id}/payment-connections/authorizations
  • 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

providerstring required

Payment provider slug in lowercase. Currently only stripe (Stripe Connect) is operative; woocommerce and shopify are reserved for future providers. Any other value answers 422.

return_urlstring

URL of your portal to redirect the account holder back to after the OAuth callback completes. Must be an absolute https:// URL. On success BeeL appends status=success, provider (slug), company_id, connection_id and account (the provider account id, e.g. acct_...). On error it appends status=error, provider and message, always a stable uppercase error code: OAUTH_STATE_INVALID (the authorization is unknown, expired or already used), OAUTH_TOKEN_EXCHANGE_FAILED (the provider rejected the code exchange), ACCESS_DENIED (the account holder declined at the provider), OAUTH_ACCOUNT_CONNECTED_TO_OTHER_COMPANY (the provider account is already connected to another NIF; disconnect it there first), PROVIDER_ERROR (any other provider-reported failure) or OAUTH_UNEXPECTED. When omitted, the callback redirects to BeeL's default integrations screen. A return_url that is not an absolute https:// URL with a host is rejected up front with 422 PAYMENT_RETURN_URL_INVALID, and no authorization is opened.

Example request

{
  "provider": "stripe",
  "return_url": "https://your-platform.example.com/connections/stripe/return"
}

Response

Authorization URL generated

successboolean

Example response

{
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Changes

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