taler-docs

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

---

 .. 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.
 
   **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>`.
     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.
 
   :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.)
   :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). 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 ``/batch-deposit`` request.
     Applicable error codes:
 
     * ``MERCHANT_POST_ORDERS_ID_PAY_INSUFFICIENT_FUNDS``:  Exchange reported insufficient
       funds for one of the coins.
 
   :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:`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). In any case, the wallet should refresh
     the deposited coins of the affected exchange and
     may try to pay with coins from another exchange if
     possible (it has such coins and the merchant accepts
     coins from another exchange).
     The body is a `PaymentDeniedLegallyResponse` with
     details about the failure.
     Since protocol **v17**.
   :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 failed in some way.
     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.
     Applicable error codes:
 
     * ``MERCHANT_GENERIC_EXCHANGE_UNEXPECTED_STATUS``
     * ``MERCHANT_GENERIC_EXCHANGE_REPLY_MALFORMED``
 
   :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:: 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.
       pos_confirmation?: string;
 
       // Signed tokens. 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.  The donation tokens will be present
       // at the offset matching the place where a donation receipt
       // was indicated in the outputs array, and of course be skipped
       // if the ``PayWalletData`` did not have a ``donau`` field.
       // @since protocol **v21**
       token_sigs?: SignedTokenEnvelope[];
 
     }
 
   .. 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.
       session_id?: string;
 
     }
 
   .. 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: string;
 
       // 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: string;
 
       // 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_pub: 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
       // TALER_EC_MERCHANT_POST_ORDERS_ID_PAY_EXCHANGE_LEGALLY_REFUSED.
       code: Integer;
 
       // Base URL of the exchanges that denied the payment.
       // The wallet should refresh the coins from these
       // exchanges, but may try to pay with coins from
       // other exchanges.
       exchange_base_urls: string[];
 
     }