diff --git a/04.md b/04.md index b0aa9a0d4..8728b04f7 100644 --- a/04.md +++ b/04.md @@ -40,11 +40,16 @@ Depending on the payment method, the request structure may vary, but all methods ```json { - "unit": + "unit": , + "amount": , // Optional + "description": , // Optional + "pubkey": // 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 @@ -52,6 +57,8 @@ The mint `Bob` responds with a quote that includes some common fields for all me "quote": , // UUID v7 "request": , "unit": , + "expiry": , + "pubkey": , // Optional "method": , "amount_paid": , "amount_issued": , @@ -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 diff --git a/05.md b/05.md index 1a404e35b..f40f24fca 100644 --- a/05.md +++ b/05.md @@ -46,18 +46,23 @@ Depending on the payment method, the request structure may vary, but all methods ```json { "request": , - "unit": + "unit": , + "amount": // 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": , // UUID v7 + "request": , "amount": , "unit": , + "fee_reserve": , // Optional "method": , "state": , "expiry": @@ -65,7 +70,14 @@ The mint `Bob` responds with a quote that includes some common fields for all me } ``` -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