opentransact.xml

<?xml version="1.0" encoding="UTF-8"?>
  <?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>

<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
]>

<rfc ipr="trust200902" docName="draft-pelle-opentransact-core-02"
     category="info" >

<?rfc toc="yes"?>
<?rfc sortrefs="yes"?>
<?rfc symrefs="yes" ?>

  <front>
    <title abbrev="opentransact">
      OpenTransact Core
    </title>
    <author initials="P" surname="Braendgaard" fullname="Pelle Braendgaard">
      <organization>PicoMoney Inc</organization>
      <address>
        <email>pelle@picomoney.com</email>
      </address>
    </author>
    <author initials="N" surname="Matake" fullname="Nov Matake">
      <organization>Cerego Japan Inc</organization>
      <address>
        <email>nov@matake.jp</email>
      </address>
    </author>
    <author initials="T" surname="Brown" fullname="Tom Brown">
      <address>
        <email>herestomwiththeweather@gmail.com</email>
      </address>
    </author>
    <author initials="D" surname="Nicol" fullname="David Nicol">
      <organization>TipJar</organization>
      <address>
        <email>davidnicol@gmail.com</email>
      </address>
    </author>

    <date year="2012" month="January" day="10"/>

    <area>General</area>
    <workgroup>OpenTransact</workgroup>
    <keyword>Internet-Draft</keyword>
    <abstract>
      <t>
      This document specifies the OpenTransact standard for requesting and performing transfers of assets over the http protocol.
      </t>
    </abstract>
  </front>

  <middle>


<section anchor="status-of-document" title="Status of Document">

<t>This document is in draft and reflects the current designs from the OpenTransact mailing list.</t>

</section>
<section anchor="introduction" title="Introduction">

<t>The goal is to develop a very simple low level standard for transferring an amount of an asset from one account to another.</t>

<t>Most payment systems and existing standards use the messaging paradigm for historical reasons. OpenTransact specifically rejects the message paradigm and prefers the RESTful (REpresentational State Transfer) resource approach as used on the web with URL&rsquo;s and HTTP at it&rsquo;s core.</t>

<t>We aim to create a new standard from scratch ignoring all legacy systems, while leaving it flexible enough to allow applications built on top of it to deal with legacy systems.</t>

<t>The standard is designed to follow standard RESTful practices and be concise and human readable.</t>

<section anchor="assets" title="Assets">

<t>Within OpenTransact we use the accounting definition of the word &ldquo;Asset&rdquo; to mean anything fungible about which one could make an accounting book entry.</t>

<t>For example:</t>

<t><list style='symbols'>
  <t>money</t>
  <t>shares</t>
  <t>bonds</t>
  <t>mobile phone minutes</t>
  <t>hours of work</t>
  <t>property</t>
  <t>domain names</t>
  <t>tons of sand</t>
  <t>general admission tickets to an event</t>
  <t>et cetera</t>
</list></t>

<section anchor="asset-service" title="Asset Service">

<t>An Asset Service is a service maintained by an organization to manage accounts of one asset. For money and other financial assets the Asset Service would normally be run by a Financial Service Provider of some type. Other types of assets are offered by non-financial services. The regulatory definition of &ldquo;financial&rdquo; is of course out of the scope of this document.</t>

</section>
<section anchor="transaction-url" title="Transaction URL">

<t>Each Asset Service has a unique transaction URL. An informal convention is developing, but is out of the cope of this document. Guidance concerning the form of these URLs with regard to specific details like currency, card type, size, color MAY become available in a future Best Current Practices document.</t>

<t>The service available at the transaction URL MUST follow basic REST practices:</t>

<t><list style='symbols'>
  <t>A transaction URL such as https://paymentsarewe.example.com/prwpoints MUST NOT contain query or fragment part.</t>
  <t>Loading the URL into a normal web browser should present a human readable description of the asset.</t>
  <t>A POST to the URL is used for creating a transaction transferring value.</t>
  <t>A GET to the URL from a normal web browser with specific parameters becomes a payment request that the user can authorize.</t>
  <t>A GET to the URL in a machine readable form such as json returns meta data about the asset and optionally a list of transactions that the current user is allowed to see.</t>
  <t>Each transaction has a unique URL. This SHOULD be formed by appending a unique transaction identifier to the transaction URL, such as https://paymentsarewe.example.com/prwpoints/aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d.</t>
</list></t>

</section>
<section anchor="example-of-asset-services" title="Example of Asset Services">

<t>Lets say it&rsquo;s an imaginary electronic currency asset provider eepay.example.net they only offer one asset type, their currency. So they would only have one transaction url:</t>

<t><list style='symbols'>
  <t>http://eepay.example.net/transactions</t>
</list></t>

<t>If the asset provider offered multiple currencies it should have a url for each currency as they are really separate asset types:</t>

<t><list style='symbols'>
  <t>http://eepay.example.net/transactions/usd</t>
  <t>http://eepay.example.net/transactions/euro</t>
</list></t>

<t>A bank offering OT as an alternative to ACH service could have a tranaction URL for each of the currencies in which it offers checking accounts. The details of interbank settlements are out of the scope of this document.</t>

