custom payment methods

04.md

@@ -40,23 +40,30 @@ Depending on the payment method, the request structure may vary, but all methods
 
 ```json
 {
-  "unit": <str_enum[UNIT]>
+  "unit": <str_enum[UNIT]>,
+  "amount": <int>,        // Optional
+  "description": <str>,   // Optional
+  "pubkey": <str>         // Optional, NUT-20
   // Additional method-specific fields may be required
 }
 ```
 
+`amount`, `description` and `pubkey` are common optional fields; method-specific NUTs make them required or ignore them as needed (e.g. NUT-23 requires `amount`, NUT-20 defines `pubkey`).
+
 The mint `Bob` responds with a quote that includes some common fields for all methods:
 
 ```json
 {
   "quote": <str>, // UUID v7
   "request": <str>,
   "unit":  <str_enum[UNIT]>,
+  "expiry": <int|null>,
+  "pubkey": <str>             // Optional
   // Additional method-specific fields will be included
 }
 ```
 
-Where `quote` is the quote ID string in UUID v7 format, `request` is the payment request for the quote, and `unit` corresponds to the value provided in the request.
+Where `quote` is the quote ID string in UUID v7 format, `request` is the payment request for the quote, `unit` corresponds to the value provided in the request, and `expiry` is the Unix timestamp until which the quote is valid (`null` if it does not expire).
 
 > [!CAUTION]
 >
@@ -101,6 +108,34 @@ The mint then responds with:
 
 where `signatures` is an array of blind signatures on the outputs.
 
+## Custom Payment Methods
+
+Payment methods not specified in a dedicated NUT can be supported as custom payment methods. A custom payment method is identified by a lowercase string `{method}` (e.g., `paypal`, `stripe`, `onchain-payment-processor`). The `{method}` string **MUST** contain only ASCII alphanumeric characters, hyphens (`-`), and underscores (`_`), and **MUST** be non-empty.
+
+### Mint Quote
+
+For a custom `{method}`, the wallet sends a request following the common mint quote request format (see [General Flow](#general-flow)). Method-specific fields (e.g., an `amount` of tokens to mint, a `description`, or a `pubkey` for [NUT-20][20] locks) are defined by the method-specific NUT.
+
+The mint responds with the common mint quote response format and **MUST** include the `amount_paid`, `amount_issued` and `updated_at` accounting fields. The `request` field contains the method-specific payment request (e.g., a payment URL, an on-chain address, an account identifier). Additional method-specific fields are defined by the method-specific NUT.
+
+### Method-Specific Fields
+
+Custom payment methods **MAY** include additional fields in requests and responses. Implementations **MUST** ignore unrecognized fields to preserve forward compatibility. When a custom method gains widespread adoption, its fields **MAY** be formalized in a dedicated NUT.
+
+Custom payment methods **MAY** include extra fields that the mint forwards to the payment processor without validation.
+
+### Websocket Notifications
+
+Custom methods **MAY** support websocket subscriptions via [NUT-17][17] with kind `"{method}_mint_quote"`.
+
+### Cached Responses
+
+Custom method endpoints **MAY** support caching via [NUT-19][19] (e.g., `POST /v1/mint/{method}`).
+
+### Amount Precision
+
+If an `amount` is provided, fiat-denominated units (e.g., `usd`, `eur`) **SHOULD** represent the value in the smallest currency unit (e.g., cents). For example, `"amount": 100` with `"unit": "usd"` represents $1.00 USD.
+
 ## Adding New Payment Methods
 
 To add a new payment method (e.g., BOLT12), implement the following:

05.md

@@ -46,25 +46,30 @@ Depending on the payment method, the request structure may vary, but all methods
 ```json
 {
   "request": <str>,
-  "unit": <str_enum[UNIT]>
+  "unit": <str_enum[UNIT]>,
+  "amount": <int>   // Optional
   // Additional method-specific fields will be required
 }
 ```
 
+`amount` is a common optional field; method-specific NUTs make it required or ignore it as needed (e.g. NUT-30 requires `amount` for onchain melts).
+
 The mint `Bob` responds with a quote that includes some common fields for all methods:
 
 ```json
 {
   "quote": <str>, // UUID v7
+  "request": <str>,
   "amount": <int>,
   "unit": <str_enum[UNIT]>,
+  "fee_reserve": <int>,     // Optional
   "state": <str_enum[STATE]>,
   "expiry": <int>
   // Additional method-specific fields will be included
 }
 ```
 
-Where `quote` is the quote ID string in UUID v7 format with all 74 variable bits generated by a CSPRNG, `amount` and `unit` the amount and unit that need to be provided, and `expiry` is the Unix timestamp until which the melt quote is valid.
+Where `quote` is the quote ID string in UUID v7 format with all 74 variable bits generated by a CSPRNG, `request` is the method-specific payment routing target, `amount` and `unit` the amount and unit that need to be provided, `fee_reserve` is the additional fee reserve for using the method (the wallet provides proofs covering at least `amount + fee_reserve + fee`, where `fee` is the keyset input fee per [NUT-02][02]), and `expiry` is the Unix timestamp until which the melt quote is valid.
 
 `state` is an enum string field with possible values `"UNPAID"`, `"PENDING"`, `"PAID"`:
 
@@ -203,6 +208,24 @@ GET https://mint.host:3338/v1/melt/quote/bolt11/019e6d5a-2347-7000-89e2-35fe79f9
 }
 ```
 
+## Custom Payment Methods
+
+Payment methods not specified in a dedicated NUT can be supported as custom payment methods. See [NUT-04][04] for the custom method identifier definition and general conventions.
+
+### Melt Quote
+
+For a custom `{method}`, the wallet sends a request following the common melt quote request format (see [General Flow](#general-flow)). The `request` field is the method-specific payment target (e.g., a bank account identifier, an on-chain address, a payment processor reference). `unit` is the unit the wallet would like to pay with.
+
+The mint responds with the common melt quote response format, using the standard `state` values (`"UNPAID"`, `"PENDING"`, `"PAID"`). Method-specific fields are defined by the method-specific NUT.
+
+### Websocket Notifications
+
+Custom methods **MAY** support websocket subscriptions via [NUT-17][17] with kind `"{method}_melt_quote"`.
+
+### Cached Responses
+
+Custom method endpoints **MAY** support caching via [NUT-19][19] (e.g., `POST /v1/melt/{method}`).
+
 ## Adding New Payment Methods
 
 To add a new payment method (e.g., BOLT12), implement the following:
@@ -257,6 +280,8 @@ The mint's settings for this NUT indicate the supported method-unit pairs for me
 [10]: 10.md
 [11]: 11.md
 [12]: 12.md
+[17]: 17.md
+[19]: 19.md
 [23]: 23.md
 [25]: 25.md
 [30]: 30.md