Get a payment event of a NIF'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.
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.
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 events belong to. 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.
uuidPayment provider slug in lowercase. Currently only stripe (Stripe Connect) is
operative; woocommerce and shopify are reserved for future providers.
"stripe"Identifier 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
curl -X GET "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/payment-connections/stripe/events/497f6eca-6276-4993-bfeb-53cbbbba6f08"{
"success": true,
"data": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"provider": "stripe",
"event_type": "payment_intent.succeeded",
"external_event_id": "evt_1234567890",
"external_payment_id": "pi_1234567890",
"currency": "EUR",
"amount": 150,
"fee_amount": 0,
"net_amount": 0,
"customer_email": "string",
"customer_name": "string",
"status": "PROCESSED",
"invoice_id": "f4c4edb8-11e0-4b33-bcc1-482dc59ebb32",
"failure_category": "USER_CONFIGURATION",
"failure_reason": "MISSING_DEFAULT_SERIES",
"failure_message": "string",
"needs_action": true,
"draft_available": true,
"retry_available": true,
"retry_count": 0,
"received_at": "2019-08-24T14:15:22Z",
"processed_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": "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": "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"
}
}List the payment events of a NIF's connection GET
Lists the payment events received through the payment provider connection of a NIF (company) that your account **owns or manages**, most recent first. Use it to audit the charges that produced an invoice and to find the ones that did not. **Events belong to the connection, not to the NIF directly.** The `{provider}` segment picks the 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. If the NIF has no connection for the provider, returns `404`.
Retry a payment event of a NIF's connection POST
Reprocesses a payment event whose automatic invoicing did not complete, applying the current configuration of the NIF. Use it after fixing what caused the failure, for example a missing invoice series. Only events in a retryable state can be retried, and each event admits a limited number of retries; otherwise the request returns `400`.