<t><list style='symbols'>
  <t>http://coolbank.example.com/current</t>
  <t>http://coolbank.example.com/savings</t>
  <t>http://coolbank.example.com/bonds/mortgage</t>
</list></t>

<t>A mutual fund company would have a url for each of their funds.</t>

<t><list style='symbols'>
  <t>http://fidelify.example.com/funds/sp500</t>
  <t>http://fidelify.example.com/funds/emergingmarkets</t>
</list></t>

<t>With relaxation of current regulations on brokerage transactions all going through markets, a broker (rather, a stock market) could implement an OpenTransact API and have a different URL for each symbol.</t>

<t><list style='symbols'>
  <t>http://nyex.example.com/trade/AAPL</t>
  <t>http://nyex.example.com/trade/EBAY</t>
</list></t>

<t>This would ease the barrier to registered securities being used directly as money.</t>

<t>If we let the URL do the describing, there are many different possibilities. This allows support for all manners of asset types.</t>

<t>All the above examples are fungible assets. In general it is best practice that one item of value for one asset is fungible for one another.</t>

<t>For unique items such as domain names, property titles and diamonds that are unique and infungible, we can still create asset urls for each item, but only accept transfer amounts of 1.</t>

<t>All the above examples are fungible assets.</t>

<t>For unique items such as domain names, property titles and diamonds that are unique and infungible, we may define a separate currency for the item representing partial ownership. The legal framework for defining the resulting partnerships and their governance is out of scope of this document.</t>

</section>
<section anchor="derivative-assets" title="Derivative Assets">

<t>A Derivative asset is an asset that is based on the current asset but provides different semantics and business rules.</t>

<t>Examples:</t>

<t><list style='symbols'>
  <t>Reserves/Escrows</t>
  <t>Subscription services providing recurring billing</t>
  <t>Exchanges providing exchange of asset with another asset</t>
</list></t>

<t>It is out of scope to define here exactly how these would work, but the OpenTransact community will build a list of recipes for how to implement these and may publish further drafts outlining specifics in the future.</t>

</section>
</section>
<section anchor="roles" title="Roles">

<t>OpenTransact defines 4 roles:</t>

<t><list style='symbols'>
  <t>Asset provider
  <list style='symbols'>
      <t>The entity providing or issuing the asset</t>
    </list></t>
  <t>Transferer
  <list style='symbols'>
      <t>The entity transfering an amount of the asset</t>
    </list></t>
  <t>Transferee
  <list style='symbols'>
      <t>The entity receiving an amount of the asset</t>
    </list></t>
  <t>3rd party application
  <list style='symbols'>
      <t>An application performing a transfer on behalf of the Transferer</t>
    </list></t>
</list></t>

</section>
<section anchor="transfer" title="Transfer">

<t>We will use the term &ldquo;Transfer&rdquo; as it is more widely applicable than &ldquo;Payment&rdquo;.</t>

<t>A Transfer is legally a transfer in ownership of some amount of the Asset from the Transferer to the Transferee.</t>

<t>Eg. A Payment of $12 from Bob to Alice is a Transfer of $12 with Bob being the Transferer and Alice the Transferee.</t>

</section>
<section anchor="transfer-request" title="Transfer Request">

<t>A Transfer request is when the Transferee requests a transfer of a given amount of an asset from the Transferer.</t>

<t>Eg. Alice sends an invoice to Bob for $12. This is a Transfer Request from Alice to Bob where Alice is the Transferee and Bob the Transferer.</t>

<t>A Transfer Request is simply a specially formatted payment link that takes Bob to Asset Service if followed. The Asset Service shall present the Transfer Request to Bob who can authorize or decline it.</t>

</section>
<section anchor="transfer-authorization" title="Transfer Authorization">

<t>A Transfer Authorization is when  the Transferee or a third party application requests an authorization to transfer of a given amount of an asset from the Transferer.</t>

<t>Eg. Bob wants to hire someone on an online job board to edit a document for $33. The Job Board creates a Transfer Authorization link. Bob follows this link to the Asset Service and authorizes the Job Board to transfer $33 from his account to some one else within a time period.</t>

<t>A Transfer Request is simply a specially formatted payment link that takes Bob to Asset Service if followed. The Asset Service shall present the Transfer Request to Bob who can authorize or decline it. If Bob authorizes it the Asset Service issues an authorization code to the Job Board that they can use to exchange for an OAuth token.</t>

</section>
<section anchor="exchange-transaction" title="Exchange Transaction">

<t>A Transfer is often but not always part of an exchange of value between 2 types of assets. Eg.:</t>

<t><list style='symbols'>
  <t>10 consulting hours exchanged for 1100EUR</t>
  <t>10 USD exchanged for 8 EURO</t>
  <t>0.99 USD exchanged for an mp3 song</t>
</list></t>

<t>There are as many different exchange mechanisms for creating exchanges as there are exchange types.</t>

<t><list style='symbols'>
  <t>Invoicing system</t>
  <t>App Store</t>
  <t>Web shop</t>
  <t>Auction site</t>
  <t>Stock Exchange</t>
</list></t>

<t>It is outside the scope for OpenTransact to define every single type of exchange that is possible. OpenTransact provides a fundamental building block in building such systems. It integrates well with exchange systems that don&rsquo;t yet understand OpenTransact.</t>

