taler-docs

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

post-private-accounts.rst (4137B)

      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:`400 Bad Request`:
     24     The request body is malformed.
     25     Returned with ``TALER_EC_GENERIC_PAYTO_URI_MALFORMED``,
     26     ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` or
     27     ``TALER_EC_GENERIC_PARAMETER_MISSING``.
     28   :http:statuscode:`409 Conflict`:
     29     The provided information is inconsistent with the current state of the instance.
     30     Usually this means we already have this account, but with conflicting credit facade information.
     31     Inactive accounts can be reactivated using this method even if the
     32     credit facade information differs from the previous state.
     33     Returned with ``TALER_EC_MERCHANT_PRIVATE_ACCOUNT_EXISTS``.
     34   :http:statuscode:`413 Request entity too large`:
     35     The uploaded body is to long, it exceeds the size limit.
     36     Returned with an error code of
     37     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
     38   :http:statuscode:`500 Internal Server Error`:
     39     The server experienced an internal failure.
     40     Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``,
     41     ``TALER_EC_GENERIC_DB_FETCH_FAILED``,
     42     ``TALER_EC_GENERIC_DB_COMMIT_FAILED``,
     43     ``TALER_EC_GENERIC_DB_SOFT_FAILURE`` or
     44     ``TALER_EC_GENERIC_DB_INVARIANT_FAILURE``.
     45 
     46   **Details:**
     47 
     48   .. ts:def:: AccountAddDetails
     49 
     50     interface AccountAddDetails {
     51 
     52       // Full payto:// URI of the account.
     53       payto_uri: string;
     54 
     55       // URL from where the merchant can download information
     56       // about incoming wire transfers to this account.
     57       credit_facade_url?: string;
     58 
     59       // Credentials to use when accessing the credit facade.
     60       // Never returned on a GET (as this may be somewhat
     61       // sensitive data). Can be set in POST
     62       // or PATCH requests to update (or delete) credentials.
     63       // To really delete credentials, set them to the type: "none".
     64       credit_facade_credentials?: FacadeCredentials;
     65 
     66       // Additional text to include in the wire transfer subject when
     67       // settling the payment. Note that the merchant MUST use this
     68       // consistently for the same ``merchant_pub`` and ``merchant_payto_uri``
     69       // as during aggregation *any* of these values may be selected
     70       // for the actual aggregated wire transfer. If a merchant wants
     71       // to use different ``extra_subject`` values for the same IBAN,
     72       // it should thus create multiple instances (with different
     73       // ``merchant_pub`` values). When changing the ``extra_subject``,
     74       // the change may thus not be immediately reflected in the
     75       // settlements.
     76       //
     77       // Must match [a-zA-Z0-9-.:]{1, 40}
     78       //
     79       // Optional. Since **v27**.
     80       extra_wire_subject_metadata?: string;
     81     }
     82 
     83   .. ts:def:: FacadeCredentials
     84 
     85     type FacadeCredentials =
     86       | NoFacadeCredentials
     87       | BasicAuthFacadeCredentials;
     88 
     89   .. ts:def:: NoFacadeCredentials
     90 
     91     interface NoFacadeCredentials {
     92        type: "none";
     93     };
     94 
     95   .. ts:def:: BasicAuthFacadeCredentials
     96 
     97     interface BasicAuthFacadeCredentials {
     98        type: "basic";
     99 
    100        // Username to use to authenticate
    101        username: string;
    102 
    103        // Password to use to authenticate
    104        password: string;
    105     };
    106 
    107   .. ts:def:: AccountAddResponse
    108 
    109     interface AccountAddResponse {
    110 
    111       // Hash over the wire details (including over the salt).
    112       h_wire: HashCode;
    113 
    114       // Salt used to compute h_wire.
    115       salt: HashCode;
    116 
    117     }