taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

post-purses-PURSE_PUB-merge.rst (4943B)

      1 .. http:post:: /purses/$PURSE_PUB/merge
      2 
      3   Merge purse with account, adding the value of the purse into
      4   the account.  Endpoint to be used by the receiver of a PUSH payment.
      5 
      6   **Request:**
      7 
      8   The request body must be a `MergeRequest` object.
      9 
     10   **Response:**
     11 
     12   :http:statuscode:`200 OK`:
     13     The operation succeeded, the exchange confirms that the
     14     funds were merged into the account.
     15     The response will include a `MergeSuccess` object.
     16   :http:statuscode:`400 Bad Request`:
     17     The request body is malformed or a parameter is invalid.
     18     This response comes with a standard `ErrorDetail` response with
     19     a code of ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
     20   :http:statuscode:`402 Payment Required`:
     21     The purse is not yet full and more money needs to be deposited
     22     before the merge can be made.
     23     This response comes with a standard `ErrorDetail` response with
     24     a code of ``TALER_EC_EXCHANGE_PURSE_NOT_FULL``.
     25   :http:statuscode:`403 Forbidden`:
     26     The signature of the merge request or the reserve was invalid.
     27     This response comes with a standard `ErrorDetail` response.
     28     Possible error codes include
     29     ``TALER_EC_EXCHANGE_PURSE_MERGE_INVALID_MERGE_SIGNATURE`` or
     30     ``TALER_EC_EXCHANGE_PURSE_MERGE_INVALID_RESERVE_SIGNATURE``.
     31   :http:statuscode:`404 Not found`:
     32     The merge operation failed as we could not find the purse
     33     or the partner exchange.
     34     This response comes with a standard `ErrorDetail` response.
     35     Possible error codes include
     36     ``TALER_EC_EXCHANGE_GENERIC_PURSE_UNKNOWN`` or
     37     ``TALER_EC_EXCHANGE_MERGE_PURSE_PARTNER_UNKNOWN``.
     38   :http:statuscode:`409 Conflict`:
     39     The purse was already merged into a different reserve.
     40     The response will include a `MergeConflict` object.
     41   :http:statuscode:`410 Gone`:
     42     The purse has already expired and thus can no longer be merged.
     43     This response comes with a standard `ErrorDetail` response with
     44     a code of ``TALER_EC_EXCHANGE_GENERIC_PURSE_EXPIRED``.
     45   :http:statuscode:`413 Request entity too large`:
     46     The uploaded body is to long, it exceeds the size limit.
     47     Returned with an error code of
     48     ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
     49   :http:statuscode:`451 Unavailable For Legal Reasons`:
     50     This account has not yet passed the KYC checks.
     51     The client must pass KYC checks before proceeding with the merge.
     52     The response will be an `LegitimizationNeededResponse` object.
     53   :http:statuscode:`500 Internal Server Error`:
     54     The server experienced an internal error.
     55     This response comes with a standard `ErrorDetail` response.
     56     Possible error codes include
     57     ``TALER_EC_GENERIC_DB_STORE_FAILED``,
     58     ``TALER_EC_GENERIC_DB_FETCH_FAILED``, or
     59     ``TALER_EC_EXCHANGE_GENERIC_WIRE_FEES_MISSING``.
     60 
     61   **Details:**
     62 
     63   .. ts:def:: MergeRequest
     64 
     65     interface MergeRequest {
     66 
     67       // Normalized payto URI of the account the purse is to be merged into.
     68       // Must be of the form: 'payto://taler/$EXCHANGE_URL/$RESERVE_PUB'.
     69       payto_uri: string;
     70 
     71       // EdDSA signature of the account/reserve affirming the merge
     72       // over a `TALER_AccountMergeSignaturePS`.
     73       // Must be of purpose ``TALER_SIGNATURE_ACCOUNT_MERGE``
     74       reserve_sig: EddsaSignature;
     75 
     76       // EdDSA signature of the merge private key affirming the merge
     77       // over a `TALER_PurseMergeSignaturePS`.
     78       // Must be of purpose ``TALER_SIGNATURE_PURSE_MERGE``.
     79       merge_sig: EddsaSignature;
     80 
     81       // Client-side timestamp of when the merge request was made.
     82       merge_timestamp: Timestamp;
     83 
     84     }
     85 
     86   .. ts:def:: MergeSuccess
     87 
     88      interface MergeSuccess {
     89 
     90       // Amount merged (excluding deposit fees).
     91       merge_amount: Amount;
     92 
     93       // Time at which the merge came into effect.
     94       // Maximum of the "payment_timestamp" and the
     95       // "merge_timestamp".
     96       exchange_timestamp: Timestamp;
     97 
     98       // EdDSA signature of the exchange affirming the merge of
     99       // purpose ``TALER_SIGNATURE_PURSE_MERGE_SUCCESS``
    100       // over `TALER_PurseMergeSuccessSignaturePS`.
    101       // Signs over the above and the account public key.
    102       exchange_sig: EddsaSignature;
    103 
    104       // public key used to create the signature.
    105       exchange_pub: EddsaPublicKey;
    106 
    107     }
    108 
    109   .. ts:def:: MergeConflict
    110 
    111     interface MergeConflict {
    112 
    113       // Must be equal to TALER_EC_EXCHANGE_PURSE_MERGE_CONFLICTING_META_DATA
    114       code: Integer;
    115 
    116       // Client-side timestamp of when the merge request was made.
    117       merge_timestamp: Timestamp;
    118 
    119       // EdDSA signature of the purse private key affirming the merge
    120       // over a `TALER_PurseMergeSignaturePS`.
    121       // Must be of purpose ``TALER_SIGNATURE_PURSE_MERGE``.
    122       merge_sig: EddsaSignature;
    123 
    124       // Base URL of the exchange receiving the payment, only present
    125       // if the exchange hosting the reserve is not this exchange.
    126       partner_url?: string;
    127 
    128       // Public key of the reserve that the purse was merged into.
    129       reserve_pub: EddsaPublicKey;
    130     }