The Merchant JSON API
The Merchant API serves the protocol interactions between a customer and a
merchant. The protocol allows the customer and the merchant to agree upon a
contract and for the customer to spend coins according to the contract at the
merchant. It should be noted that the interactions are strictly one way: The
customer *always* initiates the requests by contacting the merchant. It is also
assumed that the customer knows the merchant's public key.
The protocol allows for three different type of interactions. In the first type
of interaction, which we refer to as *direct deposit*, an interested customer
asks the merchant to provide a ``contract`` for the merchant's services or
products. Details about the services or products and the merchant's payment
information are provided in the contract. The customer then agrees upon one of
these contracts by giving the the merchant a ``deposit permission``. The
merchant then submits this deposit permission at the mint for verification.
Upon successful verification, the merchant delivers the promised services or
The second type of interaction, *incremental deposit*, allows the merchant to
charge the customer incrementally. This is useful for subscription based
e-commerce systems. Examples for such systems are app stores and news websites.
The idea here is that the merchant will be assured that he will receive a
certain amount of money from the transaction, and then he can charge small
amounts over the assured amount without contacting the mint. In these
interactions, the customer asks merchant to make an ``offer`` for the
subscription by specifying the maximum amount the merchant may charge during the
interaction. The customer conveys his acceptance of the offer by sending a
``lock permission`` to the merchant. The merchant asks the mint to verify the
lock permission and if verified successfully, the customer then obtains a
contract from the merchant and the first type interaction follows. The customer
can then obtain further contracts until the maximum amount made in the offer is
The thrid type of interactions allows probablistic spending. `To be done.`
The following are the API made available by the merchant:
.. http:GET:: /contract
.. http:POST:: /contract
Ask the merchant to prepare a contract. The request parameters are specific
to the merchant's implementation, however, they are recommended to contain
information required for the merchant to identify which product or service
the customer is interested int.
:status 200 OK: The request was successful.
The merchant responds with a JSON object containing the following fields:
* `transaction_id`: A string representing the transaction identifier.
* `expiry`: The timestamp after which this contract expires.
* `amount`: Price of the contract as a Denomination object.
* `description`: The contract description as string.
* `H_wire`: The hash of a JSON object containing the merchant's payment
information. See :ref:`wireformats`.
* `msig`: Signature of the merchant over the fields `m`, `t`, `f`, `a`, `H_wire`.
:status 400: Request not understood.
:status 404: No products or services given in the request were found.
It is also possible to receive other error status codes depending on the
.. http:GET:: /deposit
Send a ``deposit-permission`` JSON object to the merchant. The object should
contain the following fields:
* `coin_pub`: The coin's public key.
* `mint_pub`: The public key of the mint from where the coin is obtained.
* `denom_pub`: Denomination key with which the coin is signed
* `ubsig`: Mint's unblinded signature of the coin
* `type`: the string constant `"DIRECT_DEPOSIT"` or `"INCREMENTAL_DEPOSIT"`
respectively for direct deposit or incremental deposit type of interaction.
* `transaction_id`: The transaction identifier obtained from the contract.
* `amount`: The amount to be deposited as a Denomination object. Its value should
be less than or equal to the coin's face value. Additionally, for direct
deposit type of interactions, this should be equal to the amount stated in
* `merchant_pub`: The public key of the merchant.
* `H_a`: The hash of the contract.
* `H_wire`: The hash of the merchant's payment information.
* `csig`: The signature with the coin's private key over the parameters
`type`, `m`, `f`, `M`, `H_a` and, `H_wire`.
:status 200 OK: The deposit permission is successful.
It is left upto the merchant's implementation to carry over the process of
fulfilling the agreed contract `a` from here. For example, for services or
products which can be served through HTTP, this response could contain them.
:status 400: Request not understood.
:status 404: The merchant does not entertain this type of interaction. Try
:status 403: The request doesn't comply to the contract provided. The
request should not be repeated.
:status 403: The deposit operation has failed because the coin has previously
been deposited or it has been already refreshed; the request
should not be repeated again. The response body contains the
failure response objects from the :ref:`Mint API deposit
Other interactions tbd..