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

Summary

This NIP introduces a new event kind (10164) that describes a single payment gateway with all supported methods, currencies, pricing models, and discount rules in one event.

Unlike previous proposals, this design:

• Treats a gateway as a multi-method, multi-currency system
• Allows all pricing options to be declared together
• Supports complex discount logic and conditions
• Keeps the event compact but expressive

---

Design Goals

• One event = one gateway
• Multiple methods per gateway
• Multiple currencies per method
• Flexible pricing models
• Composable discounts
• Client-friendly parsing

---

Event Kind

kind: 10164

• One event per gateway
• Creators can publish multiple events (one per gateway/provider)

---

Event Structure

{
  "kind": 10164,
  "pubkey": "<creator_pubkey>",
  "created_at": <unix_timestamp>,
  "tags": [
    ["d", "<gateway_id>"],
    ["u", "<payment_url>"],
    ["name", "<gateway_name>"],
    ["p", "<optional_gateway_pubkey>"]
  ],
  "content": "{...json_payload...}"
}

---

Content JSON Schema

The content field contains structured JSON describing all payment capabilities.

{
  "methods": [
    {
      "type": "bitcoin",
      "currencies": ["BTC", "SATS"],
      "prices": [
        {
          "amount": 0.0002,
          "interval": "monthly"
        }
      ],
      "discounts": [
        {
          "type": "percentage",
          "value": 10,
          "condition": "default"
        }
      ]
    },
    {
      "type": "fiat",
      "currencies": ["USD", "EUR"],
      "prices": [
        {
          "amount": 10,
          "interval": "monthly"
        },
        {
          "amount": 50,
          "interval": "6-months"
        }
      ],
      "discounts": [
        {
          "type": "percentage",
          "value": 20,
          "condition": "6-months-upfront"
        }
      ]
    }
  ],
  "conditions": [
    {
      "type": "group",
      "id": "<group_id>",
      "discount": 15
    },
    {
      "type": "relay",
      "id": "<relay_url>",
      "discount": 10
    }
  ],
  "zap": {
    "enabled": true,
    "min_amount": 1000,
    "interval": "monthly",
    "processor_pubkey": "<optional_pubkey>"
  },
  "payout": {
    "type": "bank_transfer"
  },
  "manual": false,
  "perks": [
    "Access to premium notes",
    "Early releases"
  ]
}

---

Field Breakdown

Top-Level Tags

• d: Unique gateway identifier
• u: Payment URL (entry point)
• name: Human-readable gateway name
• p: Optional pubkey of processor

---

Methods

Each method defines a payment channel:

{
  "type": "bitcoin | lightning | ethereum | fiat | zap | manual",
  "currencies": ["..."],
  "prices": [...],
  "discounts": [...]
}

---

Prices

{
  "amount": <number>,
  "interval": "monthly | yearly | 6-months | one-time"
}

---

Discounts

{
  "type": "percentage | fixed",
  "value": <number>,
  "condition": "<string>"
}

Examples of conditions:

• "bitcoin"
• "6-months-upfront"
• "members_of:<group_id>"

---

Conditions (Global Rules)

Applies across methods:

{
  "type": "group | relay",
  "id": "<identifier>",
  "discount": <percentage>
}

---

Zap Configuration

Optional zap-based subscription:

{
  "enabled": true,
  "min_amount": 1000,
  "interval": "monthly",
  "processor_pubkey": "<pubkey>"
}

---

Manual Payments

"manual": true

Indicates off-platform handling.

---

Subscriber Management

Gateways or operators update subscriber lists via:

• Kind 30000 (as per NIP-63)

This event does not manage subscribers directly.

---

Client Behavior

Clients SHOULD:

1. Fetch all 10164 events for a creator
2. Parse content JSON
3. Display:
   • Methods
   • Currencies
   • Pricing tiers
   • Discounts
4. Allow user to choose:
   • Method
   • Plan
5. Redirect to u

---

Example

{
  "kind": 10164,
  "tags": [
    ["d", "main-gateway"],
    ["u", "https://pay.example"],
    ["name", "Main Gateway"]
  ],
  "content": "{...}"
}

---

Advantages Over Previous Design

• No duplication across events
• Full pricing matrix in one place
• Easier client UX
• Supports complex real-world scenarios

---

Future Extensions

• Receipt verification events
• Expiration timestamps
• Dynamic pricing feeds
• Reputation scoring for gateways

---

Conclusion

This design makes 10164 a complete payment descriptor layer, enabling:

• Multi-method gateways
• Rich pricing logic
• Unified client experience

While keeping subscription state external and compatible with existing NIPs.