taler-docs

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

post-reserves-RESERVE_PUB-attest.rst (2850B)

      1 .. http:post:: /reserves/$RESERVE_PUB/attest
      2 
      3   Request signed KYC information about the owner of a reserve.
      4   This can be used by a reserve owner to include a proof
      5   of their identity in invoices.
      6 
      7   **Request:**
      8 
      9   The request body must be a `ReserveAttestRequest` object.
     10 
     11   **Response:**
     12 
     13   :http:statuscode:`200 OK`:
     14     The exchange responds with a `ReserveAttestResponse` object.
     15   :http:statuscode:`400 Bad Request`:
     16     The request is malformed.
     17     This response comes with a standard `ErrorDetail` response.
     18     Possible error codes include
     19     ``TALER_EC_GENERIC_RESERVE_PUB_MALFORMED`` or
     20     ``TALER_EC_EXCHANGE_GENERIC_CLOCK_SKEW``.
     21   :http:statuscode:`403 Forbidden`:
     22     The *TALER_SIGNATURE_WALLET_KYC_DETAILS* signature is invalid.
     23     This response comes with a standard `ErrorDetail` response with
     24     a code of ``TALER_EC_EXCHANGE_RESERVES_ATTEST_BAD_SIGNATURE``.
     25   :http:statuscode:`404 Not found`:
     26     The reserve key does not belong to a reserve known to the exchange.
     27     This response comes with a standard `ErrorDetail` response with
     28     a code of ``TALER_EC_EXCHANGE_GENERIC_RESERVE_UNKNOWN``.
     29   :http:statuscode:`409 Conflict`:
     30     The exchange does not have the requested KYC information.
     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   :http:statuscode:`500 Internal Server Error`:
     36     The server experienced an internal error.
     37     This response comes with a standard `ErrorDetail` response.
     38     Possible error codes include
     39     ``TALER_EC_GENERIC_DB_FETCH_FAILED`` or
     40     ``TALER_EC_GENERIC_JSON_ALLOCATION_FAILURE``.
     41 
     42   **Details:**
     43 
     44   .. ts:def:: ReserveAttestRequest
     45 
     46     interface ReserveAttestRequest {
     47       // Signature of purpose
     48       // ``TALER_SIGNATURE_WALLET_ATTEST_DETAILS`` over
     49       // a `TALER_WalletReserveAttestRequestSignaturePS`.
     50       reserve_sig: EddsaSignature;
     51 
     52       // Client's time for the request.
     53       request_timestamp: Timestamp;
     54 
     55       // Array of KYC attributes requested.
     56       details: string[];
     57     }
     58 
     59   .. ts:def:: ReserveAttestResponse
     60 
     61     interface ReserveAttestResponse {
     62       // Signature of purpose
     63       // ``TALER_SIGNATURE_EXCHANGE_RESERVE_ATTEST_DETAILS`` over
     64       // a `TALER_ExchangeAttestPS`.
     65       exchange_sig: EddsaSignature;
     66 
     67       // Exchange public key used to create the
     68       // signature.
     69       exchange_pub: EddsaPublicKey;
     70 
     71       // Time when the exchange created the signature.
     72       exchange_timestamp: Timestamp;
     73 
     74       // Expiration time for the provided information.
     75       expiration_time: Timestamp;
     76 
     77       // KYC details (key-value pairs) as requested.
     78       // The keys will match the elements of the
     79       // ``details`` array from the request.
     80       attributes: CustomerKycAttributes;
     81     }