taler-docs

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

post-private-accounts.rst (3478B)

      1 .. http:post:: [/instances/$INSTANCE]/private/accounts
      2 
      3   This is used to add an account to an instance.
      4 
      5   **Required permission:** ``accounts-write``
      6 
      7   **Request:**
      8 
      9   The request must have an `AccountAddDetails` body.
     10 
     11   **Response:**
     12 
     13   :http:statuscode:`200 Ok`:
     14     Adding the account was successful, we return the salt selected by the backend and the resulting wire hash in an `AccountAddResponse`.
     15   :http:statuscode:`202 Accepted`:
     16     2FA is required for this operation, usually to validate the
     17     email and/or phone numbers registered for the instance.
     18     This returns the `ChallengeResponse`. @since **v21**
     19   :http:statuscode:`404 Not found`:
     20     The merchant instance is unknown or it is not in our data.
     21   :http:statuscode:`403 Forbidden`:
     22     MFA channels are not available or permission denied.
     23   :http:statuscode:`409 Conflict`:
     24     The provided information is inconsistent with the current state of the instance.
     25     Usually this means we already have this account, but with conflicting credit facade information.
     26     Inactive accounts can be reactivated using this method even if the
     27     credit facade information differs from the previous state.
     28   :http:statuscode:`500 Internal Server Error`:
     29     The server experienced an internal failure.
     30     Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``.
     31 
     32   **Details:**
     33 
     34   .. ts:def:: AccountAddDetails
     35 
     36     interface AccountAddDetails {
     37 
     38       // Full payto:// URI of the account.
     39       payto_uri: string;
     40 
     41       // URL from where the merchant can download information
     42       // about incoming wire transfers to this account.
     43       credit_facade_url?: string;
     44 
     45       // Credentials to use when accessing the credit facade.
     46       // Never returned on a GET (as this may be somewhat
     47       // sensitive data). Can be set in POST
     48       // or PATCH requests to update (or delete) credentials.
     49       // To really delete credentials, set them to the type: "none".
     50       credit_facade_credentials?: FacadeCredentials;
     51 
     52       // Additional text to include in the wire transfer subject when
     53       // settling the payment. Note that the merchant MUST use this
     54       // consistently for the same ``merchant_pub`` and ``merchant_payto_uri``
     55       // as during aggregation *any* of these values may be selected
     56       // for the actual aggregated wire transfer. If a merchant wants
     57       // to use different ``extra_subject`` values for the same IBAN,
     58       // it should thus create multiple instances (with different
     59       // ``merchant_pub`` values). When changing the ``extra_subject``,
     60       // the change may thus not be immediately reflected in the
     61       // settlements.
     62       //
     63       // Must match [a-zA-Z0-9-.:]{1, 40}
     64       //
     65       // Optional. Since **v27**.
     66       extra_wire_subject_metadata?: string;
     67     }
     68 
     69   .. ts:def:: FacadeCredentials
     70 
     71     type FacadeCredentials =
     72       | NoFacadeCredentials
     73       | BasicAuthFacadeCredentials;
     74 
     75   .. ts:def:: NoFacadeCredentials
     76 
     77     interface NoFacadeCredentials {
     78        type: "none";
     79     };
     80 
     81   .. ts:def:: BasicAuthFacadeCredentials
     82 
     83     interface BasicAuthFacadeCredentials {
     84        type: "basic";
     85 
     86        // Username to use to authenticate
     87        username: string;
     88 
     89        // Password to use to authenticate
     90        password: string;
     91     };
     92 
     93   .. ts:def:: AccountAddResponse
     94 
     95     interface AccountAddResponse {
     96 
     97       // Hash over the wire details (including over the salt).
     98       h_wire: HashCode;
     99 
    100       // Salt used to compute h_wire.
    101       salt: HashCode;
    102 
    103     }