post-private-accounts.rst (3233B)
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:`409 Conflict`: 22 The provided information is inconsistent with the current state of the instance. 23 Usually this means we already have this account, but with conflicting credit facade information. 24 Inactive accounts can be reactivated using this method even if the 25 credit facade information differs from the previous state. 26 27 **Details:** 28 29 .. ts:def:: AccountAddDetails 30 31 interface AccountAddDetails { 32 33 // Full payto:// URI of the account. 34 payto_uri: string; 35 36 // URL from where the merchant can download information 37 // about incoming wire transfers to this account. 38 credit_facade_url?: string; 39 40 // Credentials to use when accessing the credit facade. 41 // Never returned on a GET (as this may be somewhat 42 // sensitive data). Can be set in POST 43 // or PATCH requests to update (or delete) credentials. 44 // To really delete credentials, set them to the type: "none". 45 credit_facade_credentials?: FacadeCredentials; 46 47 // Additional text to include in the wire transfer subject when 48 // settling the payment. Note that the merchant MUST use this 49 // consistently for the same ``merchant_pub`` and ``merchant_payto_uri`` 50 // as during aggregation *any* of these values may be selected 51 // for the actual aggregated wire transfer. If a merchant wants 52 // to use different ``extra_subject`` values for the same IBAN, 53 // it should thus create multiple instances (with different 54 // ``merchant_pub`` values). When changing the ``extra_subject``, 55 // the change may thus not be immediately reflected in the 56 // settlements. 57 // 58 // Must match [a-zA-Z0-9-.:]{1, 40} 59 // 60 // Optional. Since **v27**. 61 extra_wire_subject_metadata?: string; 62 } 63 64 .. ts:def:: FacadeCredentials 65 66 type FacadeCredentials = 67 | NoFacadeCredentials 68 | BasicAuthFacadeCredentials; 69 70 .. ts:def:: NoFacadeCredentials 71 72 interface NoFacadeCredentials { 73 type: "none"; 74 }; 75 76 .. ts:def:: BasicAuthFacadeCredentials 77 78 interface BasicAuthFacadeCredentials { 79 type: "basic"; 80 81 // Username to use to authenticate 82 username: string; 83 84 // Password to use to authenticate 85 password: string; 86 }; 87 88 .. ts:def:: AccountAddResponse 89 90 interface AccountAddResponse { 91 92 // Hash over the wire details (including over the salt). 93 h_wire: HashCode; 94 95 // Salt used to compute h_wire. 96 salt: HashCode; 97 98 }