API docs by Redocly

Billing & Payment public API (1.0.0)

Download OpenAPI specification:

URL: https://github.com/blooo-io/intelligent-eu-billing-and-payment License: Apache-2.0

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.

Profile

Caller profile (REQ-009, REQ-049).

Caller profile, roles, community and readiness

Profile, roles, community and readiness of the caller (REQ-049, REQ-009).

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "participantId": "9f6624b5-5f99-42b6-899f-30f2b369cbd7",
  • "communityId": "b3a7bb5e-2860-4aca-803b-cc380a8c5ca0",
  • "roles": [
    ],
  • "readiness": "Invited",
  • "profile": {
    },
  • "billingMode": "live"
}

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:
bearerAuth
Request Body schema: application/json
required
name
required
string
address
required
string
email
required
string <email>

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "address": "string",
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "address": "string",
  • "email": "user@example.com"
}

Terms

Current terms and their acceptance.

Current terms

Current terms, including the self-billing mandate shown to a producer (REQ-050).

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "termsVersion": "string",
  • "text": "string"
}

Accept the current terms

Records terms acceptance and, for a producer, the self-billing mandate (REQ-050).

Authorizations:
bearerAuth
Request Body schema: application/json
required
termsVersion
required
string
selfBillingMandate
required
boolean

Required for a producer. False for a consumer who does not self-bill (REQ-050).

Responses

Request samples

Content type
application/json
{
  • "termsVersion": "string",
  • "selfBillingMandate": true
}

Response samples

Content type
application/json
{
  • "termsVersion": "string",
  • "selfBillingMandate": true,
  • "acceptedAt": "2019-08-24T14:15:22Z"
}

Payments

Payment-account onboarding and invoice payment.

Start payment-account onboarding

Producer/prosumer: returns outstanding KYC requirements for in-platform collection (INT-190 / INT-191, REQ-051, UAT-051). The Custom Connect account is created on the first requirements submit with an Account Token. 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:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "mode": "requirements",
  • "status": "requirements_due",
  • "stripeAccountId": "string",
  • "currentlyDue": [
    ],
  • "eventuallyDue": [
    ],
  • "url": "http://example.com",
  • "clientSecret": "string"
}

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:
bearerAuth
Request Body schema: application/json
required
paymentMethodId
required
string

Stripe PaymentMethod id (pm_…).

Responses

Request samples

Content type
application/json
{
  • "paymentMethodId": "string"
}

Response samples

Content type
application/json
{
  • "mode": "requirements",
  • "status": "requirements_due",
  • "stripeAccountId": "string",
  • "currentlyDue": [
    ],
  • "eventuallyDue": [
    ],
  • "url": "http://example.com",
  • "clientSecret": "string"
}

Submit Connect KYC requirements

Creates or updates a Custom Connect account using an Account Token (INT-191, REQ-051) and returns the refreshed onboarding session. Personal data is not retained by billing.

Authorizations:
bearerAuth
Request Body schema: application/json
required
accountToken
string

Stripe Account Token id (ct_… / tok_…) from Stripe.js createToken('account', …) or server-side tokens.create (INT-191).

country
string = 2 characters

Connected-account country (outside the token). Default FR.

businessType
string
Enum: "individual" "company"
businessProfileUrl
string <uri>
businessProfileMcc
string

Merchant category code (e.g. 5734).

object
identityDocumentFront
string

Stripe File id for individual.verification.document.front (INT-195). Prefer embedding in the Account Token from Stripe.js. Test mode may use file_identity_document_success to recover verification_failed_keyed_identity.

identityDocumentAdditionalFront
string

Stripe File id for individual.verification.additional_document.front (INT-195). Defaults to identityDocumentFront when omitted in adapters.

object

Test-mode bank account for Connect payouts (BR-12).

tosAccepted
boolean

Caller accepted Stripe Connected Account Agreement.

Responses

Request samples

