taler-docs

post-orders-ORDER_ID-pay.rst (23276B)

---

 .. http:post:: [/instances/$INSTANCE]/orders/$ORDER_ID/pay
 
   Pay for an order by giving a deposit permission for coins.  Typically used by
   the customer's wallet.  Note that this request does not include the
   usual ``h_contract`` argument to authenticate the wallet, as the hash of
   the contract is implied by the signatures of the coins.  Furthermore, this
   API doesn't really return useful information about the order.
 
   Repeating the request for an order that is already paid (a *replay*) is
   answered from the state stored with the original payment: the token
   signatures are the ones created for the original payment, and donation
   receipts that are still missing are requested from the Donau with the
   ``budikeypairs`` of the original payment, regardless of the ``wallet_data``
   of the replay.  Since protocol **vDonauReceipts**, a replay is refused
   once the order has been refunded, even if only in part.
 
   **Request:**
 
   The request must be a `pay request <PayRequest>`.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The exchange accepted all of the coins.
     The body is a `payment response <PaymentResponse>`.
     If the wallet requested donation receipts, the Donau issued them
     and they are part of the response.
     The ``frontend`` should now fulfill the contract.
     Note that it is possible that refunds have been granted.
   :http:statuscode:`400 Bad request`:
     Either the client request is malformed or some specific processing error
     happened that may be the fault of the client as detailed in the JSON body
     of the response.
     This includes the case where the payment is insufficient (sum is below
     the required total amount, for example because the wallet calculated the
     fees wrong).
     Applicable error codes:
 
     * ``MERCHANT_POST_ORDERS_ID_PAY_DENOMINATION_KEY_NOT_FOUND``: Wallet tried
       to pay with a non-existent denomination.
     * ``MERCHANT_POST_ORDERS_ID_PAY_DENOMINATION_DEPOSIT_EXPIRED``: The
       denomination used for payment has expired for deposits.
     * ``MERCHANT_POST_ORDERS_ID_PAY_AGE_COMMITMENT_MISSING``: An age commitment
       is required but was not provided.
     * ``MERCHANT_POST_ORDERS_ID_PAY_AGE_COMMITMENT_SIZE_MISMATCH``: The age
       commitment has the wrong number of public keys.
     * ``MERCHANT_POST_ORDERS_ID_PAY_AGE_VERIFICATION_FAILED``: The age
       verification signature is invalid.
     * ``MERCHANT_POST_ORDERS_ID_PAY_AGE_COMMITMENT_HASH_MISSING``: The age
       commitment hash is required but was not provided.
     * ``MERCHANT_POST_ORDERS_ID_PAY_PAYMENT_INSUFFICIENT``: The total payment
       amount is insufficient to cover the order.
     * ``MERCHANT_POST_ORDERS_ID_PAY_INSUFFICIENT_DUE_TO_FEES``: The payment
       is insufficient because fees exceed what is covered.
     * ``MERCHANT_POST_ORDERS_ID_PAY_TOKEN_ISSUE_SIG_INVALID``: A token issue
       signature is invalid.
     * ``MERCHANT_POST_ORDERS_ID_PAY_TOKEN_USE_SIG_INVALID``: A token use
       signature is invalid.
     * ``MERCHANT_POST_ORDERS_ID_PAY_TOKEN_COUNT_MISMATCH``: The number of
       input tokens does not match the expected count.
     * ``MERCHANT_POST_ORDERS_ID_PAY_TOKEN_ENVELOPE_COUNT_MISMATCH``: The number
       of output token envelopes does not match the expected count.
     * ``MERCHANT_POST_ORDERS_ID_PAY_CHOICE_INDEX_OUT_OF_BOUNDS``: The
       ``choice_index`` in the wallet data is out of range.
     * ``MERCHANT_POST_ORDERS_ID_PAY_CHOICE_INDEX_MISSING``: The
       ``choice_index`` is required but was not provided.
     * ``MERCHANT_GENERIC_EXCHANGE_UNTRUSTED``: The exchange used for a coin
       is not trusted by this merchant.
     * ``MERCHANT_POST_ORDERS_ID_PAY_AMOUNT_OVERFLOW``: Payment amount overflowed.
     * ``MERCHANT_POST_ORDERS_ID_PAY_FEES_EXCEED_PAYMENT``: Fees exceed the payment.
     * ``MERCHANT_POST_ORDERS_ID_PAY_EXCHANGE_WIRE_FEE_ADDITION_FAILED``: Adding wire fees failed.
     * ``MERCHANT_POST_ORDERS_ID_PAY_REFUND_DEADLINE_PAST_WIRE_TRANSFER_DEADLINE``: Refund deadline past wire deadline.
     * ``MERCHANT_POST_ORDERS_ID_PAY_WIRE_HASH_UNKNOWN``: Wire hash unknown.
     * ``MERCHANT_POST_ORDERS_ID_PAY_WIRE_METHOD_UNSUPPORTED``: Wire method unsupported.
     * ``GENERIC_PARAMETER_MALFORMED``: A request parameter is malformed.
 
   :http:statuscode:`402 Payment required`:
     There used to be a sufficient payment, but due to refunds the amount effectively
     paid is no longer sufficient. (If the amount is generally insufficient, we
     return "400 Bad Request", only if this is because of refunds we return 402.)
     Returned with ``TALER_EC_MERCHANT_POST_ORDERS_ID_PAY_REFUNDED``.
   :http:statuscode:`403 Forbidden`:
     One of the coin signatures was not valid.
   :http:statuscode:`404 Not found`:
     The merchant backend could not find the order
     or the instance or a token family or
     the Donau charity specified in
     the contract and thus cannot process the payment.
     Applicable error codes:
 
     * ``MERCHANT_GENERIC_TOKEN_KEY_UNKNOWN``
     * ``MERCHANT_GENERIC_ORDER_UNKNOWN``
     * ``MERCHANT_GENERIC_DONAU_CHARITY_UNKNOWN``
     * ``MERCHANT_GENERIC_INSTANCE_UNKNOWN``
 
   :http:statuscode:`408 Request timeout`:
     The backend took too long to process the request. Likely the merchant's connection
     to the exchange timed out. Try again.
     Applicable error codes:
 
     * ``MERCHANT_GENERIC_EXCHANGE_TIMEOUT``
 
   :http:statuscode:`409 Conflict`:
     The exchange rejected the payment because a coin was already spent (or
     used in a different way for the same purchase previously), or
     the merchant rejected the payment because the order was already fully paid
     (and then return signatures with refunds) or has been refunded since it
     was paid. If a coin was already spent
     (this includes re-using the same coin after a refund),
     the response will include the ``exchange_url`` for which the payment failed,
     in addition to the response from the exchange to the :http:post:`/batch-deposit </batch-deposit>` request.
     Applicable error codes:
 
     * ``MERCHANT_POST_ORDERS_ID_PAY_INSUFFICIENT_FUNDS``:  Exchange reported insufficient
       funds for one of the coins.
     * ``MERCHANT_POST_ORDERS_ID_PAY_CHOICE_INDEX_MISMATCH``: The order was
       already paid, but completing a different choice than the one given in
       this request, so the request does not describe the payment that was
       made.  The response is an `AlreadyPaidChoiceResponse` and contains the
       ``choice_index`` the order was actually paid with.
       Since protocol **v42**.
     * ``MERCHANT_POST_ORDERS_ID_PAY_ALREADY_PAID``: The order was already
       fully paid by another wallet. The response includes refund signatures
       for the coins.
     * ``MERCHANT_POST_ORDERS_ID_PAY_TOKEN_INVALID``: A token was already used
       in a previous payment.
     * ``MERCHANT_POST_ORDERS_ID_PAY_DONATION_AMOUNT_MISMATCH``: The donation
       amount does not match the expected amount or exceeds what remains of
       the charity's yearly limit.  Since protocol **vDonauReceipts**, the
       donations whose receipts are still pending count against that limit.
     * ``MERCHANT_POST_ORDERS_ID_PAY_DONATION_YEAR_INVALID``: The ``year`` in
       the ``donau`` field of the wallet data is not the current year (UTC).
       Nothing was paid.  The response is a `DonationYearInvalidResponse`;
       the wallet should create donation receipt requests for the returned
       ``current_year`` and pay again.
       Since protocol **vDonauReceipts**.
     * ``MERCHANT_POST_ORDERS_ID_PAY_REPLAY_AFTER_REFUND``: The order was
       already paid and has since been refunded, possibly only in part, so the
       request cannot be replayed.  The response carries no payment
       signature, token signatures or donation receipts; the wallet should
       query the refunds instead.
       Since protocol **vDonauReceipts**.
     * ``MERCHANT_GENERIC_CURRENCY_MISMATCH``: Coin currency does not match
       the expected payment currency.
 
   :http:statuscode:`410 Gone`:
     The offer has expired and is no longer available or
     the provided payment has expired.
     Applicable error codes:
 
     * ``MERCHANT_POST_ORDERS_ID_PAY_DENOMINATION_DEPOSIT_EXPIRED``: payment expired
     * ``MERCHANT_POST_ORDERS_ID_PAY_OFFER_EXPIRED``: offer expired
 
   :http:statuscode:`412 Precondition failed`:
     The given exchange is not acceptable for this merchant, as it is not in the
     list of accepted exchanges and not audited by an approved auditor.
     TODO: Status code may be changed to 409 in the future as 412 is technically wrong.
 
   :http:statuscode:`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``.
 
   :http:statuscode:`451 Unavailable for Legal Reasons`:
     The exchange has rejected the deposit by the merchant
     for legal reasons. This is **not** exactly a client
     failure (and possibly nobody's fault except for the
     regulator). The wallet should suspend the payment and
     retain the selected coins and their deposit permissions.
     Once the merchant has resolved the issue, the user may
     resume the payment, which retries the same payment with
     the same coins, or abort it using the normal payment
     recovery procedure.  The wallet must not refresh or
     reselect coins solely because of this response.
     The body is a `PaymentDeniedLegallyResponse` with
     details about the failure.
     Since protocol **v17**.
     Returned with ``TALER_EC_MERCHANT_POST_ORDERS_ID_PAY_EXCHANGE_LEGALLY_REFUSED`` or
     ``TALER_EC_MERCHANT_POST_ORDERS_ID_PAY_EXCHANGE_TRANSACTION_LIMIT_VIOLATION``.
 
   :http:statuscode:`500 Internal Server Error`:
     The server experienced an internal failure.
     Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``,
     ``TALER_EC_GENERIC_DB_FETCH_FAILED``,
     ``TALER_EC_GENERIC_DB_START_FAILED``,
     ``TALER_EC_GENERIC_DB_COMMIT_FAILED``,
     ``TALER_EC_GENERIC_DB_SOFT_FAILURE``,
     ``TALER_EC_GENERIC_DB_INVARIANT_FAILURE``,
     ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE``,
     ``TALER_EC_GENERIC_FAILED_COMPUTE_JSON_HASH`` or
     ``TALER_EC_MERCHANT_GENERIC_DB_CONTRACT_CONTENT_INVALID``.
 
   :http:statuscode:`501 Not implemented`:
     This is returned if an optional feature required to
     process this particular payment is no longer implemented.
     This should only be possible if a different version
     of the backend software was deployed between order
     creation and payment.
 
     Applicable error codes:
 
     * ``MERCHANT_GENERIC_DONAU_NOT_CONFIGURED``: returned if donations are not supported
     * ``MERCHANT_GENERIC_FEATURE_NOT_AVAILABLE``: usually returned if a token type is not supported
 
   :http:statuscode:`502 Bad gateway`:
     The merchant's interaction with the exchange or the Donau failed in
     some way.
     For the exchange, the client might want to try again later.
     This includes failures such as the denomination key of a coin not being
     known to the exchange as far as the merchant can tell.
     The merchant only contacts the Donau after the payment succeeded, so
     a Donau failure does not undo the payment: the response then carries the
     payment confirmation.
     Applicable error codes:
 
     * ``MERCHANT_GENERIC_EXCHANGE_UNEXPECTED_STATUS``
     * ``MERCHANT_GENERIC_EXCHANGE_REPLY_MALFORMED``
     * ``MERCHANT_POST_ORDERS_ID_PAY_DONAU_RECEIPTS_DELAYED``: The payment
       succeeded, but the Donau could not issue the donation receipts at this
       time (it was unreachable, timed out, failed internally or replied with
       something malformed).  The body is a `PaymentDonauFailureResponse`.
       The wallet should treat the order as paid, keep its donation receipt
       requests and replay the payment request later.  The merchant keeps
       reporting this code until the Donau issues the receipts or stops
       issuing receipts for the donation year; from then on it reports
       ``MERCHANT_POST_ORDERS_ID_PAY_DONAU_RECEIPTS_REFUSED``.
       Since protocol **vDonauReceipts**.
     * ``MERCHANT_POST_ORDERS_ID_PAY_DONAU_RECEIPTS_REFUSED``: The payment
       succeeded, but the Donau refused to issue the donation receipts.  The
       body is a `PaymentDonauFailureResponse`.  The wallet should treat the
       order as paid, tell the user that the promised donation receipts will
       not be issued, and not replay the request.
       Since protocol **vDonauReceipts**.
     * ``MERCHANT_GENERIC_DONAU_INVALID_RESPONSE``: Only before protocol
       **vDonauReceipts**, for any Donau failure; the response then carried
       no payment confirmation.
 
   :http:statuscode:`504 Gateway timeout`:
     The merchant's interaction with the exchange took too long.
     The client might want to try again later.
 
   The backend will return verbatim the error codes received from the exchange's
   :ref:`deposit <deposit>` API.  If the wallet made a mistake, like by
   double-spending for example, the frontend should pass the reply verbatim to
   the browser/wallet.  If the payment was successful, the frontend MAY use
   this to trigger some business logic.
 
   **Details:**
 
   .. ts:def:: AlreadyPaidChoiceResponse
 
     interface AlreadyPaidChoiceResponse {
       // Error code identifying the conflict, always
       // ``MERCHANT_POST_ORDERS_ID_PAY_CHOICE_INDEX_MISMATCH``.
       code: number;
 
       // Index of the choice within the ``choices`` array of the
       // contract terms that the order was actually paid with. A client
       // that wants to refer to the payment that was made has to use
       // this choice instead of the one it asked for.
       choice_index: Integer;
     }
 
   .. ts:def:: PaymentResponse
 
     interface PaymentResponse {
       // Signature on ``TALER_PaymentResponsePS`` with the public
       // key of the merchant instance.
       sig: EddsaSignature;
 
       // Text to be shown to the point-of-sale staff as a proof of
       // payment.
       // For OTP devices using a challenge-signature algorithm
       // ("ECDSA_CHALLENGE" or "EDDSA_CHALLENGE"), contains the
       // Crockford Base32 encoded signature over the hash of the
       // order's challenge, made with the device private key.
       // Since protocol **v43**.
       pos_confirmation?: string;
 
       // Signed tokens for the outputs of type ``token``. Returned in
       // the same order as the token envelopes were provided in the
       // request. Specifically, the order will follow the order of the
       // outputs from the contract terms, and then within each output
       // follow the order in which the ``wallet_data`` contained the
       // respective blinded envelopes.
       // Since protocol **vDonauReceipts**, donation receipts are never
       // part of this array, see ``donau_sigs``.  Before, they were
       // present at the offset matching the place where a donation
       // receipt was indicated in the outputs array, and ``donau_sigs``
       // was absent; clients must still handle that layout when
       // ``donau_sigs`` is missing although they requested donation
       // receipts.
       // @since protocol **v21**
       token_sigs?: SignedTokenEnvelope[];
 
       // Donation receipts blindly signed by the Donau, in the order of
       // the ``budikeypairs`` in the ``donau`` field of the
       // `PayWalletData`.  Present if the wallet requested donation
       // receipts.
       // @since protocol **vDonauReceipts**
       donau_sigs?: SignedDonationReceipt[];
 
     }
 
   .. ts:def:: SignedDonationReceipt
 
     interface SignedDonationReceipt {
 
       // Blind signature made by the Donau over one of the
       // `BlindedDonationReceiptKeyPair` entries of the request.
       blind_sig: BlindedDonationReceiptSignature;
 
     }
 
   .. ts:def:: PaymentDonauFailureResponse
 
     interface PaymentDonauFailureResponse {
 
       // Numeric `error code <error-codes>`, either
       // ``MERCHANT_POST_ORDERS_ID_PAY_DONAU_RECEIPTS_DELAYED`` or
       // ``MERCHANT_POST_ORDERS_ID_PAY_DONAU_RECEIPTS_REFUSED``.
       code: Integer;
 
       // Human-readable description of the failure.
       hint?: string;
 
       // The order is paid: as in `PaymentResponse`.
       sig: EddsaSignature;
 
       // As in `PaymentResponse`.
       pos_confirmation?: string;
 
       // As in `PaymentResponse`.  The merchant's own token
       // signatures are returned even though the donation
       // receipts are missing.
       token_sigs?: SignedTokenEnvelope[];
 
       // Base URL of the Donau that was asked for the receipts.
       donau_url: WebURL;
 
       // HTTP status code of the Donau's reply, or 0 if there was
       // no reply (Donau unreachable, timeout, or the request could
       // not be created).  A malformed reply keeps its status code.
       donau_http_status: Integer;
 
       // Error code of the Donau's reply, if it had one.
       donau_ec?: Integer;
 
       // Hint of the Donau's reply, if it had one.
       donau_hint?: string;
 
     }
 
   .. ts:def:: DonationYearInvalidResponse
 
     interface DonationYearInvalidResponse {
 
       // Error code, always
       // ``MERCHANT_POST_ORDERS_ID_PAY_DONATION_YEAR_INVALID``.
       code: Integer;
 
       // Current year (UTC), the only year for which the merchant
       // accepts donation receipt requests.
       current_year: Integer;
 
     }
 
   .. ts:def:: PayRequest
 
     interface PayRequest {
       // The coins used to make the payment.
       coins: CoinPaySig[];
 
       // Input tokens required by choice indicated by ``choice_index``.
       // @since protocol **v21**
       tokens?: TokenUseSig[];
 
       // Custom inputs from the wallet for the contract.
       wallet_data?: PayWalletData;
 
       // The session for which the payment is made (or replayed).
       // Only set for session-based payments.  The empty session ID
       // is treated like the field being absent (wallets do send it
       // that way).
       session_id?: SessionID;
 
     }
 
   .. ts:def:: SignedTokenEnvelope
 
     interface SignedTokenEnvelope {
 
       // Blind signature made by the merchant.
       blind_sig: TokenIssueBlindSig;
 
     }
 
   .. ts:def:: TokenIssueBlindSig
 
     type TokenIssueBlindSig = RSATokenIssueBlindSig | CSTokenIssueBlindSig;
 
   .. ts:def:: RSATokenIssueBlindSig
 
     interface RSATokenIssueBlindSig {
       cipher: "RSA";
 
       // (blinded) RSA signature
       blinded_rsa_signature: BlindedRsaSignature;
     }
 
   .. ts:def:: CSTokenIssueBlindSig
 
     interface CSTokenIssueBlindSig {
       cipher: "CS";
 
       // Signer chosen bit value, 0 or 1, used
       // in Clause Blind Schnorr to make the
       // ROS problem harder.
       b: Integer;
 
       // Blinded scalar calculated from c_b.
       s: Cs25519Scalar;
 
     }
 
   .. ts:def:: PayWalletData
 
     interface PayWalletData {
       // Index of the selected choice within the ``choices`` array of
       // the contract terms.
       // @since protocol **v21**
       choice_index?: Integer;
 
       // Array of output tokens to be (blindly) signed by the merchant.
       // Output tokens specified in choice indicated by ``choice_index``.
       // @since protocol **v21**
       tokens_evs?: TokenEnvelope[];
 
       // Request for donation receipts to be issued.
       // @since protocol **v21**
       donau?: DonationRequestData;
     }
 
   .. ts:def:: DonationRequestData
 
     interface DonationRequestData {
       // Base URL of the selected Donau
       url: WebURL;
 
       // Year for which the donation receipts are expected.
       // Also determines which keys are used to sign the
       // blinded donation receipts.
       year: Integer;
 
       // Array of blinded donation receipts to sign.
       // Must NOT be empty (if no donation receipts
       // are desired, just leave the entire ``donau``
       // argument blank).
       budikeypairs: BlindedDonationReceiptKeyPair[];
     }
 
   .. ts:def:: CoinPaySig
 
     interface CoinPaySig {
       // Signature by the coin.
       coin_sig: EddsaSignature;
 
       // Public key of the coin being spent.
       coin_pub: EddsaPublicKey;
 
       // Signature made by the denomination public key.
       ub_sig: UnblindedSignature;
 
       // The hash of the denomination public key associated with this coin.
       h_denom: HashCode;
 
       // The amount that is subtracted from this coin with this payment.
       contribution: Amount;
 
       // URL of the exchange this coin was withdrawn from.
       exchange_url: WebURL;
 
       // Signature affirming the posession of the
       // respective private key proving that the payer
       // is old enough. Only provided if the paid contract
       // has an age restriction and the coin is
       // age-restricted.
       minimum_age_sig?: EddsaSignature;
 
       // Age commitment vector of the coin.
       // Only provided if the paid contract
       // has an age restriction and the coin is
       // age-restricted.
       age_commitment?: Edx25519PublicKey[];
 
       // Hash over the agge commitment vector of the coin.
       // Only provided if the paid contract
       // does NOT have an age restriction and the coin is
       // age-restricted.
       h_age_commitment?: AgeCommitmentHash;
     }
 
   .. ts:def:: TokenUseSig
 
     interface TokenUseSig {
 
       // Signature on ``TALER_TokenUseRequestPS`` with the token use key of
       // the token being used in this request.
       token_sig: EddsaSignature;
 
       // Token use public key.
       token_pub: EddsaPublicKey;
 
       // Unblinded signature on ``TALER_TokenIssueRequestPS`` with the token
       // issue public key of the merchant.
       ub_sig: UnblindedSignature;
 
       // Hash of the token issue public key associated with this token.
       h_issue: HashCode;
     }
 
   .. ts:def:: TokenEnvelope
 
     // This type depends on the cipher used to sign token families. This is
     // configured by the merchant and defined for each token family in the
     // contract terms.
     type TokenEnvelope = RSATokenEnvelope | CSTokenEnvelope;
 
   .. ts:def:: RSATokenEnvelope
 
     interface RSATokenEnvelope {
 
       // RSA is used for the blind signature.
       cipher: "RSA";
 
       // Blinded signature of the token's `public EdDSA key <eddsa-token-pub>`.
       rsa_blinded_planchet: BlindedRsaSignature;
 
     }
 
   .. ts:def:: CSTokenEnvelope
 
     interface CSTokenEnvelope {
       // Blind Clause-Schnorr signature scheme is used for the blind signature.
       // See https://taler.net/papers/cs-thesis.pdf for details.
       cipher: "CS";
 
       // Public nonce
       cs_nonce: string;      // Crockford `Base32` encoded
 
       // Two Curve25519 scalars, each representing a blinded challenge
       cs_blinded_c0: string; // Crockford `Base32` encoded
       cs_blinded_c1: string; // Crockford `Base32` encoded
     }
 
   .. ts:def:: PaymentDeniedLegallyResponse
 
     interface PaymentDeniedLegallyResponse {
 
       // Numeric `error code <error-codes>` unique to the condition.
       // Error code, must be either
       // TALER_EC_MERCHANT_POST_ORDERS_ID_PAY_EXCHANGE_LEGALLY_REFUSED
       // or TALER_EC_MERCHANT_POST_ORDERS_ID_PAY_EXCHANGE_TRANSACTION_LIMIT_VIOLATION.
       code: Integer;
 
       // Base URL of the exchanges that denied the payment.
       // This is diagnostic information for the wallet and user.
       // It does not instruct the wallet to refresh or reselect coins.
       exchange_base_urls: WebURL[];
 
     }