<section anchor="exchanged-item-uri" title="Exchanged item URI">

<t>In an Exchange Transaction we can include a url to the exchanged item. This URI could either be a link to the exchanged item itself or the unique URI identifying the transaction itself.</t>

</section>
<section anchor="authorization" title="Authorization">

<t>A useful building block for creating Exchange services is the Transfer Authorization flow.</t>

</section>
</section>
<section anchor="vocabulary" title="Vocabulary">

<t>OpenTransact includes a standard list parameter names used in the GET and POST requests.</t>

<t><list style='symbols'>
  <t><spanx style='emph'>asset</spanx> - Transaction URL</t>
  <t><spanx style='emph'>from</spanx> - Transferer account identifier</t>
  <t><spanx style='emph'>to</spanx> - Transferee account identifier</t>
  <t><spanx style='emph'>amount</spanx> - Amount of asset</t>
  <t><spanx style='emph'>note</spanx> - Textual description of transfer</t>
  <t><spanx style='emph'>for</spanx> - Identifier of exchanged item. This SHOULD be a URI</t>
  <t><spanx style='emph'>redirect_uri</spanx> - URI to redirect User Agent to</t>
  <t><spanx style='emph'>callback_uri</spanx> - URI for performing callback after request</t>
  <t><spanx style='emph'>client_id</spanx> - Identifier of 3rd party application</t>
  <t><spanx style='emph'>expires_in</spanx> - Request that a token expires in given seconds</t>
</list></t>

<t>They are designed to be small and semantically correct. eg</t>

<t><list style='empty'>
  <t>A transfer of 10  USD  from Bob to Alice for consulting.</t>
</list></t>

<t>Would become the following:</t>

<t><list style='symbols'>
  <t>amount=10</t>
  <t>asset=http://pay.me/usd</t>
  <t>from=bob@test.example..com</t>
  <t>to=alice@test.example..com</t>
  <t>note=Consulting on XYZ project</t>
  <t>for=http://myinvoice.test/invoices/123123</t>
</list></t>

</section>
<section anchor="authentication" title="Authentication">

<t>OpenTransact does not define any new authentication mechanisms, but relies on the Asset Provider&rsquo;s existing mechanisms for authenticating the Transferer and  OAuth 2.0 <xref target="I-D.ietf-oauth-v2-bearer"/> for authenticating 3rd party applications on behalf of the Transferer.</t>

</section>
<section anchor="parameter-encoding" title="Parameter encoding">

<t>Since OpenTransact is designed to be simple to implement, the basic parameter encoding is URL form encoding.</t>

<t>Data responses should be in JSON format.</t>

<t>OpenTransact includes a standard for name strings and value ranges for use with the JSON objects returned from a request made to a compliant OT transaction URL.</t>

</section>
<section anchor="extensions" title="Extensions">

<t>OpenTransact is designed to be extensible, either through proprietary extensions, conventions or futher standards.</t>

<t>For example it may be useful to follow the lat/lon convention allowing geotagging of data.</t>

</section>
<section anchor="notational-conventions" title="Notational Conventions">

<t>The key words &lsquo;MUST&rsquo;, &lsquo;MUST NOT&rsquo;, &lsquo;REQUIRED&rsquo;, &lsquo;SHALL&rsquo;, &lsquo;SHALL NOT&rsquo;, &lsquo;SHOULD&rsquo;, &lsquo;SHOULD NOT&rsquo;, &lsquo;RECOMMENDED&rsquo;, &lsquo;MAY&rsquo;, and &lsquo;OPTIONAL&rsquo; in this specification are to be interpreted as described in <xref target="RFC2119"/>.</t>

<t>This specification uses the Augmented Backus-Naur Form (ABNF) notation of <xref target="RFC5234"/>.</t>

<t>Certain security-related terms are to be understood in the sense defined in <xref target="RFC4949"/>. These terms include, but are not limited to, &lsquo;attack&rsquo;, &lsquo;authentication&rsquo;, &lsquo;authorization&rsquo;, &lsquo;certificate&rsquo;, &lsquo;confidentiality&rsquo;, &lsquo;credential&rsquo;, &lsquo;encryption&rsquo;, &lsquo;identity&rsquo;, &lsquo;sign&rsquo;, &lsquo;signature&rsquo;, &lsquo;trust&rsquo;, &lsquo;validate&rsquo;, and &lsquo;verify&rsquo;.</t>

<t>Unless otherwise noted, all the protocol parameter names and values are case sensitive.</t>

</section>
</section>
<section anchor="transfer-request-1" title="Transfer Request">

<t>A Transfer Request consists of a GET to the Asset URL.</t>

<figure anchor="get-usdtobillexamplecomamount10000notemilkredirecturihttpsiteexamplecomcallback-http11host-payme"><artwork><![CDATA[
GET /usd?to=bill@example.com&amount=100.00&note=Milk&redirect_uri=http://site.example.com/callback HTTP/1.1
Host: pay.me
]]></artwork></figure>

<t>We use the following parameters from our common vocabulary. All fields are optional:</t>