Content type
application/json
{
  • "accountToken": "string",
  • "country": "st",
  • "businessType": "individual",
  • "businessProfileUrl": "http://example.com",
  • "businessProfileMcc": "string",
  • "representative": {
    },
  • "identityDocumentFront": "string",
  • "identityDocumentAdditionalFront": "string",
  • "externalAccount": {
    },
  • "tosAccepted": true
}

Response samples

Content type
application/json
{
  • "mode": "requirements",
  • "status": "requirements_due",
  • "stripeAccountId": "string",
  • "currentlyDue": [
    ],
  • "eventuallyDue": [
    ],
  • "url": "http://example.com",
  • "clientSecret": "string"
}

Pay an invoice

The consumer pays the invoice. The payment goes to the producer's account (REQ-014).

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid> (Uuid)

Resource identifier.

Responses

Response samples

Content type
application/json
{
  • "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7",
  • "invoiceId": "4f163819-178d-470c-a246-d6768476a6ec",
  • "amount": "5.00",
  • "currency": "EUR",
  • "status": "pending",
  • "method": "string",
  • "failureCategory": "string"
}

Balances

Balances of the caller.

Unbilled balances per counterpart

Unbilled amounts of the caller, one row per counterpart (REQ-002, REQ-057).

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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:
bearerAuth
Request Body schema: application/json
required
producerId
required
string <uuid> (Uuid)

Responses

Request samples

Content type
application/json
{
  • "producerId": "09cbf28b-153f-46c1-af4f-7ee5a3a319fc"
}

Response samples

Content type
application/json
{
  • "runId": "78c33d18-170c-44d3-a227-b3194f134f73",
  • "communityId": "b3a7bb5e-2860-4aca-803b-cc380a8c5ca0",
  • "period": "string",
  • "type": "periodic",
  • "status": "Scheduled",
  • "version": 1
}

Invoices

Invoices of the caller.

Invoices of the caller

Invoices where the caller is the producer or the consumer (REQ-007, REQ-039).

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Invoice detail

One invoice in the caller's scope. The detail view reads the provider live (TD-6, REQ-007).

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid> (Uuid)

Resource identifier.

Responses

Response samples

Content type
application/json
{
  • "invoiceId": "4f163819-178d-470c-a246-d6768476a6ec",
  • "legalNumber": "string",
  • "producerId": "09cbf28b-153f-46c1-af4f-7ee5a3a319fc",
  • "consumerId": "9e675a24-20d6-4913-9836-f861cd23e89e",
  • "period": "string",
  • "currency": "EUR",
  • "status": "Draft",
  • "dueDate": "2019-08-24",
  • "pairSettlementId": "be603dfd-1b5b-4583-98bb-409a00500833",
  • "tradeIds": [
    ],
  • "amounts": {
    },
  • "billingMode": "live"
}

Invoice PDF

Hosted invoice PDF (REQ-039). The provider sends the document.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid> (Uuid)

Resource identifier.

Responses

Response samples

Content type
application/problem+json
{}

Set an invoice status manually

A community manager sets a status with a mandatory reason (REQ-044).

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid> (Uuid)

Resource identifier.

Request Body schema: application/json
required
status
required
string (InvoiceStatus)
Enum: "Draft" "Open" "PartiallyPaid" "Paid" "Overdue" "Void" "Disputed"

Invoice lifecycle (REQ-044, 02 §5).

reason
required
string non-empty

Responses

Request samples

Content type
application/json
{
  • "status": "Draft",
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "invoiceId": "4f163819-178d-470c-a246-d6768476a6ec",
  • "legalNumber": "string",
  • "producerId": "09cbf28b-153f-46c1-af4f-7ee5a3a319fc",
  • "consumerId": "9e675a24-20d6-4913-9836-f861cd23e89e",
  • "period": "string",
  • "currency": "EUR",
  • "status": "Draft",
  • "dueDate": "2019-08-24",
  • "pairSettlementId": "be603dfd-1b5b-4583-98bb-409a00500833",
  • "tradeIds": [
    ],
  • "amounts": {
    },
  • "billingMode": "live"
}

Communities

Community settings.

Read community billing settings

Currency, period, threshold, VAT and mode (REQ-006, REQ-043, REQ-056).

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid> (Uuid)

