From 7da82826fb064ad29584bda0ef0d567c855e5ebc Mon Sep 17 00:00:00 2001 From: d11n Date: Fri, 22 Sep 2023 11:49:20 +0200 Subject: [PATCH] API: Document payment method IDs (#5332) * API: Document payment method IDs This seems to be a source of confusion (see e.g. #5330), so I thought it'd be best to document the payment method IDs as an enum, so that we can refer to it in the several places they are used. * Remove enum --- .../v1/swagger.template.custodians.json | 7 +++++-- .../swagger/v1/swagger.template.invoices.json | 18 ++++++++++++------ .../wwwroot/swagger/v1/swagger.template.json | 6 +++++- .../v1/swagger.template.payout-processors.json | 6 ++---- .../v1/swagger.template.pull-payments.json | 10 +++------- .../swagger/v1/swagger.template.stores.json | 11 ++++++----- .../swagger/v1/swagger.template.webhooks.json | 6 +++++- 7 files changed, 38 insertions(+), 26 deletions(-) diff --git a/BTCPayServer/wwwroot/swagger/v1/swagger.template.custodians.json b/BTCPayServer/wwwroot/swagger/v1/swagger.template.custodians.json index b78b832a4..7ce0b7fdb 100644 --- a/BTCPayServer/wwwroot/swagger/v1/swagger.template.custodians.json +++ b/BTCPayServer/wwwroot/swagger/v1/swagger.template.custodians.json @@ -1075,8 +1075,11 @@ "type": "object", "properties": { "paymentMethod": { - "type": "string", - "description": "The payment method (cryptocode + network) of the withdrawal.", + "allOf": [ + { + "$ref": "#/components/schemas/PaymentMethodId" + } + ], "nullable": false }, "qty": { diff --git a/BTCPayServer/wwwroot/swagger/v1/swagger.template.invoices.json b/BTCPayServer/wwwroot/swagger/v1/swagger.template.invoices.json index 2e1ea3e3d..b23d91d61 100644 --- a/BTCPayServer/wwwroot/swagger/v1/swagger.template.invoices.json +++ b/BTCPayServer/wwwroot/swagger/v1/swagger.template.invoices.json @@ -696,9 +696,12 @@ "description": "Description of the pull payment" }, "paymentMethod": { - "type": "string", - "description": "The payment method to use for the refund", - "example": "BTC" + "allOf": [ + { + "$ref": "#/components/schemas/PaymentMethodId" + } + ], + "description": "The payment method to use for the refund" }, "refundVariant": { "type": "string", @@ -1176,7 +1179,11 @@ "description": "A specific set of payment methods to use for this invoice (ie. BTC, BTC-LightningNetwork). By default, select all payment methods enabled in the store." }, "defaultPaymentMethod": { - "type": "string", + "allOf": [ + { + "$ref": "#/components/schemas/PaymentMethodId" + } + ], "nullable": true, "description": "Default payment type for the invoice (e.g., BTC, BTC-LightningNetwork). Default payment method set for the store is used if this parameter is not specified." }, @@ -1276,8 +1283,7 @@ "additionalProperties": false, "properties": { "paymentMethod": { - "type": "string", - "description": "Payment method available for the invoice (e.g., \"BTC\" or \"BTC-LightningNetwork\" or \"BTC-LNURLPAY\")" + "$ref": "#/components/schemas/PaymentMethodId" }, "cryptoCode": { "type": "string", diff --git a/BTCPayServer/wwwroot/swagger/v1/swagger.template.json b/BTCPayServer/wwwroot/swagger/v1/swagger.template.json index f65ee5769..edf6c1a2e 100644 --- a/BTCPayServer/wwwroot/swagger/v1/swagger.template.json +++ b/BTCPayServer/wwwroot/swagger/v1/swagger.template.json @@ -115,6 +115,10 @@ ], "format": "minutes", "description": "A span of times in minutes" + }, + "PaymentMethodId": { + "type": "string", + "description": "Payment method IDs are a combination of crypto code and payment type. Available payment method IDs for Bitcoin are: \n- `\"BTC-OnChain\"` (with the equivalent of `\"BTC\"`) \n-`\"BTC-LightningLike\"`: Any supported LN-based payment method (Lightning or LNURL) \n- `\"BTC-LightningNetwork\"`: Lightning \n- `\"BTC-LNURLPAY\"`: LNURL \n \nNote: Separator can be either `-` or `_`." } }, "securitySchemes": { @@ -137,4 +141,4 @@ "Basic": [] } ] -} \ No newline at end of file +} diff --git a/BTCPayServer/wwwroot/swagger/v1/swagger.template.payout-processors.json b/BTCPayServer/wwwroot/swagger/v1/swagger.template.payout-processors.json index 04485cbed..68445553b 100644 --- a/BTCPayServer/wwwroot/swagger/v1/swagger.template.payout-processors.json +++ b/BTCPayServer/wwwroot/swagger/v1/swagger.template.payout-processors.json @@ -600,8 +600,7 @@ "additionalProperties": false, "properties": { "paymentMethod": { - "description": "payment method of the payout processor", - "type": "string" + "$ref": "#/components/schemas/PaymentMethodId" }, "intervalSeconds": { "description": "How often should the processor run", @@ -659,8 +658,7 @@ "additionalProperties": false, "properties": { "paymentMethod": { - "description": "payment method of the payout processor", - "type": "string" + "$ref": "#/components/schemas/PaymentMethodId" }, "feeTargetBlock": { "type": "number", diff --git a/BTCPayServer/wwwroot/swagger/v1/swagger.template.pull-payments.json b/BTCPayServer/wwwroot/swagger/v1/swagger.template.pull-payments.json index cb22dbb6a..529156db8 100644 --- a/BTCPayServer/wwwroot/swagger/v1/swagger.template.pull-payments.json +++ b/BTCPayServer/wwwroot/swagger/v1/swagger.template.pull-payments.json @@ -455,7 +455,7 @@ } ], "post": { - "summary": "Create Payout ", + "summary": "Create Payout", "description": "Create a new payout", "operationId": "Payouts_CreatePayoutThroughStore", "requestBody": { @@ -883,9 +883,7 @@ "description": "The amount of the payout in the currency of the pull payment (eg. USD)." }, "paymentMethod": { - "type": "string", - "example": "BTC", - "description": "The payment method of the payout" + "$ref": "#/components/schemas/PaymentMethodId" } } }, @@ -995,9 +993,7 @@ "description": "The amount of the payout in the currency of the pull payment (eg. USD)." }, "paymentMethod": { - "type": "string", - "example": "BTC", - "description": "The payment method of the payout (e.g., \"BTC\" or \"BTC_LightningLike\"" + "$ref": "#/components/schemas/PaymentMethodId" }, "cryptoCode": { "type": "string", diff --git a/BTCPayServer/wwwroot/swagger/v1/swagger.template.stores.json b/BTCPayServer/wwwroot/swagger/v1/swagger.template.stores.json index 843f93daa..c07614771 100644 --- a/BTCPayServer/wwwroot/swagger/v1/swagger.template.stores.json +++ b/BTCPayServer/wwwroot/swagger/v1/swagger.template.stores.json @@ -367,8 +367,11 @@ "type": "object", "properties": { "paymentMethod": { - "type": "string", - "description": "The payment method (e.g., \"BTC\" or \"BTC_LightningLike\")", + "allOf": [ + { + "$ref": "#/components/schemas/PaymentMethodId" + } + ], "nullable": false }, "currencyCode": { @@ -541,9 +544,7 @@ "description": "If true, payment methods are enabled individually upon user interaction in the invoice" }, "defaultPaymentMethod": { - "type": "string", - "example": "BTC", - "description": "The default payment method to load when displaying an invoice. It can be in the format of `BTC_LightningNetwork` to specify Lightning to be the default or `BTC_OnChain`/ `BTC` for on-chain to be the default. " + "$ref": "#/components/schemas/PaymentMethodId" }, "paymentMethodCriteria": { "type": "array", diff --git a/BTCPayServer/wwwroot/swagger/v1/swagger.template.webhooks.json b/BTCPayServer/wwwroot/swagger/v1/swagger.template.webhooks.json index 53e391c9e..1ff5d7457 100644 --- a/BTCPayServer/wwwroot/swagger/v1/swagger.template.webhooks.json +++ b/BTCPayServer/wwwroot/swagger/v1/swagger.template.webhooks.json @@ -780,7 +780,11 @@ "nullable": false }, "paymentMethod": { - "type": "string", + "allOf": [ + { + "$ref": "#/components/schemas/PaymentMethodId" + } + ], "description": "What payment method was used for this payment", "nullable": false },