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

This is used to create a fountain: a bearer credential that entitles a wallet to withdraw blind-signed promotional tokens for a set of token families (see DD 98). This endpoint is available since protocol vTokenFountains.

Required permission: fountains-write

Request:

The request must be a FountainCreateRequest.

Response:

200 OK:

The fountain was created successfully. Returns a FountainCreateResponse.

400 Bad Request:

The request body is malformed. Returned with TALER_EC_GENERIC_PARAMETER_MALFORMED.

404 Not found:

The merchant instance is unknown, or a token_family_slug in the grants does not refer to a known token family.

500 Internal Server Error:

The server experienced an internal failure.

Details:

interface FountainCreateRequest {

  // Human-readable description; preferably an opaque campaign
  // or recipient identifier from the institution's system.
  // The merchant backend does not need -- and should not
  // receive -- the user's real identity.
  description: string;

  // How often wallets holding this fountain's secret should
  // re-poll GET /fountain/info for updated grants.
  poll_freq: RelativeTime;

  // One grant per token family the user may withdraw
  // tokens for.
  grants: FountainGrant[];
}

interface FountainGrant {

  // Slug of the token family this grant refers to.
  token_family_slug: string;

  // Maximum number of tokens the fountain will blind-sign
  // per key validity period for this family.
  tokens_per_period_limit: Integer;

  // Number of tokens the wallet should aim to hold per period
  // (client-side stocking target; must not exceed
  // tokens_per_period_limit).
  tokens_per_period_stash: Integer;

  // Number of key slots ahead of the current one the wallet
  // may withdraw tokens for. Bounds prefetching and the time
  // for which already-withdrawn promotional tokens remain usable.
  key_window_size: Integer;
}

interface FountainCreateResponse {

  // Identifier of the fountain, used for subsequent CRUD
  // operations and included in the wallet onboarding URI.
  fountain_id: string;

  // 256-bit bearer credential for the wallet, Crockford
  // Base32 encoded. Returned exactly once; the backend
  // stores only a hash of it.
  fountain_secret: string;
}