taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

get-private-incoming-ID.rst (3705B)

      1 .. http:get:: [/instances/$INSTANCE]/private/incoming/$ID
      2 
      3   Obtain details about an expected incoming wire transfers the backend is
      4   anticipating.  ID must be the ``expected_transfer_serial_id``
      5   from `ExpectedTransferDetails`.
      6   Since protocol **v26**.
      7 
      8   **Required permission:** ``transfers-read``
      9 
     10   **Response:**
     11 
     12   :http:statuscode:`200 OK`:
     13     The body of the response is a `ExpectedTransferDetailResponse`.
     14   :http:statuscode:`400 Bad Request`:
     15     The transfer ID parameter is malformed.
     16     Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
     17   :http:statuscode:`404 Not found`:
     18     The expected wire transfer ``$ID`` or instance is unknown.
     19     Applicable error codes:
     20 
     21     * ``TALER_EC_MERCHANT_GENERIC_INSTANCE_UNKNOWN``
     22     * ``TALER_EC_MERCHANT_GENERIC_EXPECTED_TRANSFER_UNKNOWN``
     23   :http:statuscode:`500 Internal Server Error`:
     24     The server experienced an internal failure.
     25     Returned with ``TALER_EC_GENERIC_DB_FETCH_FAILED``.
     26 
     27   **Details:**
     28 
     29   .. ts:def:: ExpectedTransferDetailResponse
     30 
     31     interface ExpectedTransferDetailResponse {
     32 
     33       // List of orders that are settled by this wire
     34       // transfer according to the exchange.  Only
     35       // available if ``last_http_status`` is 200.
     36       reconciliation_details?: ExchangeTransferReconciliationDetails[];
     37 
     38       // Wire fee paid by the merchant. Only
     39       // available if ``last_http_status`` is 200.
     40       // Not present if the backend was unable to obtain the
     41       // wire fee for the ``execution_time`` from the exchange.
     42       // (If missing, this is thus indicative of a minor error.)
     43       wire_fee?: Amount;
     44 
     45       // How much should be wired to the merchant (minus fees).
     46       // Optional, missing if unknown. Happens if we are still waiting for
     47       // details from the exchange.
     48       // Since protocol **v27**.
     49       expected_credit_amount?: Amount;
     50 
     51       // Raw wire transfer identifier identifying the wire transfer (a base32-encoded value).
     52       // Since protocol **v27**.
     53       wtid: WireTransferIdentifierRawP;
     54 
     55       // Full payto://-URI of the bank account that should
     56       // receive the wire transfer.
     57       // Since protocol **v27**.
     58       payto_uri: string;
     59 
     60       // Base URL of the exchange that made the wire transfer.
     61       // Since protocol **v27**.
     62       exchange_url: string;
     63 
     64       // Expected time of the execution of the wire transfer
     65       // by the exchange, according to the exchange. Used
     66       // to compute the applicable wire fee.
     67       // Since protocol **v27**.
     68       expected_time: Timestamp;
     69 
     70       // Actual execution time of the wire transfer
     71       // as seen by us.
     72       // Optional, missing if not ``confirmed``.
     73       // Since protocol **v27**.
     74       execution_time?: Timestamp;
     75 
     76       // True if we checked the exchange's answer and are happy with
     77       // the reconciation data.
     78       // False if we have an answer and are unhappy, missing if we
     79       // do not (yet) have an answer from the exchange.
     80       // Does not imply that the wire transfer was settled.
     81       // Since protocol **v27**.
     82       confirmed: boolean;
     83 
     84     }
     85 
     86   .. ts:def:: ExchangeTransferReconciliationDetails
     87 
     88     interface ExchangeTransferReconciliationDetails {
     89 
     90       // ID of the order for which these are the
     91       // reconciliation details.
     92       order_id: string;
     93 
     94       // Remaining deposit total to be paid,
     95       // that is the total amount of the order
     96       // minus any refunds that were granted.
     97       // The actual amount to be wired is this
     98       // amount minus ``deposit_fee`` and (overall)
     99       // minus the ``wire_fee`` of the transfer.
    100       remaining_deposit: Amount;
    101 
    102       // Deposit fees paid to the exchange for this order.
    103       deposit_fee: Amount;
    104 
    105     }