NIP-XX: Payment Gateway Descriptor Event (kind:10164)

Summary

This NIP introduces a new event kind (10164) that allows content creators to declare payment gateways, pricing models, and subscription rules for accessing paid content.

It complements NIP-63 by:

• Decoupling payment handling from subscriber management
• Supporting multiple payment providers
• Enabling flexible pricing, discounts, and conditions
• Allowing both automated and manual subscription flows

---

Motivation

NIP-63 defines how to manage subscribers (e.g., via kind 30000 lists), but does not standardize:

• How users discover payment options
• How different payment methods/providers are described
• How pricing variations and discount logic are communicated

This event solves that by acting as a declarative payment layer.

---

Event Kind

kind: 10164

• Can be published multiple times by the same author
• Each event represents one payment configuration / gateway
• Clients should aggregate all 10164 events for a creator

---

Event Structure

{
  "kind": 10164,
  "pubkey": "<creator_pubkey>",
  "created_at": <unix_timestamp>,
  "tags": [
    ["d", "<unique_id>"],
    ["u", "<payment_url>"],
    ["p", "<optional_gateway_pubkey>"],
    ["method", "<payment_method>"],
    ["currency", "<currency_code>"],
    ["price", "<amount>", "<interval>"],
    ["discount", "<type>", "<value>", "<condition>"],
    ["perk", "<description>"],
    ["group", "<group_id>"],
    ["relay", "<relay_url>"],
    ["zap_min", "<amount>"],
    ["zap_unit", "<unit>"],
    ["payout", "<payout_method>"],
    ["manual", "true|false"]
  ],
  "content": "<optional human-readable description>"
}

---

Tag Definitions

Required Tags

• ["d", "<unique_id>"]
  Unique identifier for this configuration (per author)

• ["u", "<payment_url>"]
  URL to the payment gateway or instructions page

• ["method", "<payment_method>"]
  Examples:

  • bitcoin
  • lightning
  • ethereum
  • fiat
  • zap
  • manual

• ["price", "<amount>", "<interval>"]
  Examples:

  • ["price", "10", "monthly"]
  • ["price", "50", "6-months"]
  • ["price", "100", "yearly"]

---

Optional Tags

Payment Context

• ["currency", "<currency_code>"]
  Examples: USD, EUR, BTC, SATS

• ["p", "<gateway_pubkey>"]
  Optional Nostr pubkey of the payment processor

• ["payout", "<payout_method>"]
  Describes how creator receives funds
  Examples: bank_transfer, crypto_wallet

---

Discounts & Pricing Flexibility

Multiple discount tags allowed:

["discount", "<type>", "<value>", "<condition>"]

Examples:

• ["discount", "percentage", "10", "bitcoin"]
• ["discount", "percentage", "20", "6-months-upfront"]
• ["discount", "fixed", "5", "members_of:<group_id>"]

---

Access Conditions

• ["group", "<group_id>"]
  Restrict or discount for members of a specific group

• ["relay", "<relay_url>"]
  Special conditions for users of a relay

---

Zap-based Subscriptions

• ["zap_min", "<amount>"]
  Minimum zap amount to qualify

• ["zap_unit", "<interval>"]
  Examples: monthly, per-access

---

Manual Payments

• ["manual", "true"]
  Indicates payment is handled off-platform (e.g., DM, bank transfer)

---

Perks / Description

• ["perk", "<description>"]
  Can be repeated to describe benefits

---

Subscriber Management

Payment gateways (or manual operators) are responsible for updating subscriber lists using:

• Kind 30000 (or as defined in NIP-63)
• Tagging users who have successfully paid

This event does not manage subscribers directly, only defines how they can subscribe.

---

Client Behavior

Clients SHOULD:

1. Fetch all 10164 events from a creator
2. Group them by method and currency
3. Present users with available options:
   • Payment method
   • Price
   • Discounts
   • Conditions
4. Redirect users to the u URL for payment
5. Optionally verify:
   • Gateway pubkey (p)
   • Zap receipts
   • Subscription updates

---

Examples

---

1. Bitcoin + Fiat with Discount

{
  "kind": 10164,
  "tags": [
    ["d", "btc-monthly"],
    ["u", "https://pay.btc.example/subscribe"],
    ["method", "bitcoin"],
    ["currency", "BTC"],
    ["price", "0.0002", "monthly"],
    ["discount", "percentage", "10", "bitcoin"]
  ],
  "content": "10% discount when paying in Bitcoin"
}

---

2. Ethereum Payment with Fiat Payout

{
  "kind": 10164,
  "tags": [
    ["d", "eth-plan"],
    ["u", "https://ethpay.example"],
    ["method", "ethereum"],
    ["currency", "ETH"],
    ["price", "0.05", "monthly"],
    ["payout", "bank_transfer"]
  ]
}

---

3. Zap-based Subscription (Delegated Counting)

{
  "kind": 10164,
  "tags": [
    ["d", "zap-support"],
    ["u", "https://zap-tracker.example"],
    ["method", "zap"],
    ["zap_min", "1000"],
    ["zap_unit", "monthly"],
    ["p", "<zap_tracker_pubkey>"]
  ]
}

---

4. Manual Payment (No Gateway)

{
  "kind": 10164,
  "tags": [
    ["d", "manual-local"],
    ["method", "manual"],
    ["price", "30", "monthly"],
    ["currency", "LOCAL"],
    ["manual", "true"]
  ],
  "content": "Contact me via DM to arrange payment"
}

---

5. 6-Month Discount Plan

{
  "kind": 10164,
  "tags": [
    ["d", "6mo-plan"],
    ["u", "https://pay.example/6months"],
    ["method", "fiat"],
    ["currency", "USD"],
    ["price", "50", "6-months"],
    ["discount", "percentage", "20", "6-months-upfront"]
  ]
}

---

6. Group-based Discount

{
  "kind": 10164,
  "tags": [
    ["d", "community-discount"],
    ["u", "https://pay.example/community"],
    ["method", "fiat"],
    ["price", "10", "monthly"],
    ["discount", "percentage", "15", "members_of:nostr-devs"]
  ]
}

---

Design Principles

• Composable: Multiple events = multiple options
• Extensible: New tags can be introduced without breaking clients
• Decoupled: Payment ≠ subscription state
• Client-friendly: Simple tag-based parsing
• Protocol-native: Works fully within Nostr event model

---

Future Extensions

• Verifiable receipts (kind for payment proof)
• Standard discount condition schemas
• Subscription expiration timestamps
• Cross-relay subscription syncing

---

Conclusion

Kind 10164 provides a flexible, extensible way to define how users can pay, while leaving who has paid to existing NIP-63 mechanisms.

It enables:

• Multi-provider setups
• Hybrid crypto/fiat systems
• Manual and automated flows
• Rich pricing strategies

Without introducing unnecessary protocol complexity.