taler-docs

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

get-management-instances-INSTANCE.rst (4528B)

      1 .. http:get:: [/instances/$INSTANCE]/private
      2 .. http:get:: /management/instances/$INSTANCE
      3 
      4   This is used to query a specific merchant instance.  GET operations against
      5   an instance are authenticated by checking that an authorization is provided
      6   that matches either the credential required by the instance being modified
      7   OR the ``admin`` instance, depending on the access path used.
      8 
      9   This endpoint may be used even when mandatory TAN channels
     10   were not validated yet.
     11 
     12   Since **v42** this endpoint typically also supports requests
     13   with the "Accept" header requesting "text/plain".
     14   In this case, an plaintext response suitable for human consumption
     15   is returned.
     16 
     17   **Required permission:** ``instances-read`` on the ``/private`` path,
     18   ``instances-write`` on the ``/management/`` path (see :ref:`Scopes <merchant-api-scopes>`)
     19 
     20   **Response:**
     21 
     22   :http:statuscode:`200 OK`:
     23     The backend has successfully returned the list of instances stored. Returns
     24     a `QueryInstancesResponse`.
     25   :http:statuscode:`401 Unauthorized`:
     26     The request is unauthorized.
     27   :http:statuscode:`404 Not found`:
     28     The instance is unknown.
     29     Returned with ``TALER_EC_MERCHANT_GENERIC_INSTANCE_UNKNOWN``.
     30   :http:statuscode:`406 Not acceptable`:
     31     The merchant backend could not produce a response in the desired format.
     32     No error code is returned in this case.
     33     Since protocol **v42**.
     34 
     35   **Details:**
     36 
     37   .. ts:def:: QueryInstancesResponse
     38 
     39     interface QueryInstancesResponse {
     40 
     41       // Merchant name corresponding to this instance.
     42       name: string;
     43 
     44       // Merchant email for customer contact and password reset.
     45       email?: string;
     46 
     47       // True if the ``email`` address was validated.
     48       // @since **v21**.
     49       email_validated?: boolean;
     50 
     51       // Merchant phone number for password reset (2-FA)
     52       // @since **v21**.
     53       phone_number?: string;
     54 
     55       // True if the ``email`` address was validated.
     56       // @since **v21**.
     57       phone_validated?: boolean;
     58 
     59       // Merchant public website.
     60       website?: WebURL;
     61 
     62       // Merchant logo.
     63       logo?: ImageDataUrl;
     64 
     65       // Public key of the merchant/instance, in Crockford Base32 encoding.
     66       merchant_pub: EddsaPublicKey;
     67 
     68       // The merchant's physical address (to be put into contracts).
     69       address: Location;
     70 
     71       // The jurisdiction under which the merchant conducts its business
     72       // (to be put into contracts).
     73       jurisdiction: Location;
     74 
     75       // Use STEFAN curves to determine default fees?
     76       // If false, no fees are allowed by default.
     77       // Can always be overridden by the frontend on a per-order basis.
     78       use_stefan: boolean;
     79 
     80       // If the frontend does NOT specify a payment deadline, how long should
     81       // offers we make be valid by default? Added to the order creation
     82       // time.
     83       default_pay_delay: RelativeTime;
     84 
     85       // If the frontend does NOT specify a refund deadline, how long should
     86       // refunds be allowed by default? Added to the payment deadline.
     87       // @since **v22**
     88       default_refund_delay: RelativeTime;
     89 
     90       // If the frontend does NOT specify an execution date, how long should
     91       // we tell the exchange to wait to aggregate transactions before
     92       // executing the wire transfer?  This delay is added to the
     93       // refund deadline and subject to rounding to the
     94       // ``default_wire_transfer_rounding_interval``.
     95       default_wire_transfer_delay: RelativeTime;
     96 
     97       // Default interval to which wire deadlines computed by
     98       // adding the wire_transfer_delay on top of the refund
     99       // deadline should be rounded up to.
    100       // @since **v23**
    101       default_wire_transfer_rounding_interval: RoundingInterval;
    102 
    103       // Bank accounts of the merchant instance.
    104       accounts: ManagementAccountEntry[];
    105 
    106       // Authentication configuration.
    107       // Does not contain the token when token auth is configured.
    108       auth: {
    109         method: "external" | "token";
    110       };
    111 
    112     }
    113 
    114   .. ts:def:: ManagementAccountEntry
    115 
    116     interface ManagementAccountEntry {
    117 
    118       // Full payto:// URI of the account.
    119       payto_uri: string;
    120 
    121       // URL from where the merchant can download information
    122       // about incoming wire transfers to this account.
    123       credit_facade_url?: WebURL;
    124 
    125       // Hash over the wire details (including over the salt).
    126       h_wire: HashCode;
    127 
    128       // Salt used to compute h_wire.
    129       salt: HashCode;
    130 
    131       // true if this account is active,
    132       // false if it is historic.
    133       active: boolean;
    134     }