API reference
Interactive reference for the public Billing & Payment API (/v1), generated from contracts/openapi/public.v1.yaml with vitepress-openapi (INT-302).
- Raw contract: /openapi/public.v1.yaml
- Narrative notes: API & events
Use the sidebar to open each operation, or browse the full spec below.
Playground servers (Try it out / Samples) include the upstream sample gateway https://api.dev.intelligent-eu-bp.blooo.dev/v1 plus relative /v1 and http://localhost/v1. You can also enter a custom URL. Calls need a valid OIDC bearer token.
Public API exposed by the gateway under /v1 (03 §3.1, REQ-052). Every call needs a bearer token. A response contains only data of the caller's own participant or community (REQ-010). Personal data is limited to the billing profile on /me.
Contact
License
Apache-2.0Servers
Caller profile, roles, community and readiness
Profile, roles, community and readiness of the caller (REQ-049, REQ-009).
Authorizations
Responses
The caller.
Update the caller's billing profile
The participant updates their own name, address and contact e-mail. Trade-attribution identifiers are changed by the community manager (REQ-009).
Authorizations
Request Body
Responses
Updated billing profile.
Current terms
Accept the current terms
Records terms acceptance and, for a producer, the self-billing mandate (REQ-050).
Authorizations
Request Body
Responses
Acceptance recorded.
Read the caller's payment account
INT-255 — Ready Payment method / Payout account chrome. Consumers get card brand and last4 from Stripe (TP-7: Stripe is master; we do not persist PAN data). Producers get Connect account id and an optional platform Dashboard deep-link for Custom accounts (stripe_dashboard: none — no Express login link).
Authorizations
Responses
Payment account summary for the signed-in member.
Start payment-account onboarding
Producer/prosumer: creates the Connect account on first call and returns an Account Session client secret (mode: embedded) for the Stripe Connect embedded Account onboarding component (INT-362, REQ-051, UAT-051). Stripe collects the KYC and the terms of service; the producer pays Stripe fees and bears disputes (fees.payer = account, losses.payments = stripe), so the platform absorbs no cost. Consumer: returns a SetupIntent client secret (mode: elements) for in-platform Payment Element collection (INT-193 / REQ-040), or a provider setup link (mode: link) as fallback.
Authorizations
Responses
Onboarding session (embedded, elements, or link).
Attach consumer payment method after SetupIntent
Confirms the payment method collected via Stripe.js / Payment Element (INT-193, REQ-040) and marks the payment account ready.
Authorizations
Request Body
Responses
Updated onboarding session (status complete).
Submit Connect KYC requirements
Deprecated by INT-362: producers onboard through the embedded Account onboarding component (mode: embedded). Kept for producer accounts created before INT-362 (Custom, requirement_collection = application): updates such an account using an Account Token (INT-191, REQ-051) and returns the refreshed onboarding session. Personal data is not retained by billing.
Authorizations
Request Body
Responses
Refreshed onboarding session.
Pay an invoice
The consumer pays the invoice. The payment goes to the producer's account (REQ-014).
Authorizations
Parameters
Path Parameters
Resource identifier.
Responses
Payment started.
Unbilled balances per counterpart
Settle early with one producer
The consumer settles the unbilled balance with the named producer now (REQ-057). The threshold does not apply (BR-05).
Authorizations
Request Body
Responses
Early settlement accepted.
Invoices of the caller
Invoices where the caller is the producer or the consumer (REQ-007, REQ-039).
Authorizations
Responses
The caller's invoices.
Invoice detail
One invoice in the caller's scope. The detail view reads the provider live (TD-6, REQ-007).
Authorizations
Parameters
Path Parameters
Resource identifier.
Responses
The invoice.
Invoice PDF
Set an invoice status manually
A community manager sets a status with a mandatory reason (REQ-044).
Authorizations
Parameters
Path Parameters
Resource identifier.
Request Body
Responses
Updated invoice.
Read community billing settings
Currency, period, threshold, VAT and mode (REQ-006, REQ-043, REQ-056).
Authorizations
Parameters
Path Parameters
Resource identifier.
Responses
Community settings.
Update community billing settings
A community manager updates currency, period, threshold, VAT and mode (REQ-006, REQ-043, REQ-056).
Authorizations
Parameters
Path Parameters
Resource identifier.
Request Body
Responses
Updated settings.
Import participants
Imports a minimal list of e-mail, GSY DEX actor identifier, meter identifier and role. The import creates the participant, the identity-provider account and the invitation (REQ-008).
Authorizations
Parameters
Path Parameters
Resource identifier.
Request Body
Responses
Imported participants.
List participants of a community
Participant registry of the community (REQ-008, REQ-058).
Authorizations
Parameters
Path Parameters
Resource identifier.
Responses
Participants. Full billing-profile address is not included; optional directory name / email help managers recognise members (INT-283 / REQ-008).
Update trade-attribution identifiers
A community manager changes the GSY DEX actor identifier, meter or role. The participant cannot change these (REQ-009, REQ-058).
Authorizations
Parameters
Path Parameters
Resource identifier.
Request Body
Responses
Updated participant.
Offboard a participant
Removes the participant from the community and triggers the final settlement (REQ-012).
Authorizations
Parameters
Path Parameters
Resource identifier.
Responses
Offboarding accepted.
Start a billing run
A manager or operator starts a run for the community (REQ-006). The token community must be this community (REQ-049 / UAT-060); another community receives 403. The period is YYYY-MM or YYYY-Qn; a periodic run without a period closes the last elapsed period of the community calendar.
Authorizations
Parameters
Path Parameters
Resource identifier.
Request Body
Responses
Run accepted.
Read a billing run
Status of one billing run (REQ-006). Returns 404 when the run is not in the caller's community (REQ-049 / UAT-060).
Authorizations
Parameters
Path Parameters
Resource identifier.
Responses
The billing run.
Payment overview of a community
Manager view of payments in the community (REQ-018). The token community must be this community (REQ-049 / UAT-060). Lists use the provider read cache (TD-6).
Authorizations
Parameters
Path Parameters
Resource identifier.
Responses
Payments of the community.
Member history
Invoices and payments of one participant (REQ-031). A member reads only their own participant. A manager or operator reads a participant of their own community. Another community returns 404 (REQ-049 / UAT-060).
Authorizations
Parameters
Path Parameters
Resource identifier.
Responses
Member history.
Periodic summary
Summary of one community and period (REQ-032). The token community must match communityId (REQ-049 / UAT-060).
Authorizations
Parameters
Query Parameters
Community whose data is requested (REQ-010).
Billing period of the report.
Responses
Periodic summary.
KPI export for a period
CSV file export of the period (REQ-047 invoice amounts/kWh plus REQ-046 payment failure causes, suggested corrective actions and processing times per method). The later channel is still open in the architecture (03 §7, port P-KPI).
Authorizations
Parameters
Path Parameters
Billing period of the export.
Query Parameters
Community whose data is requested (REQ-010).
Responses
KPI file.
Reconciliation discrepancies
Discrepancies visible to an operator (REQ-041).
Authorizations
Parameters
Query Parameters
Limits the result to one community in the caller's scope (REQ-010).
Responses
Discrepancies.
Intake anomalies
Trade-intake anomalies visible to an operator (REQ-029).
Authorizations
Parameters
Query Parameters
Limits the result to one community in the caller's scope (REQ-010).
Responses
Intake anomalies.
List scheduled jobs
Job executions visible to an operator (02 §4.5).
Authorizations
Parameters
Query Parameters
Limits the result to one community in the caller's scope (REQ-010).
Responses
Jobs.
Run a job now
An operator triggers one scheduled job (02 §4.5).
Authorizations
Parameters
Path Parameters
Resource identifier.
Responses
Job accepted.
Request an export or an erasure
The member opens an export or erasure for themselves; the token subject is used and a body participantId is ignored (REQ-013). A community manager or the DPO may name another participant of their own community. A peer or another community is rejected (REQ-049).
Authorizations
Request Body
Responses
Request accepted.
Read a data-subject request
Status of one export or erasure request (REQ-013). A member reads a request they opened or that names them. A manager, operator or DPO reads a request in their own community. Another community returns 404 (REQ-049).
Authorizations
Parameters
Path Parameters
Resource identifier.
Responses
The request.