TipsPaidRequest `tips.paid-request@1`

Generated at 2026-09-26 00:45:03 UTC from openvibe-contracts v0.53.0 and openvibe-sdk v0.11.0.

Version: 1.0.0
Owner: tips
Visibility: first-party
Status: active
Compatibility: backward
Schema: https://openvibe.network/contracts/tips/paid-request.v1.json

tips.paid-request@1: bodies of the paid requests on OpenVibe.Tips: POST /api/v1/checkout (tips.checkout.create: a tip), POST /api/v1/paid-messages (tips.superchat.create: needs message; paid_message_min applies), POST /api/v1/tts-requests (tips.tts.request: needs text to read, tts.text or message, within the creator's TTS settings) and POST /api/v1/media-requests (tips.media_request.create: needs media.url; the creator's minimum and length apply): { creator, amount, supporter?, supporter_name?, message?, pay_with?, provider?, tts?, media?, goal_id?, target?, privacy? }. The route sets the kind. A service names the supporter; a person pays as themselves. pay_with credit (default) pays from the supporter's Billing credit at once; checkout starts a Billing checkout (from TIPS_MIN_CHECKOUT_BITS, 100 bits by default). Tips never prices money; Billing does. Needs an Idempotency-Key header (8-200 of A-Z a-z 0-9 . _ : -; 400 idempotency.key_required): a replay with the same key and body returns the first answer, the same key with another body is 422 idempotency.key_reused. Refusals are problem+json: 422 tips.invalid_input, tips.invalid_amount, tips.amount_too_small, tips.text_too_long (message over TIPS_MESSAGE_CHARS, 300 by default), tips.invalid_media, tips.invalid_subject, tips.name_taken, tips.goal_not_found or tips.self_dealing; 409 tips.not_accepting, tips.tts_disabled or tips.media_disabled; 409 tips.payment_failed (a replay of a request whose payment failed) and Billing's own refusal code (409 billing.insufficient_funds, else 422), both with the interaction in details; 404 tips.creator_not_found; 429 tips.too_many_pending; 502 tips.billing_unavailable. Unknown fields are ignored.

Fields

Field	Type	Required	Description	Constraints
`creator`	one of	yes	The creator tipped.
`amount`	integer \| string	yes	Vibes bits, at most TIPS_MAX_BITS (10000000 by default).	`pattern ^[1-9][0-9]*$` `minimum 1` `maximum 10000000`
`supporter`	one of		The supporter: required for services; ignored for a person.
`supporter_name`	string \| null		The name to show (at most 80 characters kept); never the creator's own name or handle.
`message`	string \| null
`pay_with`	enum			`one of "credit", "checkout"`
`provider`	string		pay_with checkout: one of TIPS_CHECKOUT_PROVIDERS (powerchat by default).
`tts`	object		Text-to-speech (kind tts): the text to read (default: message) and the voice.
`tts.text`	string
`tts.voice`	enum		Default: the creator's voice.	`one of "gary", "brian", "amy", "emma", "joey", "justin", "matthew", "salli", "kimberly", "kendra", "ivy", "joanna"`
`media`	object		A media request (kind media_request).
`media.url`	string	yes	An https link on an allowed host (TIPS_MEDIA_HOSTS; YouTube by default).	`pattern ^https://` `maxLength 500`
`goal_id`	string		One of the creator's open goals.
`target`	common.entity-ref		What the tip is for (a Live stream, …).
`privacy`	object		The supporter's choices; any other field is refused (422 tips.invalid_input). true, 1, "1", "true" and "on" count as yes.	`no other fields`
`privacy.anonymous`	boolean \| integer \| string		The name reads "Anonymous" to everyone but the supporter.
`privacy.hide_amount`	boolean \| integer \| string		The amount is left out of overlays, chat lines and public pages.
`privacy.private_message`	boolean \| integer \| string		A tip's message is for the creator only (tips only; 422 for the other kinds).

Examples

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

Valid: media

{
  "creator": "usr_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "amount": 300,
  "media": {
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  }
}

Valid: service-tip

{
  "creator": {
    "type": "user",
    "id": "usr_01JAB2C3D4E5F6G7H8J9K0MNPQ"
  },
  "supporter": {
    "type": "user",
    "id": "usr_01JAB2C3D4E5F6G7H8J9K0MNPR"
  },
  "supporter_name": "moosefan",
  "amount": 250,
  "message": "For the new mic!",
  "goal_id": "tgoal_01JAB2C3D4E5F6G7H8J9K0MNQ9",
  "target": {
    "service": "live",
    "type": "stream",
    "id": "8812"
  }
}

Valid: tts-checkout

{
  "creator": "moosefan",
  "amount": "1000",
  "pay_with": "checkout",
  "provider": "powerchat",
  "tts": {
    "text": "Hello from the chat",
    "voice": "amy"
  },
  "privacy": {
    "anonymous": true
  }
}

Rejected: negative

{
  "creator": "usr_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "amount": -5
}

Rejected: privacy-extra

{
  "creator": "usr_01JAB2C3D4E5F6G7H8J9K0MNPQ",
  "amount": 100,
  "privacy": {
    "anonymous": true,
    "invisible": true
  }
}

Validate

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

TipsPaidRequest tips.paid-request@1

Fields

Examples

Validate

TipsPaidRequest `tips.paid-request@1`