<t><list style='symbols'>
  <t><spanx style='emph'>to</spanx> Account identifier of Transferee. If left out it defaults to the 3rd party applications own account on Asset Service or a predefined account as specified when authorizing the access token.</t>
  <t><spanx style='emph'>amount</spanx> Amount as a number with decimal points. Symbols are allowed but SHOULD be ignored. If left out it defaults to the Asset&rsquo;s minimum transfer, 1 or an amount predefined when authorizing the access token.</t>
  <t><spanx style='emph'>note</spanx> Textual description, which can include hash tags. Asset Service may truncate this. No default.</t>
  <t><spanx style='emph'>from</spanx> Account identifier of Transferer. This should normally be left out as it is implied by the authorizer of the Access Token. The Asset Service MUST verify that the Access Token is authorized to transfer from this account. This could be useful for Asset providers charging their customers accounts.</t>
  <t><spanx style='emph'>for</spanx> URI identifying the exchanged item.</t>
  <t><spanx style='emph'>redirect_uri</spanx> URI for redirecting client to afterwards</t>
  <t><spanx style='emph'>callback_uri</spanx> URI for performing a web callback</t>
</list></t>

<t>When a user follows this link, the Asset Service should present the user with a form authorizing the payment.</t>

<t>Note: Client can include OpenID Connect parameters.</t>

<section anchor="response" title="Response">

<t>The user is redirected back to the clients redirect uri with the following url encoded parameters:</t>

<t><list style='symbols'>
  <t><spanx style='emph'>txn_url</spanx> A url identifying the transaction.</t>
</list></t>

<t>Asset provider can include an access_token in the query string of txn_url.</t>

</section>
<section anchor="errors" title="Errors">

<t>Error types use OAuth 2.0&rsquo;s error codes. <xref target="I-D.ietf-oauth-v2"/></t>

</section>
</section>
<section anchor="transfer-authorization-1" title="Transfer Authorization">

<t>A Transfer Authorization consists of a GET to the Asset URL with a client_id.</t>

<figure anchor="get-usdtobillexamplecomamount10000notemilkredirecturihttpsiteexamplecomcallbackclientid1234-http11host-payme"><artwork><![CDATA[
GET /usd?to=bill@example.com&amount=100.00&note=Milk&redirect_uri=http://site.example.com/callback&client_id=1234 HTTP/1.1
Host: pay.me
]]></artwork></figure>

<t>A Transfer Authorization is really a OAuth2 Authorization <xref target="I-D.ietf-oauth-v2"/> with a few extra payment related parameters.</t>

<t>We use the following parameters from our common vocabulary. All fields are optional:</t>

<t><list style='symbols'>
  <t><spanx style='emph'>to</spanx> Account identifier of Transferee. If left out it defaults to the 3rd party applications own account on Asset Service or a predefined account as specified when authorizing the access token.</t>
  <t><spanx style='emph'>amount</spanx> Amount as a number with decimal points. Symbols are allowed but SHOULD be ignored. If left out it defaults to the Asset&rsquo;s minimum transfer, 1 or an amount predefined when authorizing the access token.</t>
  <t><spanx style='emph'>note</spanx> Textual description, which can include hash tags. Asset Service may truncate this. No default.</t>
  <t><spanx style='emph'>from</spanx> Account identifier of Transferer. This should normally be left out as it is implied by the authorizer of the Access Token. The Asset Service MUST verify that the Access Token is authorized to transfer from this account. This could be useful for Asset providers charging their customers accounts.</t>
  <t><spanx style='emph'>for</spanx> URI identifying the exchanged item.</t>
  <t><spanx style='emph'>validity</spanx> A <xref target="ISO.8601.1988"/> <eref target="http://en.wikipedia.org/wiki/ISO_8601#Durations">duration</eref> or <eref target="http://en.wikipedia.org/wiki/ISO_8601#Time_intervals">interval</eref> (see below)</t>
</list></t>

<t>OAuth2 related parameters. See <xref target="I-D.ietf-oauth-v2"/> section 5 for full details</t>

<t><list style='symbols'>
  <t><spanx style='emph'>client_id</spanx> OAuth2 client id</t>
  <t><spanx style='emph'>redirect_uri</spanx> URI for redirecting client to afterwards</t>
  <t><spanx style='emph'>callback_uri</spanx> URI for performing a web callback</t>
  <t><spanx style='emph'>response_type</spanx> token or code REQUIRED</t>
</list></t>

<t>When a user follows this link, the Asset Service should present the user with a form authorizing the payment.</t>

<t>Note: Client can include OpenID Connect parameters.</t>

<section anchor="validity-duration" title="Validity duration">

<t>A client can request a specific validity length of the oauth token.</t>

<t>The asset provider will assign a default expiration of the token if client doesn&rsquo;t specify a validity.</t>

<t>A validity can be request which is either a fixed duration  or a repeating interval.</t>

<t>For a fixed interval the amount SHOULD be guaranteed and reserved for the client.</t>

<t>For a repeating interval the amount SHOULD be guaranteed for the first interval only.</t>

<section anchor="validity-request-parameter" title="Validity Request Parameter">

