taler-docs

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

post-private-accounts-H_WIRE-kycauth.rst (2574B)

      1 .. http:post:: [/instances/$INSTANCE]/private/accounts/$H_WIRE/kycauth
      2 
      3   Request from the backend to create wire transfer instructions for
      4   a KYC Auth transfer for a particular bank account and exchange.
      5 
      6   KYC Auth transfers may be required by an exchange when an account is
      7   activated for the first time. Furthermore, obtaining the correct
      8   wire transfer instructions may require getting details from the
      9   exchange and interacting with the banking system to produce a proper
     10   (short) wire transfer subject and a transferrable minimum amount.
     11   Thus, this endpoint should be used to obtain the wire transfer
     12   instructions for a KYC Auth wire transfer when onboarding a new
     13   bank account at an exchange that requires proof of control over the
     14   bank account via a wire transfer.
     15 
     16   Since protocol **v28**.
     17 
     18   **Required permission:** ``accounts-read``
     19 
     20   **Request:**
     21 
     22    The request must provide `exchange information <KycAuthExchangeSelectionRequest>`.
     23 
     24   **Response:**
     25 
     26   :http:statuscode:`200 Ok`:
     27     Wire transfer instructions are returned in the
     28     `response <KycAuthWireTransferInstructionResponse>`.
     29   :http:statuscode:`404 Not found`:
     30     The instance or account are unknown to the exchange.
     31   :http:statuscode:`413 Request entity too large`:
     32     The uploaded body is to long, it exceeds the size limit.
     33     Returned with an error code of
     34     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
     35 
     36   **Details:**
     37 
     38   .. ts:def:: KycAuthExchangeSelectionRequest
     39 
     40     interface KycAuthExchangeSelectionRequest {
     41 
     42       // Base URL of the exchange for which KYC Auth wire
     43       // transfer instructions are requested.
     44       exchange_url: string;
     45     }
     46 
     47   .. ts:def:: KycAuthWireTransferInstructionResponse
     48 
     49     interface KycAuthWireTransferInstructionResponse {
     50 
     51       // Array of possible wire transfers to do. There might
     52       // be more than one possibility, for example if the
     53       // exchange supports multiple bank accounts.
     54       wire_instructions: WireTransferInstructionDetail[];
     55 
     56     }
     57 
     58   .. ts:def:: WireTransferInstructionDetail
     59 
     60     interface WireTransferInstructionDetail {
     61 
     62       // Amount to wire (minimum amount, as per ``tiny_amount``
     63       // of the ``/keys`` of the exchange).
     64       amount: Amount;
     65 
     66       // Full payto:// URL of the (exchange) bank account to which the
     67       // money should be sent, excludes the wire subject and the amount.
     68       target_payto: string;
     69 
     70       // Subject to use. See also DD80!
     71       subject: TransferSubject;
     72 
     73       // Expiration date after which this subject might be reused
     74       expiration: Timestamp;
     75 
     76     }