POST /purses/$PURSE_PUB/merge

Merge purse with account, adding the value of the purse into the account. Endpoint to be used by the receiver of a PUSH payment.

Request:

The request body must be a MergeRequest object.

Response:

200 OK:

The operation succeeded, the exchange confirms that the funds were merged into the account. The response will include a MergeSuccess 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.

402 Payment Required:

The purse is not yet full and more money needs to be deposited before the merge can be made. This response comes with a standard ErrorDetail response with a code of TALER_EC_EXCHANGE_PURSE_NOT_FULL.

403 Forbidden:

The signature of the merge request or the reserve was invalid. This response comes with a standard ErrorDetail response. Possible error codes include TALER_EC_EXCHANGE_PURSE_MERGE_INVALID_MERGE_SIGNATURE or TALER_EC_EXCHANGE_PURSE_MERGE_INVALID_RESERVE_SIGNATURE.

404 Not found:

The merge operation failed as we could not find the purse or the partner exchange. This response comes with a standard ErrorDetail response. Possible error codes include TALER_EC_EXCHANGE_GENERIC_PURSE_UNKNOWN or TALER_EC_EXCHANGE_MERGE_PURSE_PARTNER_UNKNOWN.

409 Conflict:

The purse was already merged into a different reserve. The response will include a MergeConflict object.

410 Gone:

The purse has already expired and thus can no longer be merged. 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_EXCHANGE_GENERIC_WIRE_FEES_MISSING.

Details:

interface MergeRequest {

  // Normalized payto URI of the account the purse is to be merged into.
  // Must be of the form: 'payto://taler/$EXCHANGE_URL/$RESERVE_PUB'.
  payto_uri: string;

  // EdDSA signature of the account/reserve affirming the merge
  // over a TALER_AccountMergeSignaturePS.
  // Must be of purpose TALER_SIGNATURE_ACCOUNT_MERGE
  reserve_sig: EddsaSignature;

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

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

}

 interface MergeSuccess {

  // Amount merged (excluding deposit fees).
  merge_amount: Amount;

  // Time at which the merge came into effect.
  // Maximum of the "payment_timestamp" and the
  // "merge_timestamp".
  exchange_timestamp: Timestamp;

  // EdDSA signature of the exchange affirming the merge of
  // purpose TALER_SIGNATURE_PURSE_MERGE_SUCCESS
  // over TALER_PurseMergeSuccessSignaturePS.
  // Signs over the above and the account public key.
  exchange_sig: EddsaSignature;

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

}

interface MergeConflict {

  // Must be equal to TALER_EC_EXCHANGE_PURSE_MERGE_CONFLICTING_META_DATA
  code: Integer;

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

  // 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;

  // Base URL of the exchange receiving the payment, only present
  // if the exchange hosting the reserve is not this exchange.
  partner_url?: string;

  // Public key of the reserve that the purse was merged into.
  reserve_pub: EddsaPublicKey;
}