POST /purses/$PURSE_PUB/deposit

Deposit money into a purse. Used by the buyer for a PULL payment.

Request:

The request body must be a PurseDeposits object.

Response:

200 OK:

The operation succeeded, the exchange confirms that all coins were deposited into the purse. The response will include a PurseDepositSuccessResponse object.

400 Bad Request:

The request body is malformed or a parameter is invalid. This response comes with a standard ErrorDetail response with a code of TALER_EC_GENERIC_PARAMETER_MALFORMED.

403 Forbidden:

A coin or denomination signature is invalid. This response comes with a standard ErrorDetail response.

404 Not found:

The purse is unknown. This response comes with a standard ErrorDetail response with a code of TALER_EC_EXCHANGE_GENERIC_PURSE_UNKNOWN.

409 Conflict:

The deposit operation has either failed because a coin has insufficient residual value, or because the same public key of the coin has been previously used with a different denomination. Which case it is can be decided by looking at the error code (TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS or TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY or TALER_EC_EXCHANGE_PURSE_DEPOSIT_CONFLICTING_META_DATA). This response comes with a standard PurseConflict response (alas some cases are impossible).

410 Gone:

The purse has expired, was deleted, or the deposit was already decided. Possible error codes include TALER_EC_EXCHANGE_GENERIC_PURSE_EXPIRED, TALER_EC_EXCHANGE_GENERIC_PURSE_DELETED, or TALER_EC_EXCHANGE_PURSE_DEPOSIT_DECIDED_ALREADY.

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 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, TALER_EC_GENERIC_DB_START_FAILED, or TALER_EC_GENERIC_FAILED_COMPUTE_AMOUNT.

Details:

interface PurseDeposits {

  // Array of coins to deposit into the purse.
  deposits: PurseDeposit[];
}

interface PurseDeposit {

  // Amount to be deposited, can be a fraction of the
  // coin's total value.
  amount: Amount;

  // Hash of denomination RSA key with which the coin is signed.
  denom_pub_hash: HashCode;

  // Exchange's unblinded RSA signature of the coin.
  ub_sig: DenominationSignature;

  // Age commitment for the coin, if the denomination is age-restricted.
  age_commitment?: AgeCommitment;

  // Attestation for the minimum age, if the denomination is age-restricted.
  attest?: Attestation;

  // Signature over TALER_PurseDepositSignaturePS
  // of purpose TALER_SIGNATURE_WALLET_PURSE_DEPOSIT
  // made by the customer with the
  // coin's private key.
  coin_sig: EddsaSignature;

  // Public key of the coin being deposited into the purse.
  coin_pub: EddsaPublicKey;

}

 interface PurseDepositSuccessResponse {

  // Total amount paid into the purse.
  total_deposited: Amount;

  // Total amount expected in the purse.
  purse_value_after_fees: Amount;

  // Time at which the deposit came into effect.
  exchange_timestamp: Timestamp;

  // Indicative time by which the purse should expire
  // if it has not been merged into an account. At this
  // point, all of the deposits made will be auto-refunded.
  purse_expiration: Timestamp;

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

  // EdDSA signature of the exchange affirming the payment,
  // of purpose TALER_SIGNATURE_PURSE_DEPOSIT_CONFIRMED
  // over a TALER_PurseDepositConfirmedSignaturePS.
  // Signs over the above and the purse public key and
  // the hash of the contract terms.
  exchange_sig: EddsaSignature;

  // public key used to create the signature.
  exchange_pub: EddsaPublicKey;

}

// AgeCommitment is an array of public keys, one for each age group of the
// age-restricted denomination.
type AgeCommitment = Edx25519PublicKey[];

// An attestation for a minimum age is an Edx25519 signature of the age
// with purpose TALER_SIGNATURE_WALLET_AGE_ATTESTATION.
type Attestation = string;