diff options
| -rw-r--r-- | core/api-merchant.rst | 181 | ||||
| -rw-r--r-- | taler-wallet.rst | 81 |
2 files changed, 179 insertions, 83 deletions
diff --git a/core/api-merchant.rst b/core/api-merchant.rst index 8849db2b..3c0ea712 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -1438,12 +1438,6 @@ Payment processing // Amount that was refunded in total. refund_amount: Amount; - // Successful refunds for this payment, empty array for none. - refunds: MerchantCoinRefundStatus[]; - - // Public key of the merchant. - merchant_pub: EddsaPublicKey; - } .. ts:def:: StatusGotoResponse @@ -1477,6 +1471,114 @@ Payment processing fulfillment_url: string; } + +.. http:delete:: /private/orders/$ORDER_ID + + Delete information about an order. Fails if the order was paid in the + last 10 years (or whatever TAX_RECORD_EXPIRATION is set to) or was + claimed but is unpaid and thus still a valid offer. + + **Response:** + + :status 204 No content: + The backend has successfully deleted the order. + :status 404 Not found: + The backend does not know the instance or the order. + :status 409 Conflict: + The backend refuses to delete the order. + + +.. _merchant_refund: + +-------------- +Giving Refunds +-------------- + +.. http:post:: /private/orders/$ORDER_ID/refund + + Increase the refund amount associated with a given order. The user should be + redirected to the ``taler_refund_uri`` to trigger refund processing in the wallet. + + **Request:** + + The request body is a `RefundRequest` object. + + **Response:** + + :status 200 OK: + The refund amount has been increased, the backend responds with a `MerchantRefundResponse` + :status 404 Not found: + The order is unknown to the merchant + :status 410 Gone: + It is too late for aborting, the exchange may have already wired the funds + to the merchant. + :status 409 Conflict: + The refund amount exceeds the amount originally paid + + .. ts:def:: RefundRequest + + interface RefundRequest { + // Amount to be refunded + refund: Amount; + + // Human-readable refund justification + reason: string; + } + + .. ts:def:: MerchantRefundResponse + + interface MerchantRefundResponse { + + // URL (handled by the backend) that the wallet should access to + // trigger refund processing. + // taler://refund/[$H_CONTRACT/$AMOUNT????] + taler_refund_uri: string; + } + + +.. http:post:: /orders/$ORDER_ID/refund + + Obtain refunds for an order. After talking to the exchange, the refunds will + no longer be pending if processed successfully. + + **Request:** + + The request body is a `WalletRefundRequest` object. + + **Response:** + + :status 200 OK: + The response is a `WalletRefundResponse`. + :status 204 No content: + There are no refunds for the order. + :status 403 Forbidden: + The ``h_contract`` does not match the order. + :status 404 Not found: + The merchant backend is unaware of the order. + + .. ts:def:: WalletRefundRequest + + interface WalletRefundRequest { + // hash of the order's contract terms (this is used to authenticate the + // wallet/customer). + h_contract: HashCode; + + } + + .. ts:def:: WalletRefundResponse + + interface WalletRefundResponse { + // Amount that was refunded in total. + refund_amount: Amount; + + // Successful refunds for this payment, empty array for none. + refunds: MerchantCoinRefundStatus[]; + + // Public key of the merchant. + merchant_pub: EddsaPublicKey; + + } + .. ts:def:: MerchantCoinRefundStatus type MerchantCoinRefundStatus = @@ -1516,7 +1618,7 @@ Payment processing // Additional details needed to verify the refund confirmation signature // (``h_contract_terms`` and ``merchant_pub``) are already known // to the wallet and thus not included. - interface RefundConfirmation { + interface MerchantCoinRefundSuccessStatus { // Used as tag for the sum type MerchantCoinRefundStatus sum type. type: "success"; @@ -1547,71 +1649,6 @@ Payment processing } -.. http:delete:: /private/orders/$ORDER_ID - - Delete information about an order. Fails if the order was paid in the - last 10 years (or whatever TAX_RECORD_EXPIRATION is set to) or was - claimed but is unpaid and thus still a valid offer. - - **Response:** - - :status 204 No content: - The backend has successfully deleted the order. - :status 404 Not found: - The backend does not know the instance or the order. - :status 409 Conflict: - The backend refuses to delete the order. - - -.. _merchant_refund: - --------------- -Giving Refunds --------------- - -.. http:post:: /private/orders/$ORDER_ID/refund - - Increase the refund amount associated with a given order. The user should be - redirected to the ``taler_refund_uri`` to trigger refund processing in the wallet. - - **Request:** - - The request body is a `RefundRequest` object. - - **Response:** - - :status 200 OK: - The refund amount has been increased, the backend responds with a `MerchantRefundResponse` - :status 404 Not found: - The order is unknown to the merchant - :status 410 Gone: - It is too late for aborting, the exchange may have already wired the funds - to the merchant. - :status 409 Conflict: - The refund amount exceeds the amount originally paid - - .. ts:def:: RefundRequest - - interface RefundRequest { - // Amount to be refunded - refund: Amount; - - // Human-readable refund justification - reason: string; - } - - .. ts:def:: MerchantRefundResponse - - interface MerchantRefundResponse { - - // URL (handled by the backend) that the wallet should access to - // trigger refund processing. - // taler://refund/[$H_CONTRACT/$AMOUNT????] - taler_refund_uri: string; - } - - - ------------------------ Tracking Wire Transfers ------------------------ diff --git a/taler-wallet.rst b/taler-wallet.rst index 7d9bbd93..6fa493f8 100644 --- a/taler-wallet.rst +++ b/taler-wallet.rst @@ -607,17 +607,6 @@ A typical API sequence for *manual* withdrawals can for example look like this: #. ``"acceptManualWithdrawal"`` after the user confirmed withdrawal with associated fees -Withdraw balance from test environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:Name: ``"withdrawTestkudos"`` -:Description: - Withdraw a balance from the test environment. -:Request: - The request parameters are ignored. -:Response: - On success, the response is an empty object. - Get Details For Bank-integrated Withdrawal ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -832,6 +821,76 @@ Confirm Payment | ConfirmPayResultDone; | ConfirmPayResultPending; +Testing API calls +----------------- + +The following API calls are useful for testing. + +Withdraw balance from the TESTKUDOS environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:Name: ``"withdrawTestkudos"`` +:Description: + Withdraw a balance from the ``TESTKUDOS`` environment. +:Request: + The request parameters are ignored. +:Response: + On success, the response is an empty object. + +Withdraw balance from a test environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:Name: ``"withdrawTestBalance"`` +:Description: + Withdraw a balance from a test environment. +:Request: + .. ts:def:: WithdrawTestBalanceRequest + + interface WithdrawTestBalanceRequest { + amount: string; + bankBaseUrl: string; + exchangeBaseUrl: string; + } +:Response: + On success, the response is an empty object. + +Run integration test +~~~~~~~~~~~~~~~~~~~~ + +:Name: ``"runIntegrationTest"`` +:Description: + Run a basic integration test that does a withdrawal, payment, + refund and again a payment. Useful to generate test data + in the integration tests of other components. +:Request: + .. ts:def:: IntegrationTestArgs + + interface IntegrationTestArgs { + exchangeBaseUrl: string; + bankBaseUrl: string; + merchantBaseUrl: string; + merchantApiKey: string; + amountToWithdraw: string; + amountToSpend: string; + } +:Response: + On success, the response is an empty object. + +Make a test payment +~~~~~~~~~~~~~~~~~~~ + +:Name: ``"testPay"`` +:Description: + Make a test payment with existing funds. +:Request: + .. ts:def:: TestPayArgs + + interface TestPayArgs { + merchantBaseUrl: string; + merchantApiKey: string; + amount: string; + summary: string; + } Global Errors ------------- |