Newchaining_hash leaves the documentation
BeeL
Get StartedMulti-NIFVeriFactuStripeAPI ReferenceChangelog
Payment Events

Discard a payment event

Scopepayment-connections:write

Removes a payment event from the default list (soft delete). The event stays in the audit trail and can be brought back with the restore operation.

The operation applies to the whole payment the event belongs to. Its scope is every active, eligible 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. All of them are discarded together, in a single transaction and with the same deleted_at timestamp. Events that are not eligible remain unchanged, and so do events still in RECEIVED state other than the one named in the request: they have not been processed yet and are left for processing. The response carries the event named in the request.

  • Eligible events: an event already linked to an issued invoice, or currently being processed, cannot be discarded; the request returns 400.
POST
/v1/companies/{company_id}/payment-connections/{connection_id}/events/{event_id}/discard

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

Formatuuid
connection_idstring

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.

Formatuuid
event_idstring

Identifier of the payment event, as returned by the list operation.

Formatuuid

Header Parameters

Idempotency-Key?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)
  • If the same key is sent twice, the result of the first operation is returned
  • Keys 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 and retry with the same key.
409IDEMPOTENCY_KEY_MISMATCHThe key was already used with a different body. Use a new key.
Match^[a-zA-Z0-9_-]+$
Lengthlength <= 255

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/payment-connections/497f6eca-6276-4993-bfeb-53cbbbba6f08/events/497f6eca-6276-4993-bfeb-53cbbbba6f08/discard"
{
  "success": true,
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "provider": "stripe",
    "event_type": "payment_intent.succeeded",
    "event_kind": "PAYMENT_COMPLETED",
    "external_event_id": "evt_1234567890",
    "external_payment_id": "pi_1234567890",
    "source_object_id": "in_1234567890",
    "currency": "EUR",
    "amount": 150,
    "fee_amount": 0,
    "net_amount": 0,
    "category": "DIRECT_PAYMENT",
    "money_returned": true,
    "customer_email": "string",
    "customer_name": "string",
    "status": "RECEIVED",
    "invoice_id": "f4c4edb8-11e0-4b33-bcc1-482dc59ebb32",
    "invoice_number": "2026/0042",
    "failure_category": "USER_CONFIGURATION",
    "failure_reason": "MISSING_DEFAULT_SERIES",
    "failure_message": "string",
    "needs_action": true,
    "draft_available": true,
    "retry_available": true,
    "discard_available": true,
    "retry_count": 0,
    "received_at": "2019-08-24T14:15:22Z",
    "processed_at": "2019-08-24T14:15:22Z",
    "description": "string",
    "payment_method": "CARD",
    "discarded": true,
    "discarded_at": "2019-08-24T14:15:22Z"
  },
  "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": "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": "La factura debe tener al menos una línea",
  "instance": "/v1/invoices/abc-123"
}
{
  "success": false,
  "error": {
    "code": "EVENT_NOT_FOUND",
    "message": "Payment event not found"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "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"
  }
}
{
  "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"
  }
}

Mark a payment event as manually resolved POST

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.

Restore a discarded payment event POST

Reverses a previous discard, bringing a payment event back into the default list. The operation reverses the whole discard operation: the event named in the request and every event with the same payment identity (see the discard operation) that was discarded together with it, that is, with exactly the same `deleted_at` timestamp. Events discarded in an earlier or later operation are not affected. Idempotent — restoring an event that is not discarded is a no-op.