summaryrefslogtreecommitdiff
path: root/core/api-merchant.rst
diff options
context:
space:
mode:
Diffstat (limited to 'core/api-merchant.rst')
-rw-r--r--core/api-merchant.rst226
1 files changed, 113 insertions, 113 deletions
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 53b6424..8def672 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -48,7 +48,7 @@ such as the implemented version of the protocol and the currency used.
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The exchange accepted all of the coins. The body is a `VersionResponse`.
.. ts:def:: VersionResponse
@@ -122,12 +122,12 @@ claim orders (say in a case where stocks are limited).
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The client has successfully claimed the order.
The response contains the :ref:`contract terms <contract-terms>`.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The backend is unaware of the instance or order.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
The someone else claimed the same order ID with different nonce before.
.. ts:def:: ClaimResponse
@@ -157,12 +157,12 @@ Making the payment
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The exchange accepted all of the coins.
The body is a `payment response <PaymentResponse>`.
The ``frontend`` should now fulfill the contract.
Note that it is possible that refunds have been granted.
- :status 400 Bad request:
+ :http:statuscode:`400 Bad request`:
Either the client request is malformed or some specific processing error
happened that may be the fault of the client as detailed in the JSON body
of the response.
@@ -170,25 +170,25 @@ Making the payment
There used to be a sufficient payment, but due to refunds the amount effectively
paid is no longer sufficient. (If the amount is generally insufficient, we
return "406 Not Acceptable", only if this is because of refunds we return 402.)
- :status 403 Forbidden:
+ :http:statuscode:`403 Forbidden`:
One of the coin signatures was not valid.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The merchant backend could not find the order or the instance and thus cannot process the payment.
- :status 406 Not Acceptable:
+ :http:statuscode:`406 Not acceptable`:
The payment is insufficient (sum is below the required total amount).
- :status 408 Request Timeout:
+ :http:statuscode:`408 Request timeout`:
The backend took too long to process the request. Likely the merchant's connection
to the exchange timed out. Try again.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
The exchange rejected the payment because a coin was already spent before.
The response will include the ``coin_pub`` for which the payment failed,
in addition to the response from the exchange to the ``/deposit`` request.
- :status 410 Gone:
+ :http:statuscode:`410 Gone`:
The offer has expired and is no longer available.
- :status 412 Precondition Failed:
+ :http:statuscode:`412 Precondition failed`:
The given exchange is not acceptable for this merchant, as it is not in the
list of accepted exchanges and not audited by an approved auditor.
- :status 424 Failed Dependency:
+ :http:statuscode:`424 Failed dependency`:
The merchant's interaction with the exchange failed in some way.
The client might want to try later again.
This includes failures like the denomination key of a coin not being
@@ -277,22 +277,22 @@ Querying payment status
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The response is a `StatusPaidResponse`.
- :status 202 Accepted:
+ :http:statuscode:`202 Accepted`:
The response is a `StatusGotoResponse`. Only returned if the content type requested was not HTML.
- :status 302 Found:
+ :http:statuscode:`302 Found`:
The client should go to the indicated location. Only returned if the content type requested was HTML.
- :status 402 PaymentRequired:
+ :http:statuscode:`402 Payment required`:
The response is a `StatusUnpaidResponse`.
- :status 403 Forbidden:
+ :http:statuscode:`403 Forbidden`:
The ``h_contract`` (or the ``token`` for unclaimed orders) does not match the order
and we have no fulfillment URL in the contract.
- :status 410 Gone:
+ :http:statuscode:`410 Gone`:
The response is a `StatusGoneResponse`.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The merchant backend is unaware of the order.
- :status 406 Not Acceptable:
+ :http:statuscode:`406 Not acceptable`:
The merchant backend could not load the template required to generate a reply in the desired format. (Likely HTML templates were not properly installed.)
.. ts:def:: StatusPaidResponse
@@ -374,20 +374,20 @@ again.
**Response:**
- :status 204 No content:
+ :http:statuscode:`204 No content`:
The merchant accepted the signature.
The ``frontend`` should now fulfill the contract.
Note that it is possible that refunds have been granted.
- :status 400 Bad request:
+ :http:statuscode:`400 Bad request`:
Either the client request is malformed or some specific processing error
happened that may be the fault of the client as detailed in the JSON body
of the response.
- :status 403 Forbidden:
+ :http:statuscode:`403 Forbidden`:
The signature was not valid.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The merchant backend could not find the order or the instance
and thus cannot process the request.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
The provided contract hash does not match this order.
.. ts:def:: PaidRequest
@@ -436,29 +436,29 @@ are for incomplete payments for an order and never for established contracts.
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The merchant accepted the request, and passed it on to the exchange. The body is a
a `merchant refund response <MerchantRefundResponse>`. Note that the exchange
MAY still have encountered errors in processing. Those will then be part of
the body. Wallets MUST carefully consider errors for each of the coins as
returned by the exchange.
- :status 400 Bad request:
+ :http:statuscode:`400 Bad request`:
Either the client request is malformed or some specific processing error
happened that may be the fault of the client as detailed in the JSON body
of the response.
- :status 403 Forbidden:
+ :http:statuscode:`403 Forbidden`:
The ``h_contract`` does not match the $ORDER_ID.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The merchant backend could not find the order or the instance
and thus cannot process the abort request.
- :status 408 Request Timeout:
+ :http:statuscode:`408 Request timeout`:
The merchant backend took too long getting a response from the exchange.
The wallet SHOULD retry soon.
- :status 412 Precondition Failed:
+ :http:statuscode:`412 Precondition failed`:
Aborting the payment is not allowed, as the original payment did succeed.
It is possible that a different wallet succeeded with the payment. This
wallet should thus try to refresh all of the coins involved in the payment.
- :status 424 Failed Dependency:
+ :http:statuscode:`424 Failed dependency`:
The merchant's interaction with the exchange failed in some way.
The error from the exchange is included.
@@ -573,13 +573,13 @@ the contract. Refunds must be approved by the merchant's business logic.
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The response is a `WalletRefundResponse`.
- :status 204 No content:
+ :http:statuscode:`204 No content`:
There are no refunds for the order.
- :status 403 Forbidden:
+ :http:statuscode:`403 Forbidden`:
The ``h_contract`` does not match the order.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The merchant backend is unaware of the order.
.. ts:def:: WalletRefundRequest
@@ -690,13 +690,13 @@ a website.
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
A tip is being returned. The backend responds with a `TipInformation`.
- :status 404 Not Found:
+ :http:statuscode:`404 Not found`:
The tip identifier is unknown.
- :status 406 Not Acceptable:
+ :http:statuscode:`406 Not acceptable`:
The merchant backend could not load the template required to generate a reply in the desired format. (Likely HTML templates were not properly installed.)
- :status 410 Gone:
+ :http:statuscode:`410 Gone`:
A tip has been fully claimed. The JSON reply still contains the `TipInformation`.
.. ts:def:: TipInformation
@@ -726,15 +726,15 @@ a website.
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
A tip is being returned. The backend responds with a `TipResponse`
- :status 401 Unauthorized:
+ :http:statuscode:`401 Unauthorized`:
The tip amount requested exceeds the tip.
- :status 404 Not Found:
+ :http:statuscode:`404 Not found`:
The tip identifier is unknown.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
Some of the denomination key hashes of the request do not match those currently available from the exchange (hence there is a conflict between what the wallet requests and what the merchant believes the exchange can provide).
- :status 410 Gone:
+ :http:statuscode:`410 Gone`:
The tip has expired.
.. ts:def:: TipPickupRequest
@@ -796,9 +796,9 @@ Setting up instances
**Response:**
- :status 204 No content:
+ :http:statuscode:`204 No content`:
The backend has successfully created the instance.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
This instance already exists, but with other configuration options.
Use "PATCH" to update an instance configuration.
@@ -863,9 +863,9 @@ Setting up instances
**Response:**
- :status 204 No content:
+ :http:statuscode:`204 No content`:
The backend has successfully created the instance.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
This instance is unknown and thus cannot be reconfigured.
.. ts:def:: InstanceReconfigurationMessage
@@ -921,7 +921,7 @@ Inspecting instances
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The backend has successfully returned the list of instances stored. Returns
a `InstancesResponse`.
@@ -962,7 +962,7 @@ Inspecting instances
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The backend has successfully returned the list of instances stored. Returns
a `QueryInstancesResponse`.
@@ -1047,11 +1047,11 @@ Deleting instances
**Response**
- :status 204 No content:
+ :http:statuscode:`204 No content`:
The backend has successfully removed the instance. The body is empty.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The instance is unknown to the backend.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
The instance cannot be deleted because it has pending offers, or
the instance cannot be purged because it has successfully processed
payments that have not passed the TAX_RECORD_EXPIRATION time.
@@ -1084,9 +1084,9 @@ Adding products to the inventory
**Response:**
- :status 204 No content:
+ :http:statuscode:`204 No content`:
The backend has successfully expanded the inventory.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
The backend already knows a product with this product ID, but with different details.
@@ -1154,7 +1154,7 @@ Adding products to the inventory
**Response:**
- :status 204 No content:
+ :http:statuscode:`204 No content`:
The backend has successfully expanded the inventory.
@@ -1210,7 +1210,7 @@ Inspecting inventory
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The backend has successfully returned the inventory. Returns
a `InventorySummaryResponse`.
@@ -1238,7 +1238,7 @@ Inspecting inventory
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The backend has successfully returned the inventory. Returns
a `ProductDetail`.
@@ -1316,11 +1316,11 @@ Reserving inventory
**Response:**
- :status 204 No content:
+ :http:statuscode:`204 No content`:
The backend has successfully locked (or unlocked) the requested ``quantity``.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The backend has does not know this product.
- :status 410 Gone:
+ :http:statuscode:`410 Gone`:
The backend does not have enough of product in stock.
.. ts:def:: LockRequest
@@ -1348,11 +1348,11 @@ Removing products from inventory
**Response:**
- :status 204 No content:
+ :http:statuscode:`204 No content`:
The backend has successfully deleted the product.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The backend does not know the instance or the product.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
The backend refuses to delete the product because it is locked.
@@ -1392,17 +1392,17 @@ Creating orders
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The backend has successfully created the proposal. The response is a
:ts:type:`PostOrderResponse`.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The order given used products from the inventory, but those were not found
in the inventory. Or the merchant instance is unknown (including possibly the instance being not configured for new orders). Details in the
error code. NOTE: no good way to find out which product is not in the
inventory, we MAY want to specify that in the reply.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
A different proposal already exists under the specified order ID.
- :status 410 Gone:
+ :http:statuscode:`410 Gone`:
The order given used products from the inventory that are out of stock.
The response is a :ts:type:`OutOfStockResponse`.
@@ -1550,7 +1550,7 @@ Inspecting orders
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The response is an `OrderHistory`.
.. ts:def:: OrderHistory
@@ -1608,11 +1608,11 @@ Inspecting orders
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
Returns a `MerchantOrderStatusResponse`, whose format can differ based on the status of the payment.
- :status 404 Not Found:
+ :http:statuscode:`404 Not found`:
The order or instance is unknown to the backend.
- :status 424 Failed dependency:
+ :http:statuscode:`424 Failed dependency`:
We failed to obtain a response from the exchange (about the wire transfer status).
.. ts:def:: MerchantOrderStatusResponse
@@ -1797,15 +1797,15 @@ the contract!) to minimize risks from information leakage.
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The merchant deleted the specified fields from the contract of
order $ORDER_ID.
- :status 400 Bad request:
+ :http:statuscode:`400 Bad request`:
The request is malformed or one of the paths is invalid.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The merchant backend could not find the order or the instance
and thus cannot process the abort request.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
The request includes a field that was not marked as forgettable, so
the merchant cannot delete that field.
@@ -1827,11 +1827,11 @@ the contract!) to minimize risks from information leakage.
**Response:**
- :status 204 No content:
+ :http:statuscode:`204 No content`:
The backend has successfully deleted the order.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The backend does not know the instance or the order.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
The backend refuses to delete the order.
@@ -1852,16 +1852,16 @@ Giving Refunds
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The refund amount has been increased, the backend responds with a `MerchantRefundResponse`
- :status 403 Forbidden:
+ :http:statuscode:`403 Forbidden`:
For the given order, the refund delay was zero and thus refunds are categorically not allowed.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The order is unknown to the merchant
- :status 410 Gone:
+ :http:statuscode:`410 Gone`:
It is too late for aborting, the exchange may have already wired the funds
to the merchant.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
The refund amount exceeds the amount originally paid
.. ts:def:: RefundRequest
@@ -1915,10 +1915,10 @@ Informing the backend about incoming wire transfers
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The wire transfer is known to the exchange, details about it follow in the body.
The body of the response is a `MerchantTrackTransferResponse`.
- :status 202 Accepted:
+ :http:statuscode:`202 Accepted`:
The exchange provided conflicting information about the transfer. Namely,
there is at least one deposit among the deposits aggregated by ``wtid``
that accounts for a coin whose
@@ -1932,12 +1932,12 @@ Informing the backend about incoming wire transfers
the bad behavior to the auditor -- and then hope for the auditor to
resolve it. So in that respect, 202 is the right status code as more
work remains to be done for a final resolution.)
- :status 404 Not Found:
+ :http:statuscode:`404 Not found`:
The instance is unknown to the exchange.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
The wire transfer identifier is already known to us, but for a different amount,
wire method or exchange.
- :status 424 Failed Dependency:
+ :http:statuscode:`424 Failed dependency`:
The exchange returned an error when we asked it about the "GET /transfer" status
for this wire transfer. Details of the exchange error are returned.
@@ -2153,7 +2153,7 @@ Querying known wire transfers
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The body of the response is a `TransferList`.
.. ts:def:: TransferList
@@ -2241,14 +2241,14 @@ funds to the exchange.
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The backend is waiting for the reserve to be established. The merchant
must now perform the wire transfer indicated in the `ReserveCreateConfirmation`.
- :status 408 Request Timeout:
+ :http:statuscode:`408 Request timeout`:
The exchange did not respond on time.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
The exchange does not support the requested wire method.
- :status 424 Failed Dependency:
+ :http:statuscode:`424 Failed dependency`:
We could not obtain /wire details from the specified exchange base URL.
.. ts:def:: ReserveCreateRequest
@@ -2286,7 +2286,7 @@ funds to the exchange.
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
Returns a list of known tipping reserves.
The body is a `TippingReserveStatus`.
@@ -2340,11 +2340,11 @@ Query funds remaining
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
Returns the `ReserveDetail`.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The tipping reserve is not known.
- :status 424 Failed Dependency:
+ :http:statuscode:`424 Failed dependency`:
We are having trouble with the request because of a problem with the exchange.
Likely returned with an "exchange_code" in addition to a "code" and
an "exchange_http_status" in addition to our own HTTP status. Also usually
@@ -2411,11 +2411,11 @@ Authorizing tips
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
A tip has been created. The backend responds with a `TipCreateConfirmation`
- :status 404 Not Found:
+ :http:statuscode:`404 Not found`:
The instance or the reserve is unknown to the backend.
- :status 412 Precondition Failed:
+ :http:statuscode:`412 Precondition failed`:
The tip amount requested exceeds the available reserve balance for tipping.
.. ts:def:: TipCreateRequest
@@ -2463,11 +2463,11 @@ Authorizing tips
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
A tip has been created. The backend responds with a `TipCreateConfirmation`
- :status 404 Not Found:
+ :http:statuscode:`404 Not found`:
The instance is unknown to the backend.
- :status 412 Precondition Failed:
+ :http:statuscode:`412 Precondition failed`:
The tip amount requested exceeds the available reserve balance for tipping
in all of the reserves of the instance.
@@ -2489,11 +2489,11 @@ Deleting reserves
**Response:**
- :status 204 No content:
+ :http:statuscode:`204 No content`:
The backend has successfully deleted the reserve.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The backend does not know the instance or the reserve.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
The backend refuses to delete the reserve (committed tips awaiting pickup).
@@ -2510,9 +2510,9 @@ Checking tip status
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The tip is known. The backend responds with a `TipDetails` message
- :status 404 Not Found:
+ :http:statuscode:`404 Not found`:
The tip is unknown to the backend.
.. ts:def:: TipDetails
@@ -2566,7 +2566,7 @@ Checking tip status
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The backend has successfully found the list of tips. The backend responds
with a `TipsResponse`.