taler-docs

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

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

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