mirror of
https://github.com/btcpayserver/btcpayserver.git
synced 2025-02-24 06:47:50 +01:00
cd9feccf6e
* Mark Payouts as Paid This PR allows users to mark payouts as paid manually through the UI and through the API. It also sets up the payout proof system to be able store a manual proof that will in a later PR allow you to specify a proof of payment (link or text) * add docs, test and greenfield client * remove extra docs stuff * Update BTCPayServer.Tests/GreenfieldAPITests.cs Co-authored-by: britttttk <39231115+britttttk@users.noreply.github.com> * clean up pull payment/payouts fetch code * Ensure payoutis are retrieved with pull payment Co-authored-by: britttttk <39231115+britttttk@users.noreply.github.com>
627 lines
26 KiB
JSON
627 lines
26 KiB
JSON
{
|
|
"paths": {
|
|
"/api/v1/stores/{storeId}/pull-payments": {
|
|
"parameters": [
|
|
{
|
|
"name": "storeId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The store ID",
|
|
"schema": { "type": "string" }
|
|
}
|
|
],
|
|
"get": {
|
|
"operationId": "PullPayments_GetPullPayments",
|
|
"summary": "Get store's pull payments",
|
|
"parameters": [
|
|
{
|
|
"name": "includeArchived",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "Whether this should list archived pull payments",
|
|
"schema": {
|
|
"type": "boolean",
|
|
"default": false
|
|
}
|
|
}
|
|
],
|
|
"description": "Get the pull payments of a store",
|
|
"responses": {
|
|
"200": {
|
|
"description": "List of pull payments",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/PullPaymentDataList"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"tags": [ "Pull payments (Management)" ],
|
|
"security": [
|
|
{
|
|
"API Key": [
|
|
"btcpay.store.canmanagepullpayments"
|
|
],
|
|
"Basic": []
|
|
}
|
|
]
|
|
},
|
|
"post": {
|
|
"operationId": "PullPayments_CreatePullPayment",
|
|
"summary": "Create a new pull payment",
|
|
"description": "A pull payment allows its receiver to ask for payouts up to `amount` of `currency` every `period`.",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"name": {
|
|
"type": "string",
|
|
"description": "The name of the pull payment",
|
|
"nullable": true
|
|
},
|
|
"amount": {
|
|
"type": "string",
|
|
"format": "decimal",
|
|
"example": "0.1",
|
|
"description": "The amount in `currency` of this pull payment as a decimal string"
|
|
},
|
|
"currency": {
|
|
"type": "string",
|
|
"example": "BTC",
|
|
"description": "The currency of the amount. In this current release, this parameter must be set to a cryptoCode like (`BTC`)."
|
|
},
|
|
"period": {
|
|
"type": "integer",
|
|
"format": "decimal",
|
|
"example": 604800,
|
|
"nullable": true,
|
|
"description": "The length of each period in seconds."
|
|
},
|
|
"startsAt": {
|
|
"type": "integer",
|
|
"format": "unix timestamp in seconds",
|
|
"example": 1592312018,
|
|
"nullable": true,
|
|
"description": "When this pull payment is effective. Already started if null or unspecified."
|
|
},
|
|
"expiresAt": {
|
|
"type": "integer",
|
|
"format": "unix timestamp in seconds",
|
|
"example": 1593129600,
|
|
"nullable": true,
|
|
"description": "When this pull payment expires. Never expires if null or unspecified."
|
|
},
|
|
"paymentMethods": {
|
|
"type": "array",
|
|
"description": "The list of supported payment methods supported. In this current release, this must be set to an array with a single entry equals to `currency` (eg. `[ \"BTC\" ]`)",
|
|
"items": {
|
|
"type": "string",
|
|
"example": "BTC"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "The create pull payment",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/PullPaymentData"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Unable to validate the request",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ValidationProblemDetails"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"tags": [ "Pull payments (Management)" ],
|
|
"security": [
|
|
{
|
|
"API Key": [
|
|
"btcpay.store.canmanagepullpayments"
|
|
],
|
|
"Basic": []
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/pull-payments/{pullPaymentId}": {
|
|
"parameters": [
|
|
{
|
|
"name": "pullPaymentId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The ID of the pull payment",
|
|
"schema": { "type": "string" }
|
|
}
|
|
],
|
|
"get": {
|
|
"summary": "Get Pull Payment",
|
|
"operationId": "PullPayments_GetPullPayment",
|
|
"description": "Get a pull payment",
|
|
"responses": {
|
|
"200": {
|
|
"description": "Information about the pull payment",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/PullPaymentData"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "Pull payment not found"
|
|
}
|
|
},
|
|
"tags": [ "Pull payments (Public)" ],
|
|
"security": []
|
|
}
|
|
},
|
|
"/api/v1/stores/{storeId}/pull-payments/{pullPaymentId}": {
|
|
"parameters": [
|
|
{
|
|
"name": "storeId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The ID of the store",
|
|
"schema": { "type": "string" }
|
|
},
|
|
{
|
|
"name": "pullPaymentId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The ID of the pull payment",
|
|
"schema": { "type": "string" }
|
|
}
|
|
],
|
|
"delete": {
|
|
"operationId": "PullPayments_ArchivePullPayment",
|
|
"summary": "Archive a pull payment",
|
|
"description": "Archive this pull payment (Will cancel all payouts awaiting for payment)",
|
|
"responses": {
|
|
"200": {
|
|
"description": "The pull payment has been archived"
|
|
},
|
|
"404": {
|
|
"description": "The pull payment has not been found, or does not belong to this store"
|
|
}
|
|
},
|
|
"tags": [ "Pull payments (Management)" ],
|
|
"security": [
|
|
{
|
|
"API Key": [
|
|
"btcpay.store.canmanagepullpayments"
|
|
],
|
|
"Basic": []
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/pull-payments/{pullPaymentId}/payouts": {
|
|
"parameters": [
|
|
{
|
|
"name": "pullPaymentId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The ID of the pull payment",
|
|
"schema": { "type": "string" }
|
|
}
|
|
],
|
|
"get": {
|
|
"summary": "Get Payouts",
|
|
"operationId": "PullPayments_GetPayouts",
|
|
"description": "Get payouts",
|
|
"parameters": [
|
|
{
|
|
"name": "includeCancelled",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "Whether this should list cancelled payouts",
|
|
"schema": {
|
|
"type": "boolean",
|
|
"default": false
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "The payouts of the pull payment",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/PayoutDataList"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "Pull payment not found"
|
|
}
|
|
},
|
|
"tags": [ "Pull payments (Public)" ],
|
|
"security": []
|
|
},
|
|
"post": {
|
|
"summary": "Create Payout",
|
|
"description": "Create a new payout",
|
|
"operationId": "PullPayments_CreatePayout",
|
|
"requestBody": {
|
|
"x-name": "request",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/CreatePayoutRequest"
|
|
}
|
|
}
|
|
},
|
|
"required": true,
|
|
"x-position": 1
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "A new payout has been created",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/PayoutData"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "Pull payment not found"
|
|
},
|
|
"422": {
|
|
"description": "Unable to validate the request",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ValidationProblemDetails"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Wellknown error codes are: `duplicate-destination`, `expired`, `not-started`, `archived`, `overdraft`, `amount-too-low`, `payment-method-not-supported`",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ProblemDetails"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"tags": [ "Pull payments (Public)" ],
|
|
"security": []
|
|
}
|
|
},
|
|
"/api/v1/stores/{storeId}/payouts/{payoutId}": {
|
|
"parameters": [
|
|
{
|
|
"name": "storeId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The ID of the store",
|
|
"schema": { "type": "string" }
|
|
},
|
|
{
|
|
"name": "payoutId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The ID of the payout",
|
|
"schema": { "type": "string" }
|
|
}
|
|
],
|
|
"post": {
|
|
|
|
"summary": "Approve Payout",
|
|
"operationId": "PullPayments_ApprovePayout",
|
|
"description": "Approve a payout",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"revision": {
|
|
"type": "integer",
|
|
"description": "The revision number of the payout being modified"
|
|
},
|
|
"rateRule": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"example": "kraken(BTC_USD)",
|
|
"description": "The rate rule to calculate the rate of the payout. This can also be a fixed decimal. (if null or unspecified, will use the same rate setting as the store's settings)"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "The payout has been approved, transitioning to `AwaitingPayment` state.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/PayoutData"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Unable to validate the request",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ValidationProblemDetails"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Wellknown error codes are: `rate-unavailable`, `invalid-state`, `amount-too-low`, `old-revision`",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ProblemDetails"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "The payout is not found"
|
|
}
|
|
},
|
|
"tags": [ "Pull payments (Management)" ],
|
|
"security": [
|
|
{
|
|
"API Key": [
|
|
"btcpay.store.canmanagepullpayments"
|
|
],
|
|
"Basic": []
|
|
}
|
|
]
|
|
},
|
|
"delete": {
|
|
"summary": "Cancel Payout",
|
|
"description": "Cancel the payout",
|
|
"operationId": "PullPayments_CancelPayout",
|
|
"responses": {
|
|
"200": {
|
|
"description": "The payout has been cancelled"
|
|
},
|
|
"404": {
|
|
"description": "The payout is not found"
|
|
}
|
|
},
|
|
"tags": [ "Pull payments (Management)" ],
|
|
"security": [
|
|
{
|
|
"API Key": [
|
|
"btcpay.store.canmanagepullpayments"
|
|
],
|
|
"Basic": []
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/stores/{storeId}/payouts/{payoutId}/mark-paid": {
|
|
"parameters": [
|
|
{
|
|
"name": "storeId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The ID of the store",
|
|
"schema": { "type": "string" }
|
|
},
|
|
{
|
|
"name": "payoutId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The ID of the payout",
|
|
"schema": { "type": "string" }
|
|
}
|
|
],
|
|
"post": {
|
|
|
|
"summary": "Mark Payout as Paid",
|
|
"operationId": "PullPayments_MarkPayoutPaid",
|
|
"description": "Mark a payout as paid",
|
|
"responses": {
|
|
"200": {
|
|
"description": "The payout has been marked paid, transitioning to `Completed` state."
|
|
},
|
|
"422": {
|
|
"description": "Unable to validate the request",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ValidationProblemDetails"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Wellknown error codes are: `invalid-state`",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ProblemDetails"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "The payout is not found"
|
|
}
|
|
},
|
|
"tags": [ "Pull payments (Management)" ],
|
|
"security": [
|
|
{
|
|
"API Key": [
|
|
"btcpay.store.canmanagepullpayments"
|
|
],
|
|
"Basic": []
|
|
}
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"components": {
|
|
"schemas": {
|
|
"PullPaymentDataList": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/PullPaymentData"
|
|
}
|
|
},
|
|
"PayoutDataList": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/PayoutData"
|
|
}
|
|
},
|
|
"CreatePayoutRequest": {
|
|
"type": "object",
|
|
"properties":{
|
|
"destination": {
|
|
"type": "string",
|
|
"example": "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2",
|
|
"description": "The destination of the payout (can be an address or a BIP21 url)"
|
|
},
|
|
"amount": {
|
|
"type": "string",
|
|
"format": "decimal",
|
|
"example": "10399.18",
|
|
"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"
|
|
}
|
|
}
|
|
},
|
|
"PayoutData": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "The id of the payout"
|
|
},
|
|
"revision": {
|
|
"type": "integer",
|
|
"description": "The revision number of the payout. This revision number is incremented when the payout amount or destination is modified before the approval."
|
|
},
|
|
"pullPaymentId": {
|
|
"type": "string",
|
|
"description": "The id of the pull payment this payout belongs to"
|
|
},
|
|
"date": {
|
|
"type": "string",
|
|
"description": "The creation date of the payout as a unix timestamp"
|
|
},
|
|
"destination": {
|
|
"type": "string",
|
|
"example": "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2",
|
|
"description": "The destination of the payout (can be an address or a BIP21 url)"
|
|
},
|
|
"amount": {
|
|
"type": "string",
|
|
"format": "decimal",
|
|
"example": "10399.18",
|
|
"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"
|
|
},
|
|
"paymentMethodAmount": {
|
|
"type": "string",
|
|
"format": "decimal",
|
|
"nullable": true,
|
|
"example": "1.12300000",
|
|
"description": "The amount of the payout in the currency of the payment method (eg. BTC). This is only available from the `AwaitingPayment` state."
|
|
},
|
|
"state": {
|
|
"type": "string",
|
|
"example": "AwaitingPayment",
|
|
"description": "The state of the payout (`AwaitingApproval`, `AwaitingPayment`, `InProgress`, `Completed`, `Cancelled`)",
|
|
"x-enumNames": [
|
|
"AwaitingApproval",
|
|
"AwaitingPayment",
|
|
"InProgress",
|
|
"Completed",
|
|
"Cancelled"
|
|
],
|
|
"enum": [
|
|
"AwaitingApproval",
|
|
"AwaitingPayment",
|
|
"InProgress",
|
|
"Completed",
|
|
"Cancelled"
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"PullPaymentData": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Id of the pull payment"
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Payment method of of the pull payment"
|
|
},
|
|
"currency": {
|
|
"type": "string",
|
|
"example": "BTC",
|
|
"description": "The currency of the pull payment's amount"
|
|
},
|
|
"amount": {
|
|
"type": "string",
|
|
"format": "decimal",
|
|
"example": "1.12000000",
|
|
"description": "The amount in the currency of this pull payment as a decimal string"
|
|
},
|
|
"period": {
|
|
"type": "integer",
|
|
"example": 604800,
|
|
"nullable": true,
|
|
"description": "The length of each period in seconds"
|
|
},
|
|
"archived": {
|
|
"type": "boolean",
|
|
"description": "Whether this pull payment is archived"
|
|
},
|
|
"viewLink": {
|
|
"type": "string",
|
|
"description": "The link to a page to claim payouts to this pull payment"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|