Resource identifier.

Responses

Response samples

Content type
application/json
{
  • "communityId": "b3a7bb5e-2860-4aca-803b-cc380a8c5ca0",
  • "currency": "EUR",
  • "billingPeriod": "string",
  • "threshold": "5.00",
  • "vatRate": "0.00",
  • "billingMode": "live"
}

Update community billing settings

A community manager updates currency, period, threshold, VAT and mode (REQ-006, REQ-043, REQ-056).

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid> (Uuid)

Resource identifier.

Request Body schema: application/json
required
currency
required
string (Currency) ^[A-Z]{3}$

ISO 4217 currency code of the community.

billingPeriod
required
string
threshold
required
string (Money) ^-?\d+\.\d{2}$

Decimal amount rounded to the cent (BR-08).

vatRate
required
string (Rate) ^\d+\.\d{2}$

Decimal rate rounded to the cent, such as a VAT rate (BR-07, BR-08).

billingMode
required
string (BillingMode)
Enum: "live" "virtual"

Community billing mode (REQ-043). V1 communities are virtual.

Responses

Request samples

Content type
application/json
{
  • "currency": "EUR",
  • "billingPeriod": "string",
  • "threshold": "5.00",
  • "vatRate": "0.00",
  • "billingMode": "live"
}

Response samples

Content type
application/json
{
  • "communityId": "b3a7bb5e-2860-4aca-803b-cc380a8c5ca0",
  • "currency": "EUR",
  • "billingPeriod": "string",
  • "threshold": "5.00",
  • "vatRate": "0.00",
  • "billingMode": "live"
}

Participants

Import, list, update and offboarding of participants.

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:
bearerAuth
path Parameters
id
required
string <uuid> (Uuid)

Resource identifier.

Request Body schema: application/json
required
required
Array of objects (ParticipantImport) non-empty

Responses

Request samples

