Get a payment event of a company's connection
Scopepayment-connections:readRetrieves a single payment event of the NIF's connection, including the outcome of its automatic invoicing and, when it failed, the stable failure code you can act on.
- Not found: an event that does not belong to this NIF's connection returns
404, the same answer an event that does not exist gets, so an event of another NIF is never disclosed.
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
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.
uuidUnique 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.
uuidIdentifier of the payment event, as returned by the list operation.
uuidResponse Body
application/json
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/497f6eca-6276-4993-bfeb-53cbbbba6f08/events/497f6eca-6276-4993-bfeb-53cbbbba6f08"{
"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": "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": "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"
}
}List the payment events of a company's connection GET
Lists the payment events received through the payment provider connection of a NIF (company), most recent first. Use it to audit the charges that produced an invoice and to find the ones that did not. - **By default, every event is listed.** Nothing is hidden: events the connection skipped, duplicates and disputes are all returned. Narrow the list with the filters below; what you do not filter, you get. Set `charges_only=true` to read the same events as one row per money movement instead. - **Scope:** events belong to the connection, not to the NIF directly. The `{connection_id}` segment picks one connection of the NIF in the path, and only the events of that connection are returned; an event of another NIF of the same account is never reachable from here. - **Unknown connection:** a `{connection_id}` that belongs to no connection of this NIF returns `404`.
Retry a payment event of a company's connection POST
Reprocesses a payment event whose automatic invoicing did not complete, applying the configuration of the NIF as it stands now. Use it after fixing what caused the failure, for example a missing invoice series. - **`retry_available`:** only events where it is `true` can be retried. Read it instead of deriving retryability from `status` yourself; anything else returns `400`. - **Limit:** the status and the skip reason must admit reprocessing, and the event must still be under the limit of 3 retries (`retry_count`). A retry that fails for a transient cause outside the event (provider outage, timeout) does not count towards the limit.