<t>The validity is requested using A ISO8601 <eref target="http://en.wikipedia.org/wiki/ISO_8601#Durations">duration</eref>,  <eref target="http://en.wikipedia.org/wiki/ISO_8601#Time_intervals">interval</eref> or <eref target="http://en.wikipedia.org/wiki/ISO_8601#Repeating_intervals">repeating interval</eref>.</t>

<t>A duration is written</t>

<figure anchor="p30d-30-dayspt5m-5-minutesp1m14dt3h5m23s-1-month-14-days-3-hours-5-minutes-and-23-seconds"><artwork><![CDATA[
P30D                      # 30 days
PT5M                     # 5 minutes
P1M14DT3H5M23S # 1 month 14 days 3 hours 5 minutes and 23 seconds
]]></artwork></figure>

<t>Intervals are either 2 ISO Dates or an ISO date and a duration separated by the &lsquo;/&rsquo; character:</t>

<figure anchor="t130000z2008-05-11t153000z-the-interval-between-2-datest130000zp1y2m10dt2h30m-the-interval-starting-at-a-date-and-finishing-after-a-durationp1y2m10dt2h30m2008-05-11t153000z-the-interval-starting-with-a-duration-and-finishing-at-a-given-datep1m-the-duration-starting-at-the-time-the-token-was-authorized"><artwork><![CDATA[
2007-03-01T13:00:00Z/2008-05-11T15:30:00Z # The interval between 2 dates
2007-03-01T13:00:00Z/P1Y2M10DT2H30M     # The interval starting at a date and finishing after a duration
P1Y2M10DT2H30M/2008-05-11T15:30:00Z     # The interval starting with a duration and finishing at a given date
P1M                                                             # The duration starting at the time the token was authorized.
]]></artwork></figure>

<t>Repeating intervals by prefix one of the above intervals or durations with the letter &lsquo;R&rsquo; and an optional number specifying the amount of times to repeat:</t>

<figure anchor="rp1m-repeat-once-a-monthr12p1m-repeat-12-times-once-a-monthrp1m2008-05-11t153000z-repeat-monthly-until-a-given-date"><artwork><![CDATA[
RP1M                     # repeat once a month
R12P1M                 # repeat 12 times once a month
RP1M/2008-05-11T15:30:00Z  # repeat monthly until a given date
]]></artwork></figure>

<t>By supporting a single parameter with any of the above durations/intervals/repeated intervals we can support a lot of different kinds of applications:</t>

<t><list style='symbols'>
  <t>Recurring payments (subscriptions) using the Repeated Intervals</t>
  <t>Daily spending limits on tokens using Repeated intervals similar to what debit cards have to day. eg. $300/day</t>
  <t>Request validity of a token using a simple duration</t>
</list></t>

</section>
<section anchor="validity-request-error" title="Validity Request Error">

<t>If a specified interval is not supported by service or user refuses to authorize the interval an <eref target="http://tools.ietf.org/html/draft-ietf-oauth-v2-22#section-4.1.2.1">OAuth2.0 Authorization error response</eref> MUST be returned through redirection with the following error:</t>

<t>error=unsupported_interval</t>

</section>
</section>
<section anchor="response-1" title="Response">

<t>Follows OAuth 2 response depending on response_type requested. <xref target="I-D.ietf-oauth-v2"/></t>

</section>
<section anchor="errors-1" title="Errors">

<t>Error types use OAuth 2.0&rsquo;s error codes. <xref target="I-D.ietf-oauth-v2"/></t>

</section>
</section>
<section anchor="transfer-1" title="Transfer">

<t>A transfer consists of a HTTP POST to the asset url by a 3rd party application on behalf of the Transferer.</t>

<t>The Application MUST have an OAuth 2.0 access token issued as defined in the <xref target="I-D.ietf-oauth-v2"/> section 7.</t>

<t>The asset provider SHOULD support the <xref target="I-D.ietf-oauth-v2-bearer"/> Access Token type and can support other access token such as <xref target="I-D.ietf-oauth-v2-http-mac"/>.</t>

<t>The Transfer MUST be created using HTTPS when using <xref target="I-D.ietf-oauth-v2-bearer"/> and other unsigned access tokens.</t>

<figure anchor="post-usd-http11host-paymeauthorization-bearer-vf9dft4qmttobillexamplecomamount10000notemilk"><artwork><![CDATA[
POST /usd HTTP/1.1
Host: pay.me
Authorization: Bearer vF9dft4qmT

to=bill@example.com&amount=100.00&note=Milk
]]></artwork></figure>

<t>We use the following parameters from our common vocabulary in 1.6. All fields are optional:</t>

<t><list style='symbols'>
  <t><spanx style='emph'>to</spanx> Account identifier of Transferee. If left out it defaults to the 3rd party applications own account on Asset Service or a predefined account as specified when authorizing the access token.</t>
  <t><spanx style='emph'>amount</spanx> Amount as a number with decimal points. Symbols are allowed but SHOULD be ignored. If left out it defaults to the Asset&rsquo;s minimum transfer, 1 or an amount predefined when authorizing the access token.</t>
  <t><spanx style='emph'>note</spanx> Textual description, which can include hash tags. Asset Service may truncate this. No default.</t>
  <t><spanx style='emph'>from</spanx> Account identifier of Transferer. This should normally be left out as it is implied by the authorizer of the Access Token. The Asset Service MUST verify that the Access Token is authorized to transfer from this account. This could be useful for Asset providers charging their customers accounts.</t>
  <t><spanx style='emph'>for</spanx> URI identifying the exchanged item.</t>
