BillingReceiptExternalPayload `billing.receipt.external@1`

Generated at 2026-09-23 23:26:36 UTC from openvibe-contracts v0.33.0 and openvibe-sdk v0.5.0.

Version: 1.0.0
Owner: billing
Visibility: first-party
Status: active
Compatibility: backward
Decision: ADR-012
Schema: https://openvibe.network/contracts/events/payloads/billing.receipt.external.v1.json

billing.receipt.external v1 (OpenVibe.Billing server/ops/external.js record). An EXTERNAL receipt (ADR-012): a tip paid on a creator's own provider account (PowerChat route direct). The money never touches OpenVibe (no journal entry); Billing announces it once per payment, only when BILLING_AUTHORITY=billing and the receiving account is mapped to a creator. OpenVibe.Tips celebrates it (chat line, overlay alert, goal). Envelope: subject { type: provider_receipt, id: <provider>:<payment id> }, visibility internal, priority important, actor service:billing.

Fields

Field	Type	Required	Description	Constraints
`classification`	const	yes		`= "EXTERNAL"`
`provider`	string	yes		`pattern ^[a-z][a-z0-9_-]{1,39}$`
`receipt_ref`	string	yes	<provider>:<payment id>, e.g. powerchat:…
`provider_event_id`	string	yes	The provider's id of the payment, stable across redeliveries.	`minLength 1` `maxLength 200`
`delivery_id`	string	yes	The webhook delivery that carried it.
`streamer`	identity.subject-ref	yes
`receiving_account`	object	yes		`no other fields`
`receiving_account.provider`	string	yes
`receiving_account.id`	string \| null	yes
`receiving_account.username`	string \| null	yes
`amount_cents`	integer	yes		`minimum 1` `maximum 100000000`
`currency`	const	yes		`= "usd-cents"`
`value_bits`	integer	yes	Billing's value of the money in bits.	`minimum 0`
`donor_name`	string \| null	yes	null when anonymous.	`maxLength 80`
`anonymous`	boolean	yes
`message`	string \| null	yes		`maxLength 500`
`app_ref`	string \| null	yes
`app_purpose`	string \| null	yes		`maxLength 120`
`occurred_at`	string \| null	yes	The provider's timestamp as it sent it.
`test`	boolean	yes
`rates`	object	yes	Rate snapshot.
`rates.bits_per_usd`	number	yes

Examples

From the contract's own test fixtures: valid ones validate, rejected ones must fail.

Valid: anonymous

{
  "classification": "EXTERNAL",
  "provider": "powerchat",
  "receipt_ref": "powerchat:ext-1",
  "provider_event_id": "ext-1",
  "delivery_id": "dlv-ext-1",
  "streamer": {
    "type": "user",
    "id": "usr_01JAB2C3D4E5F6G7H8J9K0MNPQ"
  },
  "receiving_account": {
    "provider": "powerchat",
    "id": "981",
    "username": "japaneseoldguy"
  },
  "amount_cents": 1234,
  "currency": "usd-cents",
  "value_bits": 1234,
  "donor_name": null,
  "anonymous": true,
  "message": null,
  "app_ref": null,
  "app_purpose": null,
  "occurred_at": "2026-09-23T20:00:00Z",
  "test": false,
  "rates": {
    "bits_per_usd": 100
  }
}

Valid: powerchat-tip

{
  "classification": "EXTERNAL",
  "provider": "powerchat",
  "receipt_ref": "powerchat:ext-1",
  "provider_event_id": "ext-1",
  "delivery_id": "dlv-ext-1",
  "streamer": {
    "type": "user",
    "id": "usr_01JAB2C3D4E5F6G7H8J9K0MNPQ"
  },
  "receiving_account": {
    "provider": "powerchat",
    "id": "981",
    "username": "japaneseoldguy"
  },
  "amount_cents": 1234,
  "currency": "usd-cents",
  "value_bits": 1234,
  "donor_name": "Generous Fan",
  "anonymous": false,
  "message": "love the stream",
  "app_ref": null,
  "app_purpose": "goal:12",
  "occurred_at": "2026-09-23T20:00:00Z",
  "test": false,
  "rates": {
    "bits_per_usd": 100
  }
}

Rejected: booked-classification

{
  "classification": "SITE",
  "provider": "powerchat",
  "receipt_ref": "powerchat:ext-1",
  "provider_event_id": "ext-1",
  "delivery_id": "dlv-ext-1",
  "streamer": {
    "type": "user",
    "id": "usr_01JAB2C3D4E5F6G7H8J9K0MNPQ"
  },
  "receiving_account": {
    "provider": "powerchat",
    "id": "981",
    "username": "japaneseoldguy"
  },
  "amount_cents": 1234,
  "currency": "usd-cents",
  "value_bits": 1234,
  "donor_name": "Generous Fan",
  "anonymous": false,
  "message": "love the stream",
  "app_ref": null,
  "app_purpose": "goal:12",
  "occurred_at": "2026-09-23T20:00:00Z",
  "test": false,
  "rates": {
    "bits_per_usd": 100
  }
}

Rejected: zero-amount

{
  "classification": "EXTERNAL",
  "provider": "powerchat",
  "receipt_ref": "powerchat:ext-1",
  "provider_event_id": "ext-1",
  "delivery_id": "dlv-ext-1",
  "streamer": {
    "type": "user",
    "id": "usr_01JAB2C3D4E5F6G7H8J9K0MNPQ"
  },
  "receiving_account": {
    "provider": "powerchat",
    "id": "981",
    "username": "japaneseoldguy"
  },
  "amount_cents": 0,
  "currency": "usd-cents",
  "value_bits": 1234,
  "donor_name": "Generous Fan",
  "anonymous": false,
  "message": "love the stream",
  "app_ref": null,
  "app_purpose": "goal:12",
  "occurred_at": "2026-09-23T20:00:00Z",
  "test": false,
  "rates": {
    "bits_per_usd": 100
  }
}

Validate

const contracts = require('openvibe-contracts');
contracts.validate('billing.receipt.external@1', value);   // { valid, errors: [{ path, message }] }

BillingReceiptExternalPayload billing.receipt.external@1

Fields

Examples

Validate

BillingReceiptExternalPayload `billing.receipt.external@1`