taler-docs

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

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

      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:`402 Payment Required`:
     17     The purse is not yet full and more money needs to be deposited
     18     before the merge can be made.
     19   :http:statuscode:`403 Forbidden`:
     20     The signature of the merge request or the reserve was invalid.
     21     This response comes with a standard `ErrorDetail` response.
     22   :http:statuscode:`404 Not found`:
     23     The merge operation failed as we could not find the purse
     24     or the partner exchange.
     25     This response comes with a standard `ErrorDetail` response.
     26   :http:statuscode:`409 Conflict`:
     27     The purse was already merged into a different reserve.
     28     The response will include a `MergeConflict` object.
     29   :http:statuscode:`410 Gone`:
     30     The purse has already expired and thus can no longer be merged.
     31     This response comes with a standard `ErrorDetail` response.
     32   :http:statuscode:`451 Unavailable For Legal Reasons`:
     33     This account has not yet passed the KYC checks.
     34     The client must pass KYC checks before proceeding with the merge.
     35     The response will be an `LegitimizationNeededResponse` object.
     36 
     37   **Details:**
     38 
     39   .. ts:def:: MergeRequest
     40 
     41     interface MergeRequest {
     42 
     43       // Normalized payto URI of the account the purse is to be merged into.
     44       // Must be of the form: 'payto://taler/$EXCHANGE_URL/$RESERVE_PUB'.
     45       payto_uri: string;
     46 
     47       // EdDSA signature of the account/reserve affirming the merge
     48       // over a `TALER_AccountMergeSignaturePS`.
     49       // Must be of purpose ``TALER_SIGNATURE_ACCOUNT_MERGE``
     50       reserve_sig: EddsaSignature;
     51 
     52       // EdDSA signature of the merge private key affirming the merge
     53       // over a `TALER_PurseMergeSignaturePS`.
     54       // Must be of purpose ``TALER_SIGNATURE_PURSE_MERGE``.
     55       merge_sig: EddsaSignature;
     56 
     57       // Client-side timestamp of when the merge request was made.
     58       merge_timestamp: Timestamp;
     59 
     60     }
     61 
     62   .. ts:def:: MergeSuccess
     63 
     64      interface MergeSuccess {
     65 
     66       // Amount merged (excluding deposit fees).
     67       merge_amount: Amount;
     68 
     69       // Time at which the merge came into effect.
     70       // Maximum of the "payment_timestamp" and the
     71       // "merge_timestamp".
     72       exchange_timestamp: Timestamp;
     73 
     74       // EdDSA signature of the exchange affirming the merge of
     75       // purpose ``TALER_SIGNATURE_PURSE_MERGE_SUCCESS``
     76       // over `TALER_PurseMergeSuccessSignaturePS`.
     77       // Signs over the above and the account public key.
     78       exchange_sig: EddsaSignature;
     79 
     80       // public key used to create the signature.
     81       exchange_pub: EddsaPublicKey;
     82 
     83     }
     84 
     85   .. ts:def:: MergeConflict
     86 
     87     interface MergeConflict {
     88 
     89       // Client-side timestamp of when the merge request was made.
     90       merge_timestamp: Timestamp;
     91 
     92       // EdDSA signature of the purse private key affirming the merge
     93       // over a `TALER_PurseMergeSignaturePS`.
     94       // Must be of purpose ``TALER_SIGNATURE_PURSE_MERGE``.
     95       merge_sig: EddsaSignature;
     96 
     97       // Base URL of the exchange receiving the payment, only present
     98       // if the exchange hosting the reserve is not this exchange.
     99       partner_url?: string;
    100 
    101       // Public key of the reserve that the purse was merged into.
    102       reserve_pub: EddsaPublicKey;
    103     }