</list></t>

<section anchor="response-2" title="Response">

<t>http 201 with Receipt json.</t>

</section>
</section>
<section anchor="receipt" title="Receipt">

<t>The receipt is returned when creating a transaction as well as when accessing a transaction url. It can also be used for creating a transaction list by the asset provider.</t>

<t>The receipt is a JSON object consisting of the following fields:</t>

<t><list style='symbols'>
  <t><spanx style='emph'>txn_url</spanx></t>
  <t><spanx style='emph'>to</spanx></t>
  <t><spanx style='emph'>from</spanx></t>
  <t><spanx style='emph'>amount</spanx></t>
  <t><spanx style='emph'>note</spanx></t>
  <t><spanx style='emph'>for</spanx></t>
  <t><spanx style='emph'>asset_url</spanx></t>
  <t><spanx style='emph'>timestamp</spanx></t>
</list></t>

</section>
<section anchor="asset-meta-data" title="Asset Meta data">

<t>A client can find out information about an asset by accessing the asset url directly with a http Accept header of application/json:</t>

<figure anchor="get-usd-http11host-paymeaccept-applicationjson"><artwork><![CDATA[
GET /usd HTTP/1.1
Host: pay.me
Accept: application/json
]]></artwork></figure>

<t>This returns a json hash of meta information about the asset.</t>

<t>The minimum required data would be:</t>

<t><list style='symbols'>
  <t>name - Short name of asset</t>
</list></t>

<t>The minimal asset meta data is:</t>

<figure anchor="namepay-me"><artwork><![CDATA[
{
  "name":"Pay Me"
}
]]></artwork></figure>

<t>Further OpenTransact specific parameters could be:</t>

<t><list style='symbols'>
  <t>default_amount - The default amount transfered if an amount is not specified in a transfer</t>
  <t>provider_uri - The provider of the asset&rsquo;s home page</t>
  <t>description - Short description</t>
  <t>logo_uri - Image url for Assets logo</t>
  <t>unit - ISO currency unit of asset if monetary or other such as (minute, gram, point etc)</t>
  <t>derivatives - a list of derivative assets supported by this server (see below)</t>
</list></t>

<t>Example:</t>

<figure anchor="namepay-medefaultamount10providerurihttppaysamplecomlogourihttppaysamplecomlogopngunitusdderivatives-reservehttppaysamplecomreservessubscriptionhttppaysamplecomsubscriptionsexchangehttppaysamplecomexchange"><artwork><![CDATA[
{
  "name":"Pay Me",
  "default_amount":1.0,
  "provider_uri":"http://pay.sample.com",
  "logo_uri":"http://pay.sample.com/logo.png",
  "unit":"USD",
  "derivatives": [
    {"reserve":"http:/pay.sample.com/reserves"},
    {"subscription":"http:/pay.sample.com/subscriptions"},
    {"exchange":"http:/pay.sample.com/exchange"}
  ]
}
]]></artwork></figure>

<t>Asset services can provide further information more specific to their particular asset type.</t>

<t>If an OAuth Access Token is provided the Asset Service should provide information related to the capabilities of the token.</t>

<t><list style='symbols'>
  <t>balance - balance of account</t>
  <t>available_balance - available balance of account</t>
</list></t>

<t>For tokens obtained through a Transfer Authentication this should reflect the remaining balance of the authorized amount.</t>

<section anchor="transaction-history" title="Transaction history">

<t>If tokens scope allows access to accounts transaction history a url to the transaction history or a transaction history SHOULD be included here:</t>

<t><list style='symbols'>
  <t>transactions_uri - URI to list of transactions</t>
  <t>transactions - array of receipts</t>
</list></t>

</section>
<section anchor="derivative-assets-1" title="Derivative assets">

<t>If an asset has derivative assets they SHOULD be listed in the optional derivatives list:</t>

<figure anchor="name-pay-mederivatives-reservehttppaysamplecomreservessubscriptionhttppaysamplecomsubscriptionsexchangehttppaysamplecomexchange"><artwork><![CDATA[
{
  "name": "Pay Me",
  "derivatives": [
    {"reserve":"http:/pay.sample.com/reserves"},
    {"subscription":"http:/pay.sample.com/subscriptions"},
    {"exchange":"http:/pay.sample.com/exchange"}
  ]
}
]]></artwork></figure>

<t>The OpenTransact group will maintain a list of recipes that may be further standardized.</t>

</section>
</section>
<section anchor="security-considerations" title="Security Considerations">

<t>The security of OpenTransact is achieved by it&rsquo;s use of <xref target="I-D.ietf-oauth-v2"/>. Please see its <eref target="http://tools.ietf.org/html/draft-ietf-oauth-v2-22#section-10">security discussion</eref> and a more thorough discussion in <xref target="I-D.ietf-oauth-v2-threatmodel"/>.</t>

</section>
</middle>

<back>

  <references title='Normative References'>