Content type
application/json
{
  • "participants": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

List participants of a community

Participant registry of the community (REQ-008, REQ-058).

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid> (Uuid)

Resource identifier.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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:
bearerAuth
path Parameters
id
required
string <uuid> (Uuid)

Resource identifier.

Request Body schema: application/json
required
marketActorId
string
meterId
string
role
string (ParticipantRole)
Enum: "consumer" "producer" "prosumer"

Role of a participant in the community (02 §6).

Responses

Request samples

Content type
application/json
{
  • "marketActorId": "string",
  • "meterId": "string",
  • "role": "consumer"
}

Response samples

Content type
application/json
{
  • "participantId": "9f6624b5-5f99-42b6-899f-30f2b369cbd7",
  • "communityId": "b3a7bb5e-2860-4aca-803b-cc380a8c5ca0",
  • "role": "consumer",
  • "status": "Invited",
  • "marketActorId": "string",
  • "meterId": "string"
}

Offboard a participant

Removes the participant from the community and triggers the final settlement (REQ-012).

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid> (Uuid)

Resource identifier.

Responses

Response samples

Content type
application/json
{
  • "participantId": "9f6624b5-5f99-42b6-899f-30f2b369cbd7",
  • "communityId": "b3a7bb5e-2860-4aca-803b-cc380a8c5ca0",
  • "role": "consumer",
  • "status": "Invited",
  • "marketActorId": "string",
  • "meterId": "string"
}

Billing

Billing runs and early settlement.

Start a billing run

A manager or operator starts a run for the community (REQ-006).

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid> (Uuid)

Resource identifier.

Request Body schema: application/json
required
type
required
string (BillingRunType)
Enum: "periodic" "early" "final"

Kind of billing run (02 §6).

period
string

Required when type is periodic.

Responses

Request samples

Content type
application/json
{
  • "type": "periodic",
  • "period": "string"
}

Response samples

Content type
application/json
{
  • "runId": "78c33d18-170c-44d3-a227-b3194f134f73",
  • "communityId": "b3a7bb5e-2860-4aca-803b-cc380a8c5ca0",
  • "period": "string",
  • "type": "periodic",
  • "status": "Scheduled",
  • "version": 1
}

Read a billing run

Status of one billing run (REQ-006).

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid> (Uuid)

Resource identifier.

Responses

Response samples

Content type
application/json
{
  • "runId": "78c33d18-170c-44d3-a227-b3194f134f73",
  • "communityId": "b3a7bb5e-2860-4aca-803b-cc380a8c5ca0",
  • "period": "string",
  • "type": "periodic",
  • "status": "Scheduled",
  • "version": 1
}

Reports

Periodic summaries, discrepancies, intake anomalies and KPI export.

Payment overview of a community

Manager view of payments in the community (REQ-018). Lists use the provider read cache (TD-6).

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid> (Uuid)

Resource identifier.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Member history

Invoices and payments of one participant (REQ-031).

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid> (Uuid)

Resource identifier.

Responses

Response samples

Content type
application/json
{
  • "participantId": "9f6624b5-5f99-42b6-899f-30f2b369cbd7",
  • "invoices": [
    ],
  • "payments": [
    ]
}

Periodic summary

Summary of one community and period (REQ-032).

Authorizations:
bearerAuth
query Parameters
communityId
required
string <uuid> (Uuid)

Community whose data is requested (REQ-010).

period
required
string

Billing period of the report.

Responses

Response samples

Content type
application/json
{
  • "communityId": "b3a7bb5e-2860-4aca-803b-cc380a8c5ca0",
  • "period": "string",
  • "currency": "EUR",
  • "invoiceCount": 0,
  • "paymentCount": 0,
  • "total": "5.00"
}

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:
bearerAuth
path Parameters
period
required
string

Billing period of the export.

query Parameters
communityId
required
string <uuid> (Uuid)

Community whose data is requested (REQ-010).

Responses

Response samples

Content type
application/problem+json
{}

Operations

Scheduled jobs.

Reconciliation discrepancies

Discrepancies visible to an operator (REQ-041).

Authorizations:
bearerAuth
query Parameters
communityId
string <uuid> (Uuid)

Limits the result to one community in the caller's scope (REQ-010).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Intake anomalies

Trade-intake anomalies visible to an operator (REQ-029).

Authorizations:
bearerAuth
query Parameters
communityId
string <uuid> (Uuid)

Limits the result to one community in the caller's scope (REQ-010).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List scheduled jobs

Job executions visible to an operator (02 §4.5).

Authorizations:
bearerAuth
query Parameters
communityId
string <uuid> (Uuid)

Limits the result to one community in the caller's scope (REQ-010).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Run a job now

An operator triggers one scheduled job (02 §4.5).

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid> (Uuid)

Resource identifier.

Responses

Response samples

Content type
application/json
{
  • "jobId": "9d222c6d-893e-4e79-8201-3c9ca16a0f39",
  • "name": "RefreshIntake",
  • "communityId": "b3a7bb5e-2860-4aca-803b-cc380a8c5ca0",
  • "outcome": "string",
  • "lastRunAt": "2019-08-24T14:15:22Z"
}

Privacy

Data-subject export and erasure requests.

Request an export or an erasure

The member or the DPO opens an export or erasure request (REQ-013).

Authorizations:
bearerAuth
Request Body schema: application/json
required
type
required
string
Enum: "export" "erasure"
participantId
string <uuid> (Uuid)

Set by a DPO acting for a participant. Omitted when the member acts for themselves.

Responses

Request samples

Content type
application/json
{
  • "type": "export",
  • "participantId": "9f6624b5-5f99-42b6-899f-30f2b369cbd7"
}

Response samples

Content type
application/json
{
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "participantId": "9f6624b5-5f99-42b6-899f-30f2b369cbd7",
  • "type": "export",
  • "status": "string"
}

Read a data-subject request

Status of one export or erasure request (REQ-013).

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid> (Uuid)

Resource identifier.

Responses

Response samples

Content type
application/json
{
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "participantId": "9f6624b5-5f99-42b6-899f-30f2b369cbd7",
  • "type": "export",
  • "status": "string"
}