params.json

{"name":"WebWalletAPI","tagline":"A digital wallet specification for the Web","body":"#The WebWallet API <span>&nbsp;&nbsp;(working draft)</span>\r\n###A digital wallet specification for the Web.\r\n\r\n## Abstract\r\nThis specification defines an application programming interface (API) that aims to enable web applications to carry out electronic commerce transactions using WebWallets.\r\n\r\n## What is a WebWallet?\r\nA WebWallet is a rechargeable digital wallet that can hold electronic money and credentials to make payments on the Web.\r\n\r\n#### Features\r\n+ **No deposits but recharges**  \r\nA WebWallet is not a deposit account, but a rechargeable digital wallet. Funds are not added as deposits but as prepaid recharges, which represent a temporary intermediation between online buyers and sellers.\r\n\r\n+ **No withdrawals or redemption**  \r\nA WebWallet recharge is interpreted as a purchase intention, so it cannot be reversed. The funds added to a WebWallet cannot be withdrawn or redeemed for cash, so they must be fully spent at some point.\r\n\r\n+ **No currency exchange**  \r\nA WebWallet can be recharged in any currency supported by the involved parties and the applicable regulations. However, a WebWallet recharge is not a currency exchange operation by itself.\r\n\r\n\r\n## WebWallet Transactions\r\nWebWallet transactions are bilateral, token-based and expire if not completed within a certain time interval.\r\n\r\n+ **Bilateral**  \r\n  - WebWallet transactions are carried out in two major stages: creation and completion.  \r\n  - Each of the two parties involved must exclusively carry out one of the two stages.  \r\n  - A transaction initiated by one party can only be completed by the other party.  \r\n\r\n+ **Token-based**  \r\n  - WebWallet transactions are initiated by requesting a transaction token to a WebWallet provider.  \r\n  - Transaction tokens are pointers to information such as the transaction type, amount and currency.  \r\n  - Tokens must be handed over by the initiator party for the other party to complete the transaction.  \r\n\r\n+ **Expirable**  \r\n  - Transaction tokens must have an expiration date and receive a timestamp when they are created.  \r\n  - Transactions must be completed by the party that did not create the token before the expiration date.  \r\n  - If a transaction token expires, the initiator party will need to request a new token and start over.  \r\n\r\n\r\n## WebWallet Modules\r\nThe WebWallet specification is divided into modules that resemble the different pockets of a physical wallet intended for holding paper money, identification documents, cards and receipts, among others.\r\n\r\n+ **Electronic Money**  \r\nThe main goal of a WebWallet is to be as easy to use as a physical wallet: put some money on it, and take some money out to make payments. However, since physical money cannot be literally put into a digital wallet, the funds added to a WebWallet must be reflected as an online balance.  \r\n  \r\n  _\"Electronic money is a digital equivalent of cash, stored on an electronic device or remotely at a server.\"_ [_(European Comission on E-money)_](http://ec.europa.eu/internal_market/payments/emoney/index_en.htm).\r\n\r\n  The purpose of the Electronic Money module is to resemble the pocket of a physical wallet that is used for holding paper money, by implementing a digital stored value system whose balance reflects the available funds of a WebWallet that were added through prepaid recharges.\r\n\r\n\r\n## API Overview\r\nThe WebWallet API defines how to expose and interact with WebWallets in order to request and carry out electronic commerce transactions.\r\n\r\n+ **Exposure through URIs**  \r\nEach WebWallet is represented as a URI:  \r\n\r\n    ```\r\n    wallet.example.com/:walletID\r\n    ```\r\n\r\n+ **Secure API calls using tokens**  \r\nA transaction token must be requested in order to obtain authorization to make API calls:\r\n\r\n    ```\r\n    POST /:walletID/transactions HTTP/1.1\r\n    Host: wallet.example.com\r\n    \r\n    options=transaction-options\r\n    ```\r\n\r\n+ **Transactions through HTTP methods**  \r\nTransactions are carried out using HTTP methods signed with a valid transaction token.\r\n\r\n    **Checking the balance:**\r\n    ```\r\n    GET /:walletID/balance HTTP/1.1\r\n        ?token=transaction-token\r\n    Host: wallet.example.com\r\n    ```\r\n\r\n    **Adding funds:**\r\n    ```\r\n    POST /:walletID/funds HTTP/1.1\r\n    Host: wallet.example.com\r\n    \r\n    token=transaction-token\r\n    ```\r\n    \r\n    **Sending/Requesting a payment:**\r\n    ```\r\n    POST /:walletID/payments HTTP/1.1\r\n    Host: wallet.example.com\r\n    \r\n    token=transaction-token\r\n    ```\r\n\r\n## WebWallet Transaction Flow\r\n\r\n#### Payments\r\nWebWallet payments come in two flavors: user initiated and merchant initiated.\r\n\r\n+ **User initiated: merchant charges**  \r\n  When a user initiates a payment transaction, the merchant has to complete it by charging the payment:  \r\n\r\n  **1.** The user creates a transaction by requesting a transaction token with the payment information.  \r\n    ```\r\n    POST /:userWalletID/transactions HTTP/1.1\r\n    Host: wallet.example.com\r\n    \r\n    options=transaction-options\r\n    ```  \r\n  **2.** The user passes the transaction token to the merchant as an authorization to request the payment.  \r\n    ```\r\n    POST /:merchantWalletID/payments HTTP/1.1\r\n    Host: wallet.example.com\r\n    \r\n    token=transaction-token\r\n    ```  \r\n  **3.** The merchant completes the transaction by posting the payment request using the transaction token.  \r\n    ```\r\n    POST /:userWalletID/payments HTTP/1.1\r\n    Host: wallet.example.com\r\n    \r\n    token=transaction-token\r\n    ```  \r\n  \r\n  By creating and handing over a payment transaction token to a merchant, a user authorizes the merchant to charge the payment to the user's wallet. This is similar to direct debit and credit card charges that are authorized by subscribing recurring payments, swiping a card or filling an online form with its details.\r\n\r\n+ **Merchant initiated: user pays**  \r\n  When a merchant initiates a payment transaction, the user has to complete it by sending the payment:  \r\n\r\n  **1.** The merchant creates a transaction by requesting a transaction token with the payment information.  \r\n    ```\r\n    POST /:merchantWalletID/transactions HTTP/1.1\r\n    Host: wallet.example.com\r\n    \r\n    options=transaction-options\r\n    ```  \r\n  **2.** The merchant passes the transaction token to the user as a request or demand to make a payment.  \r\n    ```\r\n    POST /:userWalletID/payments HTTP/1.1\r\n    Host: wallet.example.com\r\n    \r\n    token=transaction-token\r\n    ```  \r\n  **3.** The user completes the transaction by posting the payment using the transaction token.  \r\n    ```\r\n    POST /:merchantWalletID/payments HTTP/1.1\r\n    Host: wallet.example.com\r\n    \r\n    token=transaction-token\r\n    ```  \r\n\r\n  By creating and handing over a payment transaction token to a user, a merchant requests or demands the user to send the payment to the merchant's wallet. This is similar to cash transactions in which a merchant communicates the payment ammount (e.g. invoice) and waits for the user to hand over the money.\r\n","google":"","note":"Don't delete this file! It's used internally to help with page regeneration."}