<t>

<reference anchor='RFC2119'>

<front>
<title abbrev='RFC Key Words'>Key words for use in RFCs to Indicate Requirement Levels</title>
<author initials='S.' surname='Bradner' fullname='Scott Bradner'>
<organization>Harvard University</organization>
<address>
<postal>
<street>1350 Mass. Ave.</street>
<street>Cambridge</street>
<street>MA 02138</street></postal>
<phone>- +1 617 495 3864</phone>
<email>sob@harvard.edu</email></address></author>
<date year='1997' month='March' />
<area>General</area>
<keyword>keyword</keyword>
<abstract>
<t>
   In many standards track documents several words are used to signify
   the requirements in the specification.  These words are often
   capitalized.  This document defines these words as they should be
   interpreted in IETF documents.  Authors who follow these guidelines
   should incorporate this phrase near the beginning of their document:

<list>
<t>
      The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
      NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
      "OPTIONAL" in this document are to be interpreted as described in
      RFC 2119.
</t></list></t>
<t>
   Note that the force of these words is modified by the requirement
   level of the document in which they are used.
</t></abstract></front>

<seriesInfo name='BCP' value='14' />
<seriesInfo name='RFC' value='2119' />
<format type='TXT' octets='4723' target='http://www.rfc-editor.org/rfc/rfc2119.txt' />
<format type='HTML' octets='17491' target='http://xml.resource.org/public/rfc/html/rfc2119.html' />
<format type='XML' octets='5777' target='http://xml.resource.org/public/rfc/xml/rfc2119.xml' />
</reference>



<reference anchor='RFC2616'>

<front>
<title abbrev='HTTP/1.1'>Hypertext Transfer Protocol -- HTTP/1.1</title>
<author initials='R.' surname='Fielding' fullname='Roy T. Fielding'>
<organization abbrev='UC Irvine'>Department of Information and Computer Science</organization>
<address>
<postal>
<street>University of California, Irvine</street>
<city>Irvine</city>
<region>CA</region>
<code>92697-3425</code></postal>
<facsimile>+1(949)824-1715</facsimile>
<email>fielding@ics.uci.edu</email></address></author>
<author initials='J.' surname='Gettys' fullname='James Gettys'>
<organization abbrev='Compaq/W3C'>World Wide Web Consortium</organization>
<address>
<postal>
<street>MIT Laboratory for Computer Science, NE43-356</street>
<street>545 Technology Square</street>
<city>Cambridge</city>
<region>MA</region>
<code>02139</code></postal>
<facsimile>+1(617)258-8682</facsimile>
<email>jg@w3.org</email></address></author>
<author initials='J.' surname='Mogul' fullname='Jeffrey C. Mogul'>
<organization abbrev='Compaq'>Compaq Computer Corporation</organization>
<address>
<postal>
<street>Western Research Laboratory</street>
<street>250 University Avenue</street>
<city>Palo Alto</city>
<region>CA</region>
<code>94305</code></postal>
<email>mogul@wrl.dec.com</email></address></author>
<author initials='H.' surname='Frystyk' fullname='Henrik Frystyk Nielsen'>
<organization abbrev='W3C/MIT'>World Wide Web Consortium</organization>
<address>
<postal>
<street>MIT Laboratory for Computer Science, NE43-356</street>
<street>545 Technology Square</street>
<city>Cambridge</city>
<region>MA</region>
<code>02139</code></postal>
<facsimile>+1(617)258-8682</facsimile>
<email>frystyk@w3.org</email></address></author>
<author initials='L.' surname='Masinter' fullname='Larry Masinter'>
<organization abbrev='Xerox'>Xerox Corporation</organization>
<address>
<postal>
<street>MIT Laboratory for Computer Science, NE43-356</street>
<street>3333 Coyote Hill Road</street>
<city>Palo Alto</city>
<region>CA</region>
<code>94034</code></postal>
<email>masinter@parc.xerox.com</email></address></author>
<author initials='P.' surname='Leach' fullname='Paul J. Leach'>
<organization abbrev='Microsoft'>Microsoft Corporation</organization>
<address>
<postal>
<street>1 Microsoft Way</street>
<city>Redmond</city>
<region>WA</region>
<code>98052</code></postal>
<email>paulle@microsoft.com</email></address></author>
<author initials='T.' surname='Berners-Lee' fullname='Tim Berners-Lee'>
<organization abbrev='W3C/MIT'>World Wide Web Consortium</organization>
<address>
<postal>
<street>MIT Laboratory for Computer Science, NE43-356</street>
<street>545 Technology Square</street>
<city>Cambridge</city>
<region>MA</region>
<code>02139</code></postal>
<facsimile>+1(617)258-8682</facsimile>
<email>timbl@w3.org</email></address></author>
<date year='1999' month='June' />
<abstract>
<t>
   The Hypertext Transfer Protocol (HTTP) is an application-level
   protocol for distributed, collaborative, hypermedia information
   systems. It is a generic, stateless, protocol which can be used for
   many tasks beyond its use for hypertext, such as name servers and
   distributed object management systems, through extension of its
   request methods, error codes and headers . A feature of HTTP is
   the typing and negotiation of data representation, allowing systems
   to be built independently of the data being transferred.
