Retry a payment event of a NIF's connection
Scopepayment-connections:writeReprocesses 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.
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.
uuidHeader Parameters
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.
| 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 and retry with the same key. |
409 | IDEMPOTENCY_KEY_MISMATCH | The key was already used with a different body. Use a new key. |
^[a-zA-Z0-9_-]+$length <= 255Response Body
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/stripe/events/497f6eca-6276-4993-bfeb-53cbbbba6f08/retry"{
"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": "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 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"
}
}Get a payment event of a NIF's connection GET
Retrieves 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.
Create a draft invoice from a payment event of a NIF's connection POST
Builds a draft invoice from a payment event that could not be invoiced automatically, applying the same recipient resolution and tax treatment the automatic flow would have applied. The invoice is left as a draft so it can be reviewed and issued afterwards, and it is created in the NIF of the path. Only events that were not invoiced can produce a draft; otherwise the request returns `400`. If invoicing rules reject the resulting document, the request returns `422`.