POST [/instances/$INSTANCE]/private/accounts

This is used to add an account to an instance.

Required permission: accounts-write

Request:

The request must have an AccountAddDetails body.

Response:

200 Ok:

Adding the account was successful, we return the salt selected by the backend and the resulting wire hash in an AccountAddResponse.

202 Accepted:

2FA is required for this operation, usually to validate the email and/or phone numbers registered for the instance. This returns the ChallengeResponse. @since v21

404 Not found:

The merchant instance is unknown or it is not in our data.

409 Conflict:

The provided information is inconsistent with the current state of the instance. Usually this means we already have this account, but with conflicting credit facade information. Inactive accounts can be reactivated using this method even if the credit facade information differs from the previous state.

Details:

interface AccountAddDetails {

  // Full payto:// URI of the account.
  payto_uri: string;

  // URL from where the merchant can download information
  // about incoming wire transfers to this account.
  credit_facade_url?: string;

  // Credentials to use when accessing the credit facade.
  // Never returned on a GET (as this may be somewhat
  // sensitive data). Can be set in POST
  // or PATCH requests to update (or delete) credentials.
  // To really delete credentials, set them to the type: "none".
  credit_facade_credentials?: FacadeCredentials;

  // Additional text to include in the wire transfer subject when
  // settling the payment. Note that the merchant MUST use this
  // consistently for the same merchant_pub and merchant_payto_uri
  // as during aggregation *any* of these values may be selected
  // for the actual aggregated wire transfer. If a merchant wants
  // to use different extra_subject values for the same IBAN,
  // it should thus create multiple instances (with different
  // merchant_pub values). When changing the extra_subject,
  // the change may thus not be immediately reflected in the
  // settlements.
  //
  // Must match [a-zA-Z0-9-.:]{1, 40}
  //
  // Optional. Since **v27**.
  extra_wire_subject_metadata?: string;
}

type FacadeCredentials =
  | NoFacadeCredentials
  | BasicAuthFacadeCredentials;

interface NoFacadeCredentials {
   type: "none";
};

interface BasicAuthFacadeCredentials {
   type: "basic";

   // Username to use to authenticate
   username: string;

   // Password to use to authenticate
   password: string;
};

interface AccountAddResponse {

  // Hash over the wire details (including over the salt).
  h_wire: HashCode;

  // Salt used to compute h_wire.
  salt: HashCode;

}