# Mark a payment event as manually resolved API Reference Marks a payment event as resolved outside BeeL, for example when the invoice was issued through another tool or the situation was otherwise handled by hand. The event leaves the events that need action without generating any invoice. The operation applies to the whole payment the event belongs to. Its scope is every active event of the connection that shares the payment identity of the event named in the request: when the event carries a payment identifier (`external_payment_id`), every event with that same identifier, whatever its kind (the sale, its failed attempts, its refunds); otherwise, when it carries a source object (`source_object_id`, such as a credit note or a dispute), every event with that same source object; otherwise, the event alone. Within that scope, the events that need action (the same criterion as the `needs_action` filter) and are eligible are resolved together, in a single transaction; a failed event still pending automatic retry is resolved as well, so that no retry is attempted for a payment the caller has declared handled elsewhere. Events that do not need action — for instance an event still in `RECEIVED` state that has not stalled — remain unchanged. The response carries the event named in the request. - **Eligible events:** only events in `FAILED`, `SKIPPED` or `RECEIVED` can be resolved; if the event named in the request is not eligible, the request returns `400`. - **Terminal:** a resolved event cannot be retried afterwards. ## POST /v1/companies/{company_id}/payment-connections/{connection_id}/events/{event_id}/resolve **Mark a payment event as manually resolved** Marks a payment event as resolved outside BeeL, for example when the invoice was issued through another tool or the situation was otherwise handled by hand. The event leaves the events that need action without generating any invoice. The operation applies to the whole payment the event belongs to. Its scope is every active event of the connection that shares the payment identity of the event named in the request: when the event carries a payment identifier (`external_payment_id`), every event with that same identifier, whatever its kind (the sale, its failed attempts, its refunds); otherwise, when it carries a source object (`source_object_id`, such as a credit note or a dispute), every event with that same source object; otherwise, the event alone. Within that scope, the events that need action (the same criterion as the `needs_action` filter) and are eligible are resolved together, in a single transaction; a failed event still pending automatic retry is resolved as well, so that no retry is attempted for a payment the caller has declared handled elsewhere. Events that do not need action — for instance an event still in `RECEIVED` state that has not stalled — remain unchanged. The response carries the event named in the request. - **Eligible events:** only events in `FAILED`, `SKIPPED` or `RECEIVED` can be resolved; if the event named in the request is not eligible, the request returns `400`. - **Terminal:** a resolved event cannot be retried afterwards. ### Authentication Accepts any of: - `ApiKeyAuth` (HTTP bearer, token format `beel_sk_*`) ### Parameters - **company_id** (required) in path `string`: Unique identifier (UUID) of the company the events belong to — 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. - **connection_id** (required) in path `string`: Unique identifier (UUID) of the payment connection the operation acts on, as returned by `GET /v1/companies/{company_id}/payment-connections`. A NIF can hold several connections of the same provider, so the provider slug alone does not name one. A connection of another NIF answers `404`, exactly like one that does not exist. - **event_id** (required) in path `string`: Identifier of the payment event, as returned by the list operation. - **Idempotency-Key** (optional) in header `string`: 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 other than 503, check whether the operation took effect before retrying with a **new** key - After a `503`, retry first with the **same** key. If the response carries `Idempotency-Replay: true`, the operation may have taken effect: check the resource before using a new key. Without that header, the retry runs the operation once - 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. | Status | Code | When | |---|---|---| | `400` | `INVALID_IDEMPOTENCY_KEY` | The key breaks the format rules above. | | `409` | `IDEMPOTENCY_KEY_PROCESSING` | The first request is still in flight. Wait for the `Retry-After` seconds (2) and retry with the same key. | | `409` | `IDEMPOTENCY_KEY_MISMATCH` | The key was already used with a **different** body. Use a new key. | ### Responses #### 200: Event marked as resolved **Content `application/json`:** - **success** `boolean`: No description - **data** `ManagedPaymentEvent`: A payment event of a managed NIF's connection (curated subset). - **meta** `ResponseMeta` #### 400: The event state does not allow resolving it (`EVENT_INVALID_STATUS_FOR_RESOLVE`) — it is already invoiced or already resolved. **Content `application/json`:** - **success** (required) `boolean`: No description (example: false) - **error** (required) `ErrorDetail` - **meta** `ResponseMeta` - **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES") - **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES") - **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line") - **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123") #### 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. **Content `application/json`:** - **success** (required) `boolean`: No description (example: false) - **error** (required) `ErrorDetail` - **meta** `ResponseMeta` - **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES") - **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES") - **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line") - **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123") **Example:** ```json { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Authentication is required to access this resource" }, "meta": { "timestamp": "2025-01-15T10:30:00Z", "request_id": "4bf92f3577b34da6a3ce929d0e0e4736" } } ``` #### 403: Your account does not own or manage this company. The same answer is given for a NIF that does not exist. That case answers `error.code` `ACTIVE_COMPANY_NOT_ACCESSIBLE`. **Content `application/json`:** - **success** (required) `boolean`: No description (example: false) - **error** (required) `ErrorDetail` - **meta** `ResponseMeta` - **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES") - **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES") - **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line") - **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123") #### 404: `CONNECTION_NOT_FOUND` when no connection of this NIF carries this `{connection_id}`; `EVENT_NOT_FOUND` when the connection is yours but the event is not its own. Both answer alike to an event that does not exist: the `404` speaks of the connection and the event, never of the NIF. A NIF you cannot reach answers `403`; a connection of another NIF answers this `404`, so naming it reveals nothing. **Content `application/json`:** - **success** (required) `boolean`: No description (example: false) - **error** (required) `ErrorDetail` - **meta** `ResponseMeta` - **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES") - **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES") - **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line") - **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123") **Example:** ```json { "success": false, "error": { "code": "EVENT_NOT_FOUND", "message": "Payment event not found" }, "meta": { "timestamp": "2025-01-15T10:30:00Z", "request_id": "4bf92f3577b34da6a3ce929d0e0e4736" } } ``` #### 422: Unprocessable entity - validation or business rule error **Content `application/json`:** - **success** (required) `boolean`: No description (example: false) - **error** (required) `ErrorDetail` - **meta** `ResponseMeta` - **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES") - **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES") - **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line") - **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123") **Example:** ```json { "success": false, "error": { "code": "UNPROCESSABLE_ENTITY", "message": "Data cannot be processed", "details": { "field": "Specific error description" } }, "meta": { "timestamp": "2025-01-15T10:30:00Z", "request_id": "4bf92f3577b34da6a3ce929d0e0e4736" } } ``` #### 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. **Headers:** - `Retry-After` `integer`: Seconds until the rate limit resets - `RateLimit-Limit` `integer`: Maximum requests allowed in the window - `RateLimit-Remaining` `integer`: Remaining requests in the current window - `RateLimit-Reset` `integer`: Seconds until the current window resets **Content `application/json`:** - **success** (required) `boolean`: No description (example: false) - **error** (required) `ErrorDetail` - **meta** `ResponseMeta` - **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES") - **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES") - **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line") - **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123") **Example:** ```json { "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" } } ``` #### 500: Internal server error **Content `application/json`:** - **success** (required) `boolean`: No description (example: false) - **error** (required) `ErrorDetail` - **meta** `ResponseMeta` - **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES") - **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES") - **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line") - **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123") **Example:** ```json { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" }, "meta": { "timestamp": "2025-01-15T10:30:00Z", "request_id": "4bf92f3577b34da6a3ce929d0e0e4736" } } ``` #### 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. **Content `application/json`:** - **success** (required) `boolean`: No description (example: false) - **error** (required) `ErrorDetail` - **meta** `ResponseMeta` - **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES") - **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES") - **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line") - **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123") **Example:** ```json { "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" } } ``` --- # Related Schema Definitions ## ManagedPaymentEventResponse - **success** `boolean`: No description - **data** `ManagedPaymentEvent`: A payment event of a managed NIF's connection (curated subset). - **meta** `ResponseMeta` ## ManagedPaymentEvent A payment event of a managed NIF's connection (curated subset). - **id** (required) `string` (uuid): Identifier of the payment event. - **provider** (required) `string`: Payment provider slug (lowercase). (example: "stripe") - **event_type** (required) `string`: Raw event name as the provider emitted it. Preserved verbatim so you can trace the event back on the provider's side. Not filterable — filter by `event_kind`. (example: "payment_intent.succeeded") - **event_kind** (required): What the event is about, once `event_type` has been classified. This is the value the `event_kind` filter takes, so what you read here you can ask for again. (example: "PAYMENT_COMPLETED") - **external_event_id** (required) `string`: Provider-side event identifier. (example: "evt_1234567890") - **external_payment_id** `string`: Canonical identity of the payment at the provider. On Stripe this is the PaymentIntent id (`pi_…`); for a charge without a PaymentIntent, the Charge id (`ch_…`); for a Stripe invoice paid outside Stripe, the payment record id (`pr_…`). Every event of the same payment carries the same value and can be grouped by it. Null while the identity is not yet resolved. To trace the event back to the object that delivered it, use `source_object_id`. (example: "pi_1234567890") - **source_object_id** `string`: Provider object that delivered this event (`in_…`, `cs_…`, `ch_…`, `pi_…`). Use it to open the originating invoice, checkout session or charge at the provider. It is an audit trail only: it never identifies the payment — `external_payment_id` does. (example: "in_1234567890") - **currency** `string`: ISO 4217 currency of the event. Absent on an event that moves no money — a failed intent, or a provider notice we do not classify — and then `amount` is absent too. (example: "EUR") - **amount** `number`: Amount the event carries. Absent whenever `currency` is: the two travel together, so an amount never arrives without the currency that gives it meaning. (example: 150) - **fee_amount** `number`: Provider fee, when reported. - **net_amount** `number`: Amount net of the provider fee, when reported. - **category**: Which product line the money came from, resolved when the event was processed. Not the same as `event_kind`: that one says what happened, this one says where it came from. `null` when the event does not fall in any category, or when it predates the field. - **money_returned** `boolean`: Whether money actually went back to the payer through the provider. Always `true` for a refund. For a credit note it is `true` only when the note settles provider refunds: a note credited against an unpaid invoice, or settled outside the provider, corrects the same amount without moving any money. `null` when the concept does not apply, as on a charge. - **customer_email** `string`: Payer email reported by the provider. - **customer_name** `string`: Payer name reported by the provider. - **status** (required) `PaymentEventStatus`: Processing status of a payment event. - RECEIVED: queued, awaiting processing - PROCESSING: in flight - PROCESSED: invoice was created (`invoice_id` is set) - FAILED: processing failed (see failure_reason / failure_message) - SKIPPED: filtered out by user rules (see skip_reason) - MANUALLY_RESOLVED: operator marked it as resolved outside BeeL — terminal - **invoice_id** `string` (uuid): The invoice currently in force for this payment: when the simplified invoice it generated was exchanged, the full invoice that replaced it. `null` when the event produced no invoice. - **invoice_number** `string`: Number of the invoice in `invoice_id`. `null` while that invoice is still a draft — a draft has no number yet — and `null` when the event produced no invoice. (example: "2026/0042") - **failure_category**: High-level cause of the failure, when the event did not complete. Same vocabulary the `failure_category` filter takes. - **failure_reason** `string`: Stable failure code you can branch on. (example: "MISSING_DEFAULT_SERIES") - **failure_message** `string`: Readable explanation of the failure, in the language of the request. - **needs_action** (required) `boolean`: Whether the event did not complete and is still worth acting on. Events that failed for reasons outside your control are excluded. - **outcome** (required) `PaymentEventOutcome`: What this event means for its payment. Branch on this value instead of deriving it from `status` and `failure_reason`. - `INVOICED`: an invoice was generated from the event (`invoice_id` is set) - `IN_PROGRESS`: the payment can still change, because the event is being processed or retried, or the payer has yet to pay - `NOT_INVOICED`: closed without an invoice and with nothing for you to do, for example a zero-amount payment, or a payment settled from the payer's balance - `RESOLVED`: marked as resolved outside BeeL - `INCIDENT`: needs your action (`needs_action` is `true`) - `NO_CHANGE`: the event does not change the tax position of the payment, such as a refund that did not complete, a failed payment attempt, an event type BeeL does not handle, or a dispute settled in your favour `INCIDENT` takes precedence over the rest, then `INVOICED`. - **draft_available** (required) `boolean`: Whether a draft invoice can be generated from this event. When `false`, the draft operation would be rejected. - **retry_available** (required) `boolean`: Whether retrying this event would be accepted right now. Do not derive it from `status`: a skipped event may still be recoverable, and a failed one with no retries left is not. - **discard_available** (required) `boolean`: Whether this event can be discarded — taken out of the list. When `false`, the discard operation would be rejected. An event that is `PROCESSED` or `PROCESSING` cannot be discarded: it has (or is about to have) an invoice that already went through VeriFactu, and hiding it would break the audit trail. Do not derive it from `status`: read this flag. Already-discarded events keep the flag they would have — what applies to them is restore, not discard. - **retry_count** (required) `integer`: Retries charged to the event: those that ended in an outcome attributable to it. A retry that failed for a transient cause outside the event is not counted. - **received_at** (required) `string` (date-time): When the event was received. - **processed_at** `string` (date-time): When processing of the event finished. - **description** `string`: Charge description as the provider reported it. It is what the description filters of the connection match against, so it is what makes them auditable. - **payment_method**: How the charge was paid, when the provider reported it. `null` means the provider did not report a method for this event. (example: "CARD") - **discarded** (required) `boolean`: Whether the event was discarded (soft-deleted) and is hidden by default. - **discarded_at** `string` (date-time): When the event was discarded, when it is. ## ResponseMeta - **timestamp** `string` (date-time): No description (example: "2025-01-15T10:30:00Z") - **request_id** `string`: No description (example: "4bf92f3577b34da6a3ce929d0e0e4736") ## ErrorResponse Error response shared by all BeeL. APIs. The payload carries **two contracts at once** (additive, non-breaking): - **Legacy** (`success`, `error.{code,message,details}`, `meta`) — kept intact for existing consumers. - **RFC 9457** (`type`, `title`, `detail`, `instance`) — new fields for integrators following Problem Details for HTTP APIs. The `type` URI is the stable, shareable link to the error's documentation page (e.g. `https://docs.beel.es/errors/{code}`). Future migration: the legacy fields will be deprecated via `Deprecation`/`Sunset` headers after a sufficient adoption window, and the response Content-Type will move to `application/problem+json`. - **success** (required) `boolean`: No description (example: false) - **error** (required) `ErrorDetail` - **meta** `ResponseMeta` - **type** `string` (uri): Stable URI that identifies the problem type and where the integrator will find its documentation. (example: "https://docs.beel.es/errors/INVOICE_NO_LINES") - **title** `string`: Short summary of the problem type. Stable between occurrences of the same `type`. (example: "INVOICE_NO_LINES") - **detail** `string`: Specific message for this occurrence, localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English. Matches the legacy `error.message`. (example: "The invoice must have at least one line") - **instance** `string` (uri-reference): URI that identifies the specific occurrence of the problem — typically the path of the affected resource. (example: "/v1/invoices/abc-123") ## ErrorDetail - **code** (required) `string`: No description (example: "VALIDATION_ERROR") - **message** (required) `string`: No description (example: "The provided data is not valid") - **details** `object`: No description (example: {"field":"specific error message"}) ## PaymentEventStatus Processing status of a payment event. - RECEIVED: queued, awaiting processing - PROCESSING: in flight - PROCESSED: invoice was created (`invoice_id` is set) - FAILED: processing failed (see failure_reason / failure_message) - SKIPPED: filtered out by user rules (see skip_reason) - MANUALLY_RESOLVED: operator marked it as resolved outside BeeL — terminal Type: `string` — one of: RECEIVED, PROCESSING, PROCESSED, FAILED, SKIPPED, MANUALLY_RESOLVED ## PaymentEventOutcome What this event means for its payment. Branch on this value instead of deriving it from `status` and `failure_reason`. - `INVOICED`: an invoice was generated from the event (`invoice_id` is set) - `IN_PROGRESS`: the payment can still change, because the event is being processed or retried, or the payer has yet to pay - `NOT_INVOICED`: closed without an invoice and with nothing for you to do, for example a zero-amount payment, or a payment settled from the payer's balance - `RESOLVED`: marked as resolved outside BeeL - `INCIDENT`: needs your action (`needs_action` is `true`) - `NO_CHANGE`: the event does not change the tax position of the payment, such as a refund that did not complete, a failed payment attempt, an event type BeeL does not handle, or a dispute settled in your favour `INCIDENT` takes precedence over the rest, then `INVOICED`. Type: `string` — one of: INVOICED, IN_PROGRESS, NOT_INVOICED, RESOLVED, INCIDENT, NO_CHANGE --- Full OpenAPI spec: https://docs.beel.es/api/openapi