POST /management/instances

This request will be used to create a new merchant instance in the backend. It is only available for the implicit admin instance.

Required permission: instances-write

Request:

The request must be a InstanceConfigurationRequest.

Response:

200 Ok:

An instance has been created and a login token is being returned. The response body will be a InstanceCreatedResponse

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

204 No content:

The backend has successfully created the instance.

400 Bad Request:

The request body is malformed or a required field is missing. Returned with TALER_EC_GENERIC_PARAMETER_MALFORMED or TALER_EC_GENERIC_PARAMETER_MISSING.

409 Conflict:

This instance already exists, but with other configuration options. Use “PATCH” to update an instance configuration. Alternatively, the currency provided in the configuration does not match the currency supported by this backend. Another possible conflict would be if a deleted but not purged instance is known under this ID to the backend. Returned with TALER_EC_MERCHANT_PRIVATE_POST_INSTANCES_ALREADY_EXISTS or TALER_EC_MERCHANT_PRIVATE_POST_INSTANCES_PURGE_REQUIRED.

413 Request entity too large:

The uploaded body is to long, it exceeds the size limit. Returned with an error code of TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT.

500 Internal Server Error:

The server experienced an internal failure. Returned with TALER_EC_GENERIC_DB_STORE_FAILED, TALER_EC_GENERIC_DB_START_FAILED or TALER_EC_GENERIC_DB_COMMIT_FAILED.

Details:

interface InstanceConfigurationRequest {

  // Name of the merchant instance to create (will become $INSTANCE).
  // Must match the regex ^[A-Za-z0-9][A-Za-z0-9_.@-]+$.
  id: string;

  // Merchant name corresponding to this instance.
  name: string;

  // Merchant email for customer contact and password reset.
  email?: string;

  // Merchant phone number for password reset (2-FA)
  // @since **v21**.
  phone_number?: string;

  // Merchant public website.
  website?: string;

  // Merchant logo.
  logo?: ImageDataUrl;

  // Authentication settings for this instance
  auth: InstanceAuthConfigurationMessage;

  // The merchant's physical address (to be put into contracts).
  address: Location;

  // The jurisdiction under which the merchant conducts its business
  // (to be put into contracts).
  jurisdiction: Location;

  // Use STEFAN curves to determine default fees?
  // If false, no fees are allowed by default.
  // Can always be overridden by the frontend on a per-order basis.
  use_stefan: boolean;

  // If the frontend does NOT specify a payment deadline, how long should
  // offers we make be valid by default?
  // Optional @since **v22** (before the setting was mandatory).
  // If not provided, the global merchant default will be used.
  default_pay_delay?: RelativeTime;

  // If the frontend does NOT specify a refund deadline, how long should
  // refunds be allowed by default? Added on top of the
  // payment deadline.
  // @since **v22**
  default_refund_delay?: RelativeTime;

  // If the frontend does NOT specify an execution date, how long should
  // we tell the exchange to wait to aggregate transactions before
  // executing the wire transfer?  This delay is added on top of
  // the refund deadline and afterwards subject to rounding
  // via the default_wire_transfer_rounding_interval.
  // Optional @since **v22** (before the setting was mandatory).
  // If not provided, the global merchant default will be used.
  default_wire_transfer_delay?: RelativeTime;

  // How far should the wire deadline (if computed with the help of
  // the default_wire_transfer_delay) be rounded up to compute
  // the ultimate wire deadline?
  // @since **v22**, defaults to no rounding if not given.
  default_wire_transfer_rounding_interval?: RoundingInterval;
}

interface InstanceCreatedResponse {

  // The login token that can be used to access resources
  // that are in scope for some time. Must be prefixed
  // with "Bearer " when used in the "Authorization" HTTP header.
  // Will already begin with the RFC 8959 prefix.
  // **Since v19**
  access_token: string;

  // Legacy field for the access token.
  // @deprecated since **v19**.
  token: string;

  // Scope of the access token
  scope: "readonly" | "write" | "all" | "order-simple" | "order-pos" | "order-mgmt" | "order-full";

  // True if the access token can be refreshed.
  refreshable: boolean;

  // Time when the access token expires.
  expiration: Timestamp;

}