NUT-04/05: custom payment methods

04.md

@@ -40,18 +40,25 @@ 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
   "method": <str>,
   "amount_paid": <int>,
   "amount_issued": <int>,
@@ -65,6 +72,7 @@ Where:
 - `quote` is the quote ID in UUID v7 format
 - `request` is the payment request for the quote
 - `unit` corresponds to the value provided in the request
+- `expiry` is the Unix timestamp until which the quote is valid (`null` if it does not expire)
 - `method` is the payment method of the quote
 - `amount_paid` is the total amount that has been paid to the mint for this quote, denominated in `unit`
 - `amount_issued` is the total amount of ecash that has been issued for this quote, denominated in `unit`
@@ -119,6 +127,22 @@ 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 a third party payment processor without validation.
+
 ## Adding New Payment Methods
 
 To add a new payment method (e.g., BOLT12), implement the following:
@@ -168,6 +192,8 @@ Upon receiving the `BlindSignatures` from the mint, the wallet unblinds them to
 
 [00]: 00.md
 [06]: 06.md
+[17]: 17.md
+[19]: 19.md
 [20]: 20.md
 [23]: 23.md
 [25]: 25.md

05.md

@@ -46,26 +46,38 @@ 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
   "method": <str>,
   "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, `method` is the payment method of the quote, 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])
+- `method` is the payment method of the quote
+- `expiry` is the Unix timestamp until which the melt quote is valid.
 
 `state` is an enum string field with possible values `"UNPAID"`, `"PENDING"`, `"PAID"`:
 
@@ -205,6 +217,16 @@ 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.
+
 ## Adding New Payment Methods
 
 To add a new payment method (e.g., BOLT12), implement the following:
@@ -262,6 +284,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