POST /reserves/$RESERVE_PUB/purse

Create purse for an account. First step of a PULL payment.

Request:

The request body must be a ReservePurseRequest object.

Response:

200 OK:

The operation succeeded, the exchange confirms that the purse was allocated. The response will include a PurseCreateSuccessResponse object.

400 Bad Request:

The request is invalid. In addition to generic error codes, the following specific error codes may be returned:

1. TALER_EC_EXCHANGE_RESERVES_PURSE_EXPIRATION_BEFORE_NOW: The requested purse expiration time is in the past.

2. TALER_EC_EXCHANGE_RESERVES_PURSE_CREATE_INSUFFICIENT_FUNDS: The reserve does not have enough funds to create this reserve.

3. TALER_EC_EXCHANGE_RESERVES_PURSE_EXPIRATION_IS_NEVER: A purse expiration time of “never” is not allowed.

4. TALER_EC_EXCHANGE_RESERVES_PURSE_FEE_TOO_LOW: The specified purse fee is lower than allowed.

403 Forbidden:

Account or contract signature is invalid. This response comes with a standard ErrorDetail response. Returned with error codes of: - TALER_EC_EXCHANGE_PURSE_CREATE_SIGNATURE_INVALID - TALER_EC_EXCHANGE_PURSE_ECONTRACT_SIGNATURE_INVALID - TALER_EC_EXCHANGE_RESERVES_PURSE_MERGE_SIGNATURE_INVALID - TALER_EC_EXCHANGE_RESERVES_RESERVE_MERGE_SIGNATURE_INVALID

404 Not found:

The purse creation operation failed as we could not find the reserve. This response comes with a standard ErrorDetail response. Returned with an EC of TALER_EC_EXCHANGE_GENERIC_RESERVE_UNKNOWN

409 Conflict:

The purse creation failed because a purse with the same public key but different meta data was created previously or the funds for the operation were insufficient. Which specific conflict it is can be decided by looking at the error code: - TALER_EC_EXCHANGE_PURSE_CREATE_CONFLICTING_META_DATA - TALER_EC_EXCHANGE_PURSE_DEPOSIT_CONFLICTING_META_DATA - TALER_EC_EXCHANGE_PURSE_ECONTRACT_CONFLICTING_META_DATA - TALER_EC_EXCHANGE_RESERVES_PURSE_CREATE_INSUFFICIENT_FUNDS - TALER_EC_EXCHANGE_RESERVES_PURSE_CREATE_CONFLICTING_META_DATA The specific fields of the response depend on the error code and include the signatures (and what was signed over) proving the conflict. The response will be a PurseConflict response (but not a DepositDoubleSpendError).

410 Gone:

The purse has expired. This response comes with a standard ErrorDetail response with a code of TALER_EC_EXCHANGE_GENERIC_PURSE_EXPIRED.

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.

451 Unavailable For Legal Reasons:

This account has not yet passed the KYC checks. The client must pass KYC checks before proceeding with the merge. The response will be an LegitimizationNeededResponse object.

500 Internal Server Error:

The server experienced an internal error. This response comes with a standard ErrorDetail response. Possible error codes include TALER_EC_GENERIC_DB_STORE_FAILED, TALER_EC_GENERIC_DB_FETCH_FAILED, or TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE.

503 Service unavailable:

The server could not process the request because it is currently unavailable. Error codes include: - TALER_EC_EXCHANGE_GENERIC_KEYS_MISSING - TALER_EC_EXCHANGE_GENERIC_GLOBAL_FEES_MISSING

Details:

interface ReservePurseRequest {

  // Minimum amount that must be credited to the reserve, that is
  // the total value of the purse minus the deposit fees.
  // If the deposit fees are lower, the contribution to the
  // reserve can be higher!
  purse_value: Amount;

  // Minimum age required for all coins deposited into the purse.
  min_age: Integer;

  // Purse fee the reserve owner is willing to pay
  // for the purse creation. Optional, if not present
  // the purse is to be created from the purse quota
  // of the reserve.
  purse_fee?: Amount;

  // Optional encrypted contract, in case the buyer is
  // proposing the contract and thus establishing the
  // purse with the payment.
  econtract?: EncryptedContract;

  // EdDSA public key used to approve merges of this purse.
  merge_pub: EddsaPublicKey;

  // EdDSA signature of the purse private key affirming the merge
  // over a TALER_PurseMergeSignaturePS.
  // Must be of purpose TALER_SIGNATURE_PURSE_MERGE.
  merge_sig: EddsaSignature;

  // EdDSA signature of the account/reserve affirming the merge.
  // Must be of purpose TALER_SIGNATURE_WALLET_ACCOUNT_MERGE
  reserve_sig: EddsaSignature;

  // Purse public key.
  purse_pub: EddsaPublicKey;

  // EdDSA signature of the purse over
  // TALER_PurseRequestSignaturePS of
  // purpose TALER_SIGNATURE_PURSE_REQUEST
  // confirming that the
  // above details hold for this purse.
  purse_sig: EddsaSignature;

  // SHA-512 hash of the contact of the purse.
  h_contract_terms: HashCode;

  // Client-side timestamp of when the merge request was made.
  merge_timestamp: Timestamp;

  // Indicative time by which the purse should expire
  // if it has not been paid.
  purse_expiration: Timestamp;

}