mirror of
https://github.com/btcpayserver/btcpayserver.git
synced 2025-02-23 06:35:13 +01:00
3576ebd14f
* Public Invoice receipt * implement payment,s qr, better ui, and fix invoice bug * General view updates * Update admin details link * Update view * add missing check * Refactor * make payments and qr shown by default * move cusotmization options to own ReceiptOptions * Make sure to sanitize values inside PosData partial * Refactor * Make sure that ReceiptOptions for the StoreData is never null, and that values are always set in API * add receipt link to checkout and add tests * add receipt link to lnurl * Use ReceiptOptions.Merge * fix lnurl * fix chrome * remove i18n parameterization * Fix swagger * Update translations * Fix warning Co-authored-by: Dennis Reimann <mail@dennisreimann.de> Co-authored-by: nicolas.dorier <nicolas.dorier@gmail.com>
1270 lines
52 KiB
JSON
1270 lines
52 KiB
JSON
{
|
|
"paths": {
|
|
"/api/v1/stores/{storeId}/invoices": {
|
|
"get": {
|
|
"tags": [
|
|
"Invoices"
|
|
],
|
|
"summary": "Get invoices",
|
|
"parameters": [
|
|
{
|
|
"name": "storeId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The store to query",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "orderId",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "Array of OrderIds to fetch the invoices for",
|
|
"schema": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"example": "1000&orderId=1001&orderId=1002"
|
|
},
|
|
{
|
|
"name": "status",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "Array of statuses of invoices to be fetched",
|
|
"$ref": "#/components/schemas/InvoiceStatus"
|
|
},
|
|
{
|
|
"name": "textSearch",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "A term that can help locating specific invoices.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "startDate",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "Start date of the period to retrieve invoices",
|
|
"$ref": "#/components/schemas/UnixTimestamp"
|
|
},
|
|
{
|
|
"name": "endDate",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "End date of the period to retrieve invoices",
|
|
"$ref": "#/components/schemas/UnixTimestamp"
|
|
},
|
|
{
|
|
"name": "skip",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "Number of records to skip",
|
|
"schema": {
|
|
"nullable": true,
|
|
"type": "number"
|
|
}
|
|
},
|
|
{
|
|
"name": "take",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "Number of records returned in response",
|
|
"schema": {
|
|
"nullable": true,
|
|
"type": "number"
|
|
}
|
|
}
|
|
],
|
|
"description": "View information about the existing invoices",
|
|
"operationId": "Invoices_GetInvoices",
|
|
"responses": {
|
|
"200": {
|
|
"description": "list of invoices",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/InvoiceDataList"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"API_Key": [
|
|
"btcpay.store.canviewinvoices"
|
|
],
|
|
"Basic": []
|
|
}
|
|
]
|
|
},
|
|
"post": {
|
|
"tags": [
|
|
"Invoices"
|
|
],
|
|
"summary": "Create a new invoice",
|
|
"parameters": [
|
|
{
|
|
"name": "storeId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The store to query",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"description": "Create a new invoice",
|
|
"operationId": "Invoices_CreateInvoice",
|
|
"responses": {
|
|
"200": {
|
|
"description": "Information about the new invoice",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/InvoiceData"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "A list of errors that occurred when creating the invoice",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ValidationProblemDetails"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "If you are authenticated but forbidden to add new invoices"
|
|
}
|
|
},
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/CreateInvoiceRequest"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"API_Key": [
|
|
"btcpay.store.cancreateinvoice"
|
|
],
|
|
"Basic": []
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/stores/{storeId}/invoices/{invoiceId}": {
|
|
"get": {
|
|
"tags": [
|
|
"Invoices"
|
|
],
|
|
"summary": "Get invoice",
|
|
"parameters": [
|
|
{
|
|
"name": "storeId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The store to fetch",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "invoiceId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The invoice to fetch",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"description": "View information about the specified invoice",
|
|
"operationId": "Invoices_GetInvoice",
|
|
"responses": {
|
|
"200": {
|
|
"description": "specified invoice",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/InvoiceData"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "If you are authenticated but forbidden to view the specified invoice"
|
|
},
|
|
"404": {
|
|
"description": "The key is not found for this invoice"
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"API_Key": [
|
|
"btcpay.store.canviewinvoices"
|
|
],
|
|
"Basic": []
|
|
}
|
|
]
|
|
},
|
|
"delete": {
|
|
"tags": [
|
|
"Invoices"
|
|
],
|
|
"summary": "Archive invoice",
|
|
"description": "Archives the specified invoice.",
|
|
"operationId": "Invoices_ArchiveInvoice",
|
|
"parameters": [
|
|
{
|
|
"name": "storeId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The store the invoice belongs to",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "invoiceId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The invoice to remove",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "The invoice has been archived"
|
|
},
|
|
"400": {
|
|
"description": "A list of errors that occurred when archiving the invoice",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ValidationProblemDetails"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "If you are authenticated but forbidden to archive the specified invoice"
|
|
},
|
|
"404": {
|
|
"description": "The key is not found for this invoice"
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"API_Key": [
|
|
"btcpay.store.canmodifyinvoices"
|
|
],
|
|
"Basic": []
|
|
}
|
|
]
|
|
},
|
|
"put": {
|
|
"tags": [
|
|
"Invoices"
|
|
],
|
|
"summary": "Update invoice",
|
|
"description": "Updates the specified invoice.",
|
|
"operationId": "Invoices_UpdateInvoice",
|
|
"parameters": [
|
|
{
|
|
"name": "storeId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The store the invoice belongs to",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "invoiceId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The invoice to update",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "The invoice that has been updated",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/InvoiceData"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "A list of errors that occurred when updating the invoice",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ValidationProblemDetails"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "If you are authenticated but forbidden to update the specified invoice"
|
|
},
|
|
"404": {
|
|
"description": "The key is not found for this invoice"
|
|
}
|
|
},
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/UpdateInvoiceRequest"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"API_Key": [
|
|
"btcpay.store.canmodifyinvoices"
|
|
],
|
|
"Basic": []
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/stores/{storeId}/invoices/{invoiceId}/payment-methods": {
|
|
"get": {
|
|
"tags": [
|
|
"Invoices"
|
|
],
|
|
"summary": "Get invoice payment methods",
|
|
"parameters": [
|
|
{
|
|
"name": "storeId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The store to fetch",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "invoiceId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The invoice to fetch",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "onlyAccountedPayments",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "If default or true, only returns payments which are accounted (in Bitcoin, this mean not returning RBF'd or double spent payments)",
|
|
"schema": {
|
|
"type": "boolean",
|
|
"default": true
|
|
}
|
|
}
|
|
],
|
|
"description": "View information about the specified invoice's payment methods",
|
|
"operationId": "Invoices_GetInvoicePaymentMethods",
|
|
"responses": {
|
|
"200": {
|
|
"description": "specified invoice payment methods data",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "array",
|
|
"nullable": false,
|
|
"items": {
|
|
"$ref": "#/components/schemas/InvoicePaymentMethodDataModel"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "If you are authenticated but forbidden to view the specified invoice"
|
|
},
|
|
"404": {
|
|
"description": "The key is not found for this invoice"
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"API_Key": [
|
|
"btcpay.store.canviewinvoices"
|
|
],
|
|
"Basic": []
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/stores/{storeId}/invoices/{invoiceId}/status": {
|
|
"post": {
|
|
"tags": [
|
|
"Invoices"
|
|
],
|
|
"summary": "Mark invoice status",
|
|
"parameters": [
|
|
{
|
|
"name": "storeId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The store to query",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "invoiceId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The invoice to update",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"description": "Mark an invoice as invalid or settled.",
|
|
"operationId": "Invoices_MarkInvoiceStatus",
|
|
"responses": {
|
|
"200": {
|
|
"description": "The updated invoice",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/InvoiceData"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "A list of errors that occurred when updating the invoice",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ValidationProblemDetails"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "If you are authenticated but forbidden to update the invoice"
|
|
}
|
|
},
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/MarkInvoiceStatusRequest"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"API_Key": [
|
|
"btcpay.store.canmodifyinvoices"
|
|
],
|
|
"Basic": []
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/stores/{storeId}/invoices/{invoiceId}/unarchive": {
|
|
"post": {
|
|
"tags": [
|
|
"Invoices"
|
|
],
|
|
"summary": "Unarchive invoice",
|
|
"parameters": [
|
|
{
|
|
"name": "storeId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The store to query",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "invoiceId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The invoice to update",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"description": "Unarchive an invoice",
|
|
"operationId": "Invoices_UnarchiveInvoice",
|
|
"responses": {
|
|
"200": {
|
|
"description": "The unarchived invoice",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/InvoiceData"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "A list of errors that occurred when updating the invoice",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ValidationProblemDetails"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "If you are authenticated but forbidden to update the invoice"
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"API_Key": [
|
|
"btcpay.store.canmodifyinvoices"
|
|
],
|
|
"Basic": []
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/stores/{storeId}/invoices/{invoiceId}/payment-methods/{paymentMethod}/activate": {
|
|
"post": {
|
|
"tags": [
|
|
"Invoices"
|
|
],
|
|
"summary": "Activate Payment Method",
|
|
"parameters": [
|
|
{
|
|
"name": "storeId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The store to query",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "invoiceId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The invoice to update",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "paymentMethod",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The payment method to activate",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"description": "Activate an invoice payment method (if lazy payments mode is enabled)",
|
|
"operationId": "Invoices_ActivatePaymentMethod",
|
|
"responses": {
|
|
"200": {
|
|
"description": ""
|
|
},
|
|
"400": {
|
|
"description": "A list of errors that occurred when updating the invoice",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ValidationProblemDetails"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"description": "If you are authenticated but forbidden to activate the invoice payment method"
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"API_Key": [
|
|
"btcpay.store.canviewinvoices"
|
|
],
|
|
"Basic": []
|
|
}
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"components": {
|
|
"schemas": {
|
|
"InvoiceDataList": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/InvoiceData"
|
|
}
|
|
},
|
|
"MarkInvoiceStatusRequest": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"status": {
|
|
"nullable": false,
|
|
"description": "Mark an invoice as completed or invalid.",
|
|
"$ref": "#/components/schemas/InvoiceStatusMark"
|
|
}
|
|
}
|
|
},
|
|
"AddCustomerEmailRequest": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"email": {
|
|
"type": "string",
|
|
"nullable": false,
|
|
"description": "Sets the customer email, if it was not set before."
|
|
}
|
|
}
|
|
},
|
|
"InvoiceStatusMark": {
|
|
"type": "string",
|
|
"description": "",
|
|
"x-enumNames": [
|
|
"Invalid",
|
|
"Settled"
|
|
],
|
|
"enum": [
|
|
"Invalid",
|
|
"Settled"
|
|
]
|
|
},
|
|
"InvoiceStatus": {
|
|
"type": "string",
|
|
"description": "",
|
|
"x-enumNames": [
|
|
"New",
|
|
"Processing",
|
|
"Expired",
|
|
"Invalid",
|
|
"Settled"
|
|
],
|
|
"enum": [
|
|
"New",
|
|
"Processing",
|
|
"Expired",
|
|
"Invalid",
|
|
"Settled"
|
|
]
|
|
},
|
|
"InvoiceAdditionalStatus": {
|
|
"type": "string",
|
|
"description": "An additional status that describes why an invoice is in its current status.",
|
|
"x-enumNames": [
|
|
"None",
|
|
"PaidLate",
|
|
"PaidPartial",
|
|
"Marked",
|
|
"Invalid",
|
|
"PaidOver"
|
|
],
|
|
"enum": [
|
|
"None",
|
|
"PaidLate",
|
|
"PaidPartial",
|
|
"Marked",
|
|
"Invalid",
|
|
"PaidOver"
|
|
]
|
|
},
|
|
"InvoiceDataBase": {
|
|
"properties": {
|
|
"metadata": {
|
|
"$ref": "#/components/schemas/InvoiceMetadata"
|
|
},
|
|
"checkout": {
|
|
"nullable": true,
|
|
"$ref": "#/components/schemas/CheckoutOptions",
|
|
"description": "Additional settings to customize the checkout flow"
|
|
},
|
|
"receipt": {
|
|
"nullable": true,
|
|
"$ref": "#/components/schemas/ReceiptOptions",
|
|
"description": "Additional settings to customize the public receipt"
|
|
}
|
|
}
|
|
},
|
|
"InvoiceData": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/InvoiceDataBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "The identifier of the invoice"
|
|
},
|
|
"storeId": {
|
|
"type": "string",
|
|
"description": "The store identifier that the invoice belongs to"
|
|
},
|
|
"amount": {
|
|
"type": "string",
|
|
"format": "decimal",
|
|
"description": "The amount of the invoice",
|
|
"example": "5.00"
|
|
},
|
|
"currency": {
|
|
"type": "string",
|
|
"description": "The currency of the invoice",
|
|
"example": "USD"
|
|
},
|
|
"type": {
|
|
"$ref": "#/components/schemas/InvoiceType",
|
|
"description": "The type of invoice"
|
|
},
|
|
"checkoutLink": {
|
|
"type": "string",
|
|
"description": "The link to the checkout page, where you can redirect the customer"
|
|
},
|
|
"createdTime": {
|
|
"description": "The creation time of the invoice",
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/UnixTimestamp"
|
|
}
|
|
]
|
|
},
|
|
"expirationTime": {
|
|
"description": "The expiration time of the invoice",
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/UnixTimestamp"
|
|
}
|
|
]
|
|
},
|
|
"monitoringTime": {
|
|
"description": "The monitoring time of the invoice",
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/UnixTimestamp"
|
|
}
|
|
]
|
|
},
|
|
"status": {
|
|
"$ref": "#/components/schemas/InvoiceStatus",
|
|
"description": "The status of the invoice"
|
|
},
|
|
"additionalStatus": {
|
|
"$ref": "#/components/schemas/InvoiceAdditionalStatus",
|
|
"description": "a secondary status of the invoice"
|
|
},
|
|
"availableStatusesForManualMarking": {
|
|
"type": "array",
|
|
"description": "The statuses the invoice can be manually marked as",
|
|
"items": {
|
|
"$ref": "#/components/schemas/InvoiceStatus"
|
|
}
|
|
},
|
|
"archived": {
|
|
"type": "boolean",
|
|
"description": "true if the invoice is archived"
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"InvoiceMetadataPosString": {
|
|
"type": "string",
|
|
"description": "shown on the invoice details page"
|
|
},
|
|
"InvoiceMetadataPosObject": {
|
|
"type": "object",
|
|
"description": "Any json object in any schema you want. Will be rendered on a best effort basis in terms of style on the invoice details UI"
|
|
},
|
|
"InvoiceMetadata": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Additional information around the invoice that can be supplied. The mentioned properties are all optional and you can introduce any json format you wish.",
|
|
"anyOf": [
|
|
{
|
|
"properties": {
|
|
"orderId": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "You can use this property to store the ID of an external system. We allow you to search in the invoice list based on this ID."
|
|
},
|
|
"orderUrl": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "You can use this property to store the URL to the order of an external system. This makes navigating to the order easier."
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"properties": {
|
|
"posData": {
|
|
"oneOf": [
|
|
{
|
|
"$ref": "#/components/schemas/InvoiceMetadataPosString"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/InvoiceMetadataPosObject"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"properties": {
|
|
"buyerName": {
|
|
"type": "string",
|
|
"nullable": true
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"properties": {
|
|
"buyerEmail": {
|
|
"type": "string",
|
|
"nullable": true
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"properties": {
|
|
"buyerCountry": {
|
|
"type": "string",
|
|
"nullable": true
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"properties": {
|
|
"buyerZip": {
|
|
"type": "string",
|
|
"nullable": true
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"properties": {
|
|
"buyerState": {
|
|
"type": "string",
|
|
"nullable": true
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"properties": {
|
|
"buyerCity": {
|
|
"type": "string",
|
|
"nullable": true
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"properties": {
|
|
"buyerAddress1": {
|
|
"type": "string",
|
|
"nullable": true
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"properties": {
|
|
"buyerAddress2": {
|
|
"type": "string",
|
|
"nullable": true
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"properties": {
|
|
"buyerPhone": {
|
|
"type": "string",
|
|
"nullable": true
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"properties": {
|
|
"itemDesc": {
|
|
"type": "string",
|
|
"nullable": true
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"properties": {
|
|
"itemCode": {
|
|
"type": "string",
|
|
"nullable": true
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"properties": {
|
|
"physical": {
|
|
"type": "string",
|
|
"nullable": true
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"properties": {
|
|
"taxIncluded": {
|
|
"type": "number",
|
|
"nullable": true
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"CreateInvoiceRequest": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/InvoiceDataBase"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"amount": {
|
|
"type": "string",
|
|
"format": "decimal",
|
|
"nullable": true,
|
|
"description": "The amount of the invoice. If null or unspecified, the invoice will be a top-up invoice. (ie. The invoice will consider any payment as a full payment)",
|
|
"example": "5.00"
|
|
},
|
|
"currency": {
|
|
"type": "string",
|
|
"description": "The currency of the invoice (if null, empty or unspecified, the currency will be the store's settings default)'",
|
|
"nullable": true,
|
|
"example": "USD"
|
|
},
|
|
"additionalSearchTerms": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Additional search term to help you find this invoice via text search",
|
|
"nullable": true
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"UpdateInvoiceRequest": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"metadata": {
|
|
"$ref": "#/components/schemas/InvoiceMetadata"
|
|
}
|
|
}
|
|
},
|
|
"CheckoutOptions": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"speedPolicy": {
|
|
"nullable": true,
|
|
"$ref": "#/components/schemas/SpeedPolicy",
|
|
"description": "This is a risk mitigation parameter for the merchant to configure how they want to fulfill orders depending on the number of block confirmations for the transaction made by the consumer on the selected cryptocurrency"
|
|
},
|
|
"paymentMethods": {
|
|
"type": "array",
|
|
"nullable": true,
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"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",
|
|
"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."
|
|
},
|
|
"expirationMinutes": {
|
|
"nullable": true,
|
|
"description": "The number of minutes after which an invoice becomes expired. Defaults to the store's settings. (The default store settings is 15)",
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/TimeSpanMinutes"
|
|
}
|
|
]
|
|
},
|
|
"monitoringMinutes": {
|
|
"type": "number",
|
|
"nullable": true,
|
|
"description": "The number of minutes after an invoice expired after which we are still monitoring for incoming payments. Defaults to the store's settings. (The default store settings is 1440, 1 day)",
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/TimeSpanMinutes"
|
|
}
|
|
]
|
|
},
|
|
"paymentTolerance": {
|
|
"type": "number",
|
|
"format": "double",
|
|
"nullable": true,
|
|
"minimum": 0,
|
|
"maximum": 100,
|
|
"description": "A percentage determining whether to count the invoice as paid when the invoice is paid within the specified margin of error. Defaults to the store's settings. (The default store settings is 100)"
|
|
},
|
|
"redirectURL": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "When the customer has paid the invoice, the URL where the customer will be redirected when clicking on the `return to store` button. You can use placeholders `{InvoiceId}` or `{OrderId}` in the URL, BTCPay Server will replace those with this invoice `id` or `metadata.orderId` respectively."
|
|
},
|
|
"redirectAutomatically": {
|
|
"type": "boolean",
|
|
"nullable": true,
|
|
"description": "When the customer has paid the invoice, and a `redirectURL` is set, the checkout is redirected to `redirectURL` automatically if `redirectAutomatically` is true. Defaults to the store's settings. (The default store settings is false)"
|
|
},
|
|
"requiresRefundEmail": {
|
|
"type": "boolean",
|
|
"nullable": true,
|
|
"description": "Invoice will require user to provide a refund email if this option is set to `true`. Has no effect if `buyerEmail` metadata is set as there is no email to collect in this case."
|
|
},
|
|
"defaultLanguage": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "The language code (eg. en-US, en, fr-FR...) of the language presented to your customer in the checkout page. BTCPay Server tries to match the best language available. If null or not set, will fallback on the store's default language. You can see the list of language codes with [this operation](#operation/langCodes)."
|
|
}
|
|
}
|
|
},
|
|
"ReceiptOptions": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"enabled": {
|
|
"type": "boolean",
|
|
"nullable": true,
|
|
"description": "A public page will be accessible once the invoice is settled. If null or unspecified, it will fallback to the store's settings. (The default store settings is true)"
|
|
},
|
|
"showQR": {
|
|
"type": "boolean",
|
|
"nullable": true,
|
|
"default": null,
|
|
"description": "Show the QR code of the receipt in the public receipt page. If null or unspecified, it will fallback to the store's settings. (The default store setting is true)"
|
|
},
|
|
"showPayments": {
|
|
"type": "boolean",
|
|
"nullable": true,
|
|
"default": null,
|
|
"description": "Show the payment list in the public receipt page. If null or unspecified, it will fallback to the store's settings. (The default store setting is true)"
|
|
}
|
|
}
|
|
},
|
|
"SpeedPolicy": {
|
|
"type": "string",
|
|
"description": "`\"HighSpeed\"`: 0 confirmations (1 confirmation if RBF enabled in transaction) \n`\"MediumSpeed\"`: 1 confirmation \n`\"LowMediumSpeed\"`: 2 confirmations \n`\"LowSpeed\"`: 6 confirmations\n",
|
|
"x-enumNames": [
|
|
"HighSpeed",
|
|
"MediumSpeed",
|
|
"LowSpeed",
|
|
"LowMediumSpeed"
|
|
],
|
|
"enum": [
|
|
"HighSpeed",
|
|
"MediumSpeed",
|
|
"LowSpeed",
|
|
"LowMediumSpeed"
|
|
]
|
|
},
|
|
"InvoicePaymentMethodDataModel": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"paymentMethod": {
|
|
"type": "string",
|
|
"description": "Payment method available for the invoice (e.g., \"BTC\" or \"BTC-LightningNetwork\" or \"BTC-LNURLPAY\")"
|
|
},
|
|
"cryptoCode": {
|
|
"type": "string",
|
|
"description": "Crypto code of the payment method (e.g., \"BTC\" or \"LTC\")",
|
|
"example": "BTC"
|
|
},
|
|
"destination": {
|
|
"type": "string",
|
|
"description": "The destination the payment must be made to"
|
|
},
|
|
"paymentLink": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "A payment link that helps pay to the payment destination"
|
|
},
|
|
"rate": {
|
|
"type": "string",
|
|
"format": "decimal",
|
|
"description": "The rate between this payment method's currency and the invoice currency"
|
|
},
|
|
"paymentMethodPaid": {
|
|
"type": "string",
|
|
"format": "decimal",
|
|
"description": "The amount paid by this payment method"
|
|
},
|
|
"totalPaid": {
|
|
"type": "string",
|
|
"format": "decimal",
|
|
"description": "The total amount paid by all payment methods to the invoice, converted to this payment method's currency"
|
|
},
|
|
"due": {
|
|
"type": "string",
|
|
"format": "decimal",
|
|
"description": "The total amount left to be paid, converted to this payment method's currency (will be negative if overpaid)"
|
|
},
|
|
"amount": {
|
|
"type": "string",
|
|
"format": "decimal",
|
|
"description": "The invoice amount, converted to this payment method's currency"
|
|
},
|
|
"networkFee": {
|
|
"type": "string",
|
|
"format": "decimal",
|
|
"description": "The added merchant fee to pay for network costs of this payment method."
|
|
},
|
|
"payments": {
|
|
"type": "array",
|
|
"nullable": false,
|
|
"items": {
|
|
"$ref": "#/components/schemas/Payment"
|
|
},
|
|
"description": "Payments made with this payment method."
|
|
},
|
|
"activated": {
|
|
"type": "boolean",
|
|
"description": "If the payment method is activated (when lazy payments option is enabled"
|
|
},
|
|
"additionalData": {
|
|
"description": "Additional data provided by the payment method.",
|
|
"anyOf": [
|
|
{
|
|
"type": "object",
|
|
"description": "LNURL Pay information",
|
|
"properties": {
|
|
"providedComment": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "The provided comment to a LNUrl payment with comments enabled",
|
|
"example": "Thank you!"
|
|
},
|
|
"consumedLightningAddress": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "The consumed lightning address of a LN Address payment",
|
|
"example": "customer@example.com"
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "No additional information"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"Payment": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "A unique identifier for this payment"
|
|
},
|
|
"receivedDate": {
|
|
"description": "The date the payment was recorded",
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/UnixTimestamp"
|
|
}
|
|
]
|
|
},
|
|
"value": {
|
|
"type": "string",
|
|
"format": "decimal",
|
|
"description": "The value of the payment"
|
|
},
|
|
"fee": {
|
|
"type": "string",
|
|
"format": "decimal",
|
|
"description": "The fee paid for the payment"
|
|
},
|
|
"status": {
|
|
"$ref": "#/components/schemas/PaymentStatus",
|
|
"description": "The status of the payment"
|
|
},
|
|
"destination": {
|
|
"type": "string",
|
|
"description": "The destination the payment was made to"
|
|
}
|
|
}
|
|
},
|
|
"PaymentStatus": {
|
|
"type": "string",
|
|
"description": "",
|
|
"x-enumNames": [
|
|
"Invalid",
|
|
"Processing",
|
|
"Settled"
|
|
],
|
|
"enum": [
|
|
"Invalid",
|
|
"Processing",
|
|
"Settled"
|
|
]
|
|
},
|
|
"InvoiceType": {
|
|
"type": "string",
|
|
"description": "",
|
|
"x-enumNames": [
|
|
"Standard",
|
|
"TopUp"
|
|
],
|
|
"enum": [
|
|
"Standard",
|
|
"TopUp"
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"tags": [
|
|
{
|
|
"name": "Invoices"
|
|
}
|
|
]
|
|
}
|