commit 053a2f78557287762799970a9ebff1f9df906e34
parent 2af5ce7ab85618c1cebb43f62d3251ecd3a41a60
Author: Joel Häberli <haebu@rubigen.ch>
Date: Wed, 3 Apr 2024 19:15:58 +0200
docs: add c2ec api extensions
Diffstat:
1 file changed, 79 insertions(+), 2 deletions(-)
diff --git a/core/api-bank-integration.rst b/core/api-bank-integration.rst
@@ -152,6 +152,28 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr
transfer_done: boolean;
}
+ .. ts:def:: IndirectWithdrawalOperationStatus {
+
+ // Since vC2EC
+ interface IndirectWithdrawalOperationStatus {
+
+ // the current status of the withdrawal
+ status: "pending" | "selected" | "aborted" | "confirmed";
+
+ // the withdrawable amount
+ amount: Amount;
+
+ // a refund capable payto-uri
+ sender_wire: string;
+
+ // the wire type used for the transaction
+ wire_types: string[];
+
+ // the reserve public key tied to the withdrawal
+ reserve_public_key: EddsaPublicKey;
+ }
+ }
+
.. http:post:: /withdrawal-operation/$WITHDRAWAL_ID
**Request:**
@@ -166,11 +188,29 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr
selected_exchange: string;
}
+ .. ts:def:: IndirectWithdrawalOperationPostRequest {
+
+ // Since vC2EC
+ interface ProviderWithdrawalOperationPostRequest {
+ // Reserve public key.
+ reserve_pub: string;
+
+ // Id of the terminal of a provider. The terminal
+ // is the specific device leveraged for the withdrawal
+ // owned by a specific provider.
+ terminal_id: number;
+ }
+ }
+
**Response:**
:http:statuscode:`200 OK`:
The bank has accepted the withdrawal operation parameters chosen by the wallet.
The response is a `BankWithdrawalOperationPostResponse`.
+ :http:statuscode:`204 No Content`:
+ The bank has accepted the withdrawal operation parameters chosen by the wallet.
+ This response will be returned in case of a `IndirectWithdrawalOperationPostRequest`.
+ Since vC2EC
:http:statuscode:`404 Not found`:
The bank does not know about a withdrawal operation with the specified ``WITHDRAWAL_ID``.
:http:statuscode:`409 Conflict`:
@@ -198,13 +238,50 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr
// Only applicable when ``status`` is ``selected`` or ``pending``.
// It may contain withdrawal operation id
confirm_transfer_url?: string;
-
- // Deprecated field use ``status`` instead
// The transfer has been confirmed and registered by the bank.
// Does not guarantee that the funds have arrived at the exchange already.
transfer_done: boolean;
}
+.. http:post:: /withdrawal-operation/$WITHDRAWAL_ID/payment
+
+ Since protocol vC2EC
+
+ Allows a provider to notify the Bank about the payment. This will trigger a payment
+ attestation at the provider, which eventually confirms the payment and allows the
+ withdrawal. The API is idempotent, meaning sending a payment
+ notification for the same `WITHDRAWAL_ID` return successfuly but not change anything.
+
+ Attention: A bank shall **never** just accept the payment directly but instead attest
+ the payment using provider specific attestation logic!
+
+ **Request:**
+
+ .. ts:def:: PaymentNotification {
+
+ // The provider specific transaction identifier.
+ // This identifier is used by the bank to attest the
+ // payment at the providers backend.
+ provider_transaction_id: string;
+
+ // The amount to withdraw. Fees are to be sent in the
+ // separate field 'fees' and not included in the amount.
+ amount Amount;
+
+ // The fees, the customer payed at the providers facility.
+ fees: Amount;
+ }
+
+ **Response**
+
+ :http:statuscode:`204 No content`:
+ The payment notification was processed successfully.
+ :http:statuscode:`404 Not found`:
+ The withdrawal operation was not found.
+ :http:statuscode:`409 Conflict`:
+ The withdrawal operation has been aborted previously and can't be aborted
+
+
.. http:post:: /withdrawal-operation/$WITHDRAWAL_ID/abort
Aborts ``WITHDRAWAL_ID`` operation. Has no effect on an already aborted