</t>
<t>
   HTTP has been in use by the World-Wide Web global information
   initiative since 1990. This specification defines the protocol
   referred to as "HTTP/1.1", and is an update to RFC 2068 .
</t></abstract></front>

<seriesInfo name='RFC' value='2616' />
<format type='TXT' octets='422317' target='http://www.rfc-editor.org/rfc/rfc2616.txt' />
<format type='PS' octets='5529857' target='http://www.rfc-editor.org/rfc/rfc2616.ps' />
<format type='PDF' octets='550558' target='http://www.rfc-editor.org/rfc/rfc2616.pdf' />
<format type='HTML' octets='636125' target='http://xml.resource.org/public/rfc/html/rfc2616.html' />
<format type='XML' octets='493420' target='http://xml.resource.org/public/rfc/xml/rfc2616.xml' />
</reference>



<reference anchor='RFC3339'>

<front>
<title>Date and Time on the Internet: Timestamps</title>
<author initials='G.' surname='Klyne' fullname='Graham Klyne' role='editor'>
<organization>Clearswift Corporation</organization>
<address>
<postal>
<street>1310 Waterside</street>
<street>Arlington Business Park</street>
<city>Theale</city>
<region>Reading</region>
<code>RG7 4SA</code>
<country>UK</country></postal>
<phone>+44 11 8903 8903</phone>
<facsimile>+44 11 8903 9000</facsimile>
<email>GK@ACM.ORG</email></address></author>
<author initials='C.' surname='Newman' fullname='Chris Newman'>
<organization>Sun Microsystems</organization>
<address>
<postal>
<street>1050 Lakes Drive, Suite 250</street>
<city>West Covina</city>
<region>CA</region>
<code>91790</code>
<country>USA</country></postal>
<email>chris.newman@sun.com</email></address></author>
<date year='2002' month='July' />
<abstract>
<t>
   This document defines a date and time format for use in Internet
   protocols that is a profile of the ISO 8601 standard for
   representation of dates and times using the Gregorian calendar.
     </t></abstract></front>

<seriesInfo name='RFC' value='3339' />
<format type='TXT' octets='35064' target='http://www.rfc-editor.org/rfc/rfc3339.txt' />
<format type='HTML' octets='61277' target='http://xml.resource.org/public/rfc/html/rfc3339.html' />
<format type='XML' octets='37259' target='http://xml.resource.org/public/rfc/xml/rfc3339.xml' />
</reference>



<reference anchor='RFC4627'>

<front>
<title>The application/json Media Type for JavaScript Object Notation (JSON)</title>
<author initials='D.' surname='Crockford' fullname='D. Crockford'>
<organization /></author>
<date year='2006' month='July' />
<abstract>
<t>JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format.  It was derived from the ECMAScript Programming Language Standard.  JSON defines a small set of formatting rules for the portable representation of structured data.  This memo provides information for the Internet community.</t></abstract></front>

<seriesInfo name='RFC' value='4627' />
<format type='TXT' octets='16319' target='http://www.rfc-editor.org/rfc/rfc4627.txt' />
</reference>



<reference anchor='RFC5234'>

<front>
<title>Augmented BNF for Syntax Specifications: ABNF</title>
<author initials='D.' surname='Crocker' fullname='D. Crocker'>
<organization /></author>
<author initials='P.' surname='Overell' fullname='P. Overell'>
<organization /></author>
<date year='2008' month='January' />
<abstract>
<t>Internet technical specifications often need to define a formal syntax.  Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications.  The current specification documents ABNF.  It balances compactness and simplicity with reasonable representational power.  The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges.  This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications. [STANDARDS-TRACK]</t></abstract></front>

<seriesInfo name='STD' value='68' />
<seriesInfo name='RFC' value='5234' />
<format type='TXT' octets='26359' target='http://www.rfc-editor.org/rfc/rfc5234.txt' />
</reference>



<reference anchor='RFC4949'>

<front>
<title>Internet Security Glossary, Version 2</title>
<author initials='R.' surname='Shirey' fullname='R. Shirey'>
<organization /></author>
<date year='2007' month='August' />
<abstract>
<t>This Glossary provides definitions, abbreviations, and explanations of terminology for information system security.  The 334 pages of entries offer recommendations to improve the comprehensibility of written material that is generated in the Internet Standards Process (RFC 2026).  The recommendations follow the principles that such writing should (a) use the same term or definition whenever the same concept is mentioned; (b) use terms in their plainest, dictionary sense; (c) use terms that are already well-established in open publications; and (d) avoid terms that either favor a particular vendor or favor a particular technology or mechanism over other, competing techniques that already exist or could be developed.  This memo provides information for the Internet community.</t></abstract></front>

<seriesInfo name='RFC' value='4949' />
<format type='TXT' octets='867626' target='http://www.rfc-editor.org/rfc/rfc4949.txt' />
</reference>
</t>

<?rfc include='http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-oauth-v2-22.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-oauth-v2-bearer-15.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-oauth-v2-http-mac-00' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-oauth-v2-threatmodel-01.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml2/_reference.ISO.8601.1988.xml' ?>


  </references>

</back>
</rfc>