Proposal: Virtual Currency API

[Sha-Mayn Teh (郑韶敏)]

Hi,

A few of us from the Google OpenSocial team have been working with 51.com in China on a proposal for payments/virtual currency, and we'd like to get your feedback. The goal is to allow app developers to develop apps using virtual currency and deploy their apps on different containers. The container handles the actual transfer of money from the user (via cash, credit cards, etc) into the fake currency, and apps can charge the user for virtual items, advanced features or VIP status. Two of the biggest social networks in China, Xiaonei and 51.com, have implemented REST-like APIs on their own (non-OpenSocial) platforms, and what we're proposing is an OpenSocial JavaScript API for them to use.

Our proposal (with link to a simple prototype) can be found here: http://docs.google.com/Doc?id=dfjcf7w4_10ddst9xd9

We have a simple demo: http://www.unickway.org.cn:9002/gadgets/files/container/sample-payment.html
with sample code for the app and container: http://docs.google.com/Doc?id=dfjcf7w4_10ddst9xd9&hl=en#Demo_And_Code

Any feedback on our proposal will be appreciated, but the end goal would be: a single unified proposal for an OpenSocial REST/RPC API and JavaScript API for payments.

I know there are some other proposals/thoughts out there, including Netlog's credits extension (at http://en.netlog.com/go/developer/documentation/article=opensocialcreditsextension), so feel free to jump in!

-- sha-mayn

[Chris Chabot]

Proposal looks great to me, hope we can have a productive discussion here, would be *very* exciting to have a standard payment API and have it live right away on 2 large social network sites!

Small suggestion btw: the feature xml linked refers to 'payment-processer.js' but the javascript file seems to be called 'pay-counter.js'.

   -- Chris

[Scott Seely]

Thanks for all the hard work you put into this! I know our dev community will love this. We were asked to tackle this specific problem several times back in November at the 1 year b-day party. It’s good to see this so far along already. The proposal is put together pretty well.

 

I do have some comments on places to make the spec better as well as a few questions.

 

1.       The phrase “The payment is committed but not executed.” is confusing. The user actually ‘approves’ or ‘denies’ a request for payment. I didn’t resolve my own confusion until I studied the workflow diagram. I’d suggest that commit gets changed to approve.

2.       APP_LOGIC_ERROR or APPLICATION_LOGIC_ERROR. One of these is a typo (I think the spec means to use APP_LOGIC_ERROR)

3.       The init handler seems like a bit of overkill. I think the JS developers will be used to XHR and our own response code where Open|Commit|Cancel|Close can be communicated via a state in the object passed to the callback. This is the model chosen by Netlog, and seems to be good enough (http://en.netlog.com/go/developer/documentation/article=opensocialcreditsextension) . Further, one may not care about Open | Close, only Commit/Cancel. As a result, I imagine that many impls would pass null for the current proposal. Yes—I know that the Netlog mechanism rides on top of makeRequest. This even seems to be suggested by the workflow diagram with the ‘payCallback’ at step 20.

4.       The workflow diagram should include where close and cancel would be triggered in the flow.

5.       The spec should indicate the format of items being sent from the containeràapp server. Otherwise, it will be difficult for other containers to implement compatible versions.

6.       Lots of references to a SIGNED request. The spec suggests RSA-SHA1. Why not HMAC-SHA1 since HMAC-SHA1 is used by OAuth?

7.       Do we need to require SSL between the container and the app server? That is, can a man in the middle do something to the sent data to change the outcome? Right now, we aren’t signing the request body, so I assume that a MITM could change the outcome.

8.       Can the RequestParameters.AMOUNT be expressed as a float? What type of precision is expected?

9.       Object model: do we want to continue to use the Parameters model or should this be designed more like what we see with the Lightweight JS API? Instead of a map of params, I’d rather be able to submit an object that looked like this:

{amount:"20", message:"You want fries with that?", userdefParam1:"SuperSize"}

Or, is the map preferred?

10.   Timestamp info doesn’t specify how to communicate the info. I think we should consider using UTC.

11.   It seems a goal here is to only allow for payment for applications that have external development servers. Is this intentional? The current design prohibits two friends from exchanging a gift where the presence of the gift could be stored in the recipients appdata. I don’t have an opinion yet on whether this scenario is valuable, I just noticed it appears to be impossible with the proposal.

[Sha-Mayn Teh (郑韶敏)]

Thanks for the speedy feedback, Scott!!! A few of us discussed it and your comments are really valuable :)

On Fri, Feb 13, 2009 at 5:28 AM, Scott Seely <sSe...@myspace.com> wrote:

Thanks for all the hard work you put into this! I know our dev community will love this. We were asked to tackle this specific problem several times back in November at the 1 year b-day party. It's good to see this so far along already. The proposal is put together pretty well.

 

I do have some comments on places to make the spec better as well as a few questions.

 

1.       The phrase "The payment is committed but not executed." is confusing. The user actually 'approves' or 'denies' a request for payment. I didn't resolve my own confusion until I studied the workflow diagram. I'd suggest that commit gets changed to approve.

Yes, "commit" is confusing. Approve is better, but what about "submit"? Approved can imply that the payment has been fully approved by the container, app backend etc while submit sounds more like a user action.

2.       APP_LOGIC_ERROR or APPLICATION_LOGIC_ERROR. One of these is a typo (I think the spec means to use APP_LOGIC_ERROR)

Thanks for catching this! Fixed to use APP_LOGIC_ERROR.
 

3.       The init handler seems like a bit of overkill. I think the JS developers will be used to XHR and our own response code where Open|Commit|Cancel|Close can be communicated via a state in the object passed to the callback. This is the model chosen by Netlog, and seems to be good enough (http://en.netlog.com/go/developer/documentation/article=opensocialcreditsextension) . Further, one may not care about Open | Close, only Commit/Cancel. As a result, I imagine that many impls would pass null for the current proposal. Yes—I know that the Netlog mechanism rides on top of makeRequest. This even seems to be suggested by the workflow diagram with the 'payCallback' at step 20.

I think it's a bit different from netlog - the idea here is to have the main payment UI flow on the container side controlled by payment-processor.js, with each action customizable by the container. payment-processor.js will be in shindig and won't be changed by most containers, instead they will implement the event handlers to customize the payment UI and actions.
We can make open/close optional, but it's nice to have if the container wants to customize the whole process.

4.       The workflow diagram should include where close and cancel would be triggered in the flow.

 Good point, will fix that.

5.       The spec should indicate the format of items being sent from the containeràapp server. Otherwise, it will be difficult for other containers to implement compatible versions.

Yes, we touched on this at the end of the interfaces section but it's not clear.  Added a note in the doc.

6.       Lots of references to a SIGNED request. The spec suggests RSA-SHA1. Why not HMAC-SHA1 since HMAC-SHA1 is used by OAuth?

Good point, both are supported by OAuth, now both are mentioned in the spec.

7.       Do we need to require SSL between the container and the app server? That is, can a man in the middle do something to the sent data to change the outcome? Right now, we aren't signing the request body, so I assume that a MITM could change the outcome.

A MITM attack is certainly possible. We could either use SSL if the app server supports it, or else sign the requests (HMAC-SHA1 or RSA-SHA1).

8.       Can the RequestParameters.AMOUNT be expressed as a float? What type of precision is expected?

I think this can left to the container to decide. Some containers are using objects as currency ("Xiaonei beans") so integers make sense, while others use coins or currency where float would be appropriate.
We could add a handler for the containers to implement to do a regex/type check. In paymentprocessor,js, we currently check that the amount is a positive javascript number.

9.       Object model: do we want to continue to use the Parameters model or should this be designed more like what we see with the Lightweight JS API? Instead of a map of params, I'd rather be able to submit an object that looked like this:

{amount:"20", message:"You want fries with that?", userdefParam1:"SuperSize"}

Or, is the map preferred?

Good suggestion - I'm open to feedback on this since I haven't been in any discussions about the Lightweight JS API.

10.   Timestamp info doesn't specify how to communicate the info. I think we should consider using UTC.

Yes, we should use UTC milliseconds. Updated the spec.

11.   It seems a goal here is to only allow for payment for applications that have external development servers. Is this intentional? The current design prohibits two friends from exchanging a gift where the presence of the gift could be stored in the recipients appdata. I don't have an opinion yet on whether this scenario is valuable, I just noticed it appears to be impossible with the proposal.

Good point, we should definitely consider that case. Actually, the reference implementation allows the app to pass a null or empty checkout url, which could be used to indicate that they don't have external servers. Added a note in the doc to expand on this.

thanks!
-- sha-mayn

[Dan Peterson]

Good point, we should definitely consider that case. Actually, the reference implementation allows the app to pass a null or empty checkout url, which could be used to indicate that they don't have external servers. Added a note in the doc to expand on this.

Thanks for putting so much detail into the initial design proposal. 

To Scott's point, it does seem like it would be awkward for the payment API to necessarily preclude usage of appdata for storing gifts. 

-Dan

thanks!
-- sha-mayn

 

 

From: opensocial-an...@googlegroups.com [mailto:opensocial-an...@googlegroups.com] On Behalf Of Chris Chabot
Sent: Thursday, February 12, 2009 7:45 AM
To: Sha-Mayn Teh (郑韶敏)
Cc: opensocial-an...@googlegroups.com; Jian Cai ☑; Yizi Wu (吴伊自)
Subject: [opensocial-and-gadgets-spec] Re: Proposal: Virtual Currency API

 

Proposal looks great to me, hope we can have a productive discussion here, would be *very* exciting to have a standard payment API and have it live right away on 2 large social network sites!

Small suggestion btw: the feature xml linked refers to 'payment-processer.js' but the javascript file seems to be called 'pay-counter.js'.

   -- Chris

On Thu, Feb 12, 2009 at 4:21 PM, Sha-Mayn Teh (郑韶敏) <sha...@google.com> wrote:

Hi,

A few of us from the Google OpenSocial team have been working with 51.com in China on a proposal for payments/virtual currency, and we'd like to get your feedback. The goal is to allow app developers to develop apps using virtual currency and deploy their apps on different containers. The container handles the actual transfer of money from the user (via cash, credit cards, etc) into the fake currency, and apps can charge the user for virtual items, advanced features or VIP status. Two of the biggest social networks in China, Xiaonei and 51.com, have implemented REST-like APIs on their own (non-OpenSocial) platforms, and what we're proposing is an OpenSocial JavaScript API for them to use.

Our proposal (with link to a simple prototype) can be found here: http://docs.google.com/Doc?id=dfjcf7w4_10ddst9xd9

We have a simple demo: http://www.unickway.org.cn:9002/gadgets/files/container/sample-payment.html
with sample code for the app and container: http://docs.google.com/Doc?id=dfjcf7w4_10ddst9xd9&hl=en#Demo_And_Code

Any feedback on our proposal will be appreciated, but the end goal would be: a single unified proposal for an OpenSocial REST/RPC API and JavaScript API for payments.

I know there are some other proposals/thoughts out there, including Netlog's credits extension (at http://en.netlog.com/go/developer/documentation/article=opensocialcreditsextension), so feel free to jump in!

 

-- sha-mayn

 

- Show quoted text -

[davew]

Great proposal. I think most developers dream about a standardized
solution for payments and virtual currency.

Some feedback:
[1] Subscriptions. I'm pretty sure we can build a subscription model
on top of this, but should the concept of VIP "subscriptions", with
reoccurring charges be built in to the proposal?
[2] Mobile payments. Mobile payments are often an easy way for users
to pay. Is there anything in the proposal that would prevent mobile
payments? Or any other form of payments?
[3] Support. With any payment solution, there will always be fraud,
requests for charge backs etc. Is there anything about support that
can or should be standardized? Or should it be up to the container or
app developer to handle support? If it's up to the developer, then
how would the developer request a charge back if the payment was made
through the container's payment solution? Can the idea of a "refund"
be standardized?
[4] Setting different currency exchange rates for different
countries. We'd likely charge far less for a subscription in Brazil
than we would in the US, and we'd want to have a nice round exchange
rate from real cash to virtual currency in each country. How would
this be handled? How can we specify a different currency exchange
rate? Maybe this can be handled at the app level..

None of these necessarily have to be including in the spec, just as
long as there is nothing that prevents them in the spec. But I bring
them up for discussion, because these are the kinds of things devs
think about..

I'd love to know what other containers and virtual currency companies
think of the proposal. Has anyone pitched this to Hyves, Netlog,
MyOfferPal, Peanut Labs, Mentez/UOL etc?

Thanks to everyone that put together the proposal!

-Dave

On Feb 12, 7:21 am, Sha-Mayn Teh (郑韶敏) <sham...@google.com> wrote:
> Hi,
>
> A few of us from the Google OpenSocial team have been working with 51.com in
> China on a proposal for payments/virtual currency, and we'd like to get your
> feedback. The goal is to allow app developers to develop apps using virtual
> currency and deploy their apps on different containers. The container
> handles the actual transfer of money from the user (via cash, credit cards,
> etc) into the fake currency, and apps can charge the user for virtual items,
> advanced features or VIP status. Two of the biggest social networks in

> China, Xiaonei and 51.com, <http://51.com/> have implemented REST-like APIs

> on their own (non-OpenSocial) platforms, and what we're proposing is an
> OpenSocial JavaScript API for them to use.
>
> Our proposal (with link to a simple prototype) can be found here:http://docs.google.com/Doc?id=dfjcf7w4_10ddst9xd9

> We have a simple demo:http://www.unickway.org.cn:9002/gadgets/files/container/sample-paymen...

> with sample code for the app and container:http://docs.google.com/Doc?id=dfjcf7w4_10ddst9xd9&hl=en#Demo_And_Code
>
> Any feedback on our proposal will be appreciated, but the end goal would be:
> a single unified proposal for an OpenSocial REST/RPC API and JavaScript API
> for payments.
>
> I know there are some other proposals/thoughts out there, including Netlog's

> credits extension (athttp://en.netlog.com/go/developer/documentation/article=opensocialcre...),

[Sha-Mayn Teh (郑韶敏)]

H Dave,

Great topics! We should definitely incorporate these into the design.

2009/2/14 davew <dave.w...@gmail.com>

Great proposal. I think most developers dream about a standardized
solution for payments and virtual currency.

Some feedback:
[1] Subscriptions.  I'm pretty sure we can build a subscription model
on top of this, but should the concept of VIP "subscriptions", with
reoccurring charges be built in to the proposal?

 
Very good point. Some thoughts:
- Would we need the user to authorize each monthly payment?
- If the container manages the reoccurring charges, there needs to be a way for the container to contact the app to stop service in case the user runs out of money.

[2] Mobile payments.  Mobile payments are often an easy way for users
to pay.  Is there anything in the proposal that would prevent mobile
payments? Or any other form of payments? 

I can't think of any issues with mobile payments atm, welcome thoughts from others on this.

[3] Support.  With any payment solution, there will always be fraud,
requests for charge backs etc.  Is there anything about support that
can or should be standardized?  Or should it be up to the container or
app developer to handle support?  If it's up to the developer, then
how would the developer request a charge back if the payment was made
through the container's payment solution?  Can the idea of a "refund"
be standardized?

I think that most of the burden is on the container, but we can probably do something here to help the developer. I think we may want to augment Payment with types (normal, refund, chargeback), but first we do need to work through the various use cases.

 

[4] Setting different currency exchange rates for different
countries.  We'd likely charge far less for a subscription in Brazil
than we would in the US, and we'd want to have a nice round exchange
rate from real cash to virtual currency in each country.  How would
this be handled?  How can we specify a different currency exchange
rate?  Maybe this can be handled at the app level..

Interesting, I had assumed that the currency conversion should be handled by the container during the transfer of real money to virtual money.
The app could set different virtual currency prices per country for price differences not already accounted for by the currency exchange
e.g. the container could convert 1 USD == 7 CNY (chinese yuan) == 7 virtual coins
but if it wanted to, the app could charge 10 coins/month in China (==10 CNY) and 70 coins/month in the US (==10USD)

None of these necessarily have to be including in the spec, just as
long as there is nothing that prevents them in the spec.  But I bring
them up for discussion, because these are the kinds of things devs
think about..

It's really good to hear things from the developer point of view :) 

thanks!!
-- sha-mayn

[Pieter De Schepper]

Hi All,

I'm Pieter and I have been working on the payment API at Netlog.

Basicaly, our implementation is similar to this proposal: the workflow
is exactly the same, but with a somehow different approach in handling
requests.
The biggest difference is that we configure a 'Commit URL' in our
backend, so it's not necesary to put that URL out there by passing it
as a parameter via JavaScript.
We also configure a payment KEY, with which the response of the APP
backend server should be md5-encoded, so we can verify that the APP
backend server is indeed the correct one.

However, I have nothing against passing this information through
JavaScript, and it seems that our implementation is a bit of an
overkill on that part.

We also have an object representing the payment, instead of a json
data object.
It's quite similar to an activity object.

Basicaly, a developer should create a payment with
opensocial.payment.newPayment(amount, opt_message, opt_params)
Then he can pass this object to requestPayment(checkoutURL,
paymentObject, opt_callback)
The object can also be used to store the requestParams and
responseParams in, and define functions on this object to retrieve
those params.

The Spec now only allows for paying with virtual currency.
However, applications should also be able to give a certain amount of
the virtual currency to the user. This can be handled with a negative
amount, or a different function?
There are plenty of examples where this could be used: e.g.
applications that give you credits for filling in a survey, or
challenge games where you play against another user for a certain
amount of credits.

In general, i'm very pleased with this proposal as it's quite similar
to our current implementation.

Kind regards,
Pieter De Schepper

[Sha-Mayn Teh (郑韶敏)]

Hi Pieter,

Thanks for your feedback!!!! See below.

That's a very good point and should definitely be added to the spec. Instead of having a negative amount, what about having another function requestCredit() to minimize confusion?

In general, i'm very pleased with this proposal as it's quite similar
to our current implementation.

It's a good sign that your implementation is quite similar. :)

thanks!
-- sha-mayn
 

[Chris Chabot]

Hey Pieter, 

Thanks for the feedback! Very exciting stuff to see this moving forward!

On Tue, Feb 24, 2009 at 8:18 AM, Pieter De Schepper <pie...@netlog.com> wrote:

We also have an object representing the payment, instead of a json
data object.
It's quite similar to an activity object.

I am quite charmed by having a consistency, Sha-Mayn, how does your team feel about using the object approach & do you see any merit in this?

  -- Chris

[sonic]

I also agree on having a consistent API style.
This is our rough ideas about virtual currency API, we will collect feedback and refine it. Thanks:)

--
Cai Jian

[Sha-Mayn Teh (郑韶敏)]

+1 -  I do like being consistent with the activity API too.

[Farhang]

Hi,

* This post ended up being longer than what I expected, my apologies
up front*


I am Farhang Kassaei and I work on eBay Gadget containers to support
commercial applications.

This is great that we are talking about payments because this is a
significant step to make Gadget Spec viable for a whole new class of
apps.

I divide my comments into two parts, first about the proposal (btw
greatly documented, thanks for the clear explanations and diagram) and
second about what we do at eBay that might be an interest.

Also, my context is multi-seller marketplaces and actual funds. My
main interest is to have a payment/checkout and subscription extension
that works for virtual as well as actual funds.

On the current proposal:

1- I'd consider separating payment concept from check out concept (it
is cleaner that way in the long run). I'd either remove all references
to "checkout" in the proposal or adopt the checkout terminology and
call the API gadget.checkout and pass item object that has amount as
an attribute.

2- One main assumption in the proposal seems to be that end users
(owners of funds) purchase goods (virtual in this case) from the App/
Gadget author. Sites like eBay operate in the multi-seller
marketplace, where a Gadget is likely to aggregate inventory from a
number of sellers (for example display LCD TVs from multi sellers in a
LCD TV Display Gadget). When a user clicks purchase on a specific TV,
the gadget has to pass the seller as well as amount and other
parameters. The proposal works great for the use case stated, but do
you guys think that we should account for multi-seller environment in
this proposal? For example a Gadget that allows you to buy multiple
virtual gifts from different sellers? Does this apply to SNS in CN or
other places?

What we are considering is

openCommerce.Checkout(item, quantity, seller, parameters)

The equivalent for payment would be

opencommerce.payment.requestPayment(appEndPointUrl, [payee], [payer],
amount, params)

(payer defaults to VIEWER - not all apps will be allowed to include
payer
Payee, defaults to the OWNER of an app)

2- Are we assuming that there is always a 1-1 relationship between end
user and source of funds s/he owns? I would consider this is major
modeling decision that we should make one way or another. The current
proposal seems to suggest that each user has one source of fund
(account). There are cases (in commercial apps) where one user might
have multiple sources of funds. The impact of this is mostly on the
container but it might have some implications for the spec as well
(specially in communication w/ the app back end)

3- Once we have account/source of fund (either 1-1 or 1-N) I agree
with the suggestions that we should consider supporting all operations
on "source of fund account" including creating a funding account,
adding funds to an account (by owner or by apps - this is equal to
requestCredit proposed by Chris) and debiting from an account (equal
to proposed requestPayment), as well as simple immutable stuff like
getBalance(), getAllSourceOfFunds() etc.

4- I'd be curious to see if there is a real use case in SNS in China
for person to person payment (as opposed to person paying an app) if
there is it might be a useful thing to support with something like
gadget.requestFundTransfer(appEndPointUrl, recipient, amount, params)

5- I personally went back and forth deciding whether interaction b/w
Container API Server and the App Server (steps 10-14) should be part
of the spec or be left out to individual containers and their
participants App providers. I am still not sure (especially for multi-
seller marketplaces)

I can think of two styles of interactions: event model and req/res. In
the event model the container simply *ensures* that the "fund
transferred from user X to App Y account" event is received by the
apps back end, but does not care what apps back end do with it. It is
an FYI event. Container does not handle business logic error from app
back end (all it cares is whether it received the event).

The other style is req/res where container invokes an end point and
waits for app server back end to process the request (not simply ack
receiving it) - in commercial cases this might happen if a vendor want
to ensure that they have an item in stock before fund gets
transferred. In this case container waits and should understand and
handle errors and exception from the App back end. This is the model
seems to be suggested by the proposal.

The proposal supports no interaction (null URL), sync req/res (app
provides the URL). If we are including the server to server
interaction as part of the spec, should we consider supporting a non-
blocking event style interaction as well? In this case a transaction
still would go thru even if Gadget/App server back end is down, not
available. Container will deliver the event to the server when it
becomes available.

6- Another option (to bypass all this) would be to separate the
concept of payment in commercial world and social world (virtual
funds). The current proposal then would become
opensocial.virtualcurrency and in the commerce world would become
opencommerce.payment and opencommerce.checkout

* The following might not directly related to the Sha-Mayn's proposal.
I just include it to solicit some thought and opinions*

Here is what we are doing at eBay wrt payments and subscriptions,
billing that might be of interest to this group.

The current proposal is inline with what we are thinking in terms of
both Payment and Checkout our use case is mostly about actual fund
(vs virtual fund) - for this I am glad we are converging on a standard
extension for Gadget. The API we are planning to expose currently
looks like this

Single Item Checkout: openCommerce.Checkout(item, quantity, seller,
parameters)

Multi Item Checkout: openCommerce.Checkout(cart, parameters)
(our cart model includes seller and quantities)

The App Server End point is configured in the backend and there are
end points for events and req/res. Configuring the end point in the
back end might sound like an over kill, but we need to ensure that the
Gadget /App owner who claims ownership of domain actually owns it
(security and legal stuff)

The assumption here is that the container is the entity that performs
the check out using the following chain (just major steps)

- Display shipping options and allows user to choose one (if more than
one is available)
- Applies discounts/coupons etc.
- Calculate tax,
- Display order review page and confirmation page
- Transfer fund from user account to app owner account
- Send an event to the App Server back end point

The alternative workflow requires App server back end approval

- Display shipping options and allows user to choose one (if more than
one is available)
- Applies discounts/coupons etc.
- Calculate tax,
- Display order review page and confirmation page
- Invoke App Server back end and get a confirmation that the container
should proceed (perhaps App Server ensures the order can be fulfilled
etc.)
- Transfer fund from user account to app owner account
- Send an event to the App Server back end point

The interesting issue is that sometimes the container processing
pipeline needs to be configurable per seller. We have sellers that use
"Check out providers". These are apps that handle shipping and tax
calculation, discounts, coupons etc. for a seller. So the container
(marketplace) needs to invoke check out provider for a particular
seller (can be yet another Gadget) and get the final amount to be
charged to users account from it (thru RPC channel) - we are trying to
standardize these interaction and coming up with some proposal, but I
just wanted to bring up the use case.

These are all applicable to users/VIEWERs doing a one time purchase of
goods/service from sellers (like you see on eBay, Amazon etc.)

Purchasing services/software on a subscription bases is a different
stream of activities. To give a brief background, the use case here is
selling subscription for productivity applications to sellers in a
multi-seller marketplace like eBay. The container is the marketplace
and it authenticates sellers and also knows about the apps and their
authors.

Our first thought was to add a "subscription" view for gadgets and let
each gadget handle its own subscription flow (display subscription
plans, pricing, discounts, T&C etc.), capturing users' choice and
having the container billing the seller on behalf of the app owner.
This way container would not have to know much about the subscription
plans. The container receives a subscription object from the Gadget
that include one time fee, recurring fee, subscription period and
charge cycle (one year subscription, charge $10/month or 1 year
subscription charge $115/year)

openCommerce.subscription.createSubscription(subscriptionPlan,
parameters)

The container would then confirm with the user (like it is suggested
in the proposal) and then create subscriptions (either by invoking the
App back end server or no interaction with it depending on app
preference)

The final decision however was to take control of subscription flow
(for product reasons) and have Gadget/App developers configure their
subscription plan ahead of time in the backend. The container will
display the proper subscription plans on behalf of an app/gadget. Our
spec includes back end integration spec with the App Servers and
additions to the deployment descriptor for proper end points and
subscription plans.

Despite this, I personally think we should consider adding
"subscription control" to the Gadget spec. Today, this portion is
performed by the containers and all subscription (that I know of) are
basically free and of unlimited duration (one special case of
subscription plans).

Thanks
F

On Feb 25, 10:56 pm, Sha-Mayn Teh (郑韶敏) <sham...@google.com> wrote:
> +1 - I do like being consistent with the activity API too.
>

> On Wed, Feb 25, 2009 at 11:15 PM, sonic <soni...@gmail.com> wrote:
> > I also agree on having a consistent API style.
> > This is our rough ideas about virtual currency API, we will collect
> > feedback and refine it. Thanks:)
>

[Sha-Mayn Teh (郑韶敏)]

Hi,

Firstly, I've published a new revision of the spec that incorporates
feedback from previous discussions (same link as before):
http://docs.google.com/Doc?docid=dfjcf7w4_10ddst9xd9
A copy of the original spec is linked off of the appendix doc.
The main changes are:
- Refactored payment into an object similar to Activity
- Changed the payment response from ResponseParameters to ResponseItem
- Added requestCredit
- Cancel/close events added to workflow diagram
- Added workflow for apps with no backend
- checkoutURL in requestPayment changed to paymentHandlerURL and
checkout terminology removed

Some TODOs not yet written in: sample server-to-server communication,
subscription model, fraud guidelines

We're still updating the demo to accommodate these changes. Comments
welcome and thanks to those who gave their valuable feedback before!

Secondly, Farhang: it's great to hear from you with real e-commerce
experience! Comments below.

> Also, my context is multi-seller marketplaces and actual funds. My
> main interest is to have a payment/checkout and subscription extension
> that works for virtual as well as actual funds.
>

I think it would be great to have a proposal that works for both
virtual and actual funds, though it looks likethe requirements for
actual funds will be more complex. It's worth a shot...

> On the current proposal:
>
> 1- I'd consider separating payment concept from check out concept (it
> is cleaner that way in the long run). I'd either remove all references
> to "checkout" in the proposal or adopt the checkout terminology and
> call the API gadget.checkout and pass item object that has amount as
> an attribute.

That's a really good point. We removed the checkout terminology as you
suggested. I think handling all the aspects of shopping carts, taxes,
discounts and general checkout were not in the original scope. As you
mentioned, it may make more sense to have a separate module
openCommerce and handle the payment-related aspects in this spec.

>
> 2- One main assumption in the proposal seems to be that end users
> (owners of funds) purchase goods (virtual in this case) from the App/
> Gadget author. Sites like eBay operate in the multi-seller
> marketplace, where a Gadget is likely to aggregate inventory from a
> number of sellers (for example display LCD TVs from multi sellers in a
> LCD TV Display Gadget). When a user clicks purchase on a specific TV,
> the gadget has to pass the seller as well as amount and other
> parameters. The proposal works great for the use case stated, but do
> you guys think that we should account for multi-seller environment in
> this proposal? For example a Gadget that allows you to buy multiple
> virtual gifts from different sellers? Does this apply to SNS in CN or
> other places?
>
> What we are considering is
>
> openCommerce.Checkout(item, quantity, seller, parameters)
>
> The equivalent for payment would be
>
> opencommerce.payment.requestPayment(appEndPointUrl, [payee], [payer],
> amount, params)
>
> (payer defaults to VIEWER - not all apps will be allowed to include
> payer
> Payee, defaults to the OWNER of an app)

That's a good point - perhaps some kind of marketplace app that acts
as intermediary between other apps? We can add optional payee/payer to
the Payment.Field to handle this case?

>
> 2- Are we assuming that there is always a 1-1 relationship between end
> user and source of funds s/he owns? I would consider this is major
> modeling decision that we should make one way or another. The current
> proposal seems to suggest that each user has one source of fund
> (account). There are cases (in commercial apps) where one user might
> have multiple sources of funds. The impact of this is mostly on the
> container but it might have some implications for the spec as well
> (specially in communication w/ the app back end)

I think you're right, the impact of this will probably mostly be on
the container, with some param on the payment to indicate which funds
source. I haven't thought of a use case for this on the virtual side
yet.

>
> 3- Once we have account/source of fund (either 1-1 or 1-N) I agree
> with the suggestions that we should consider supporting all operations
> on "source of fund account" including creating a funding account,
> adding funds to an account (by owner or by apps - this is equal to
> requestCredit proposed by Chris) and debiting from an account (equal
> to proposed requestPayment), as well as simple immutable stuff like
> getBalance(), getAllSourceOfFunds() etc.

A few concerns: I'm not sure we should support creating/administering
the funding accounts through the app interface, shouldn't this be a
container function?
Re: getBalance(): I think the app should be able to get a list of all
its payments in all states, but should it have access to the overall
account balance for privacy reasons?

So how about:
requestPayment()
requestCredit()
requestFundsTransfer() - all 3 using the Payment object?
getTransactions()
getFundSources() // returns ids of fund accounts that can be used in
requestPayment etc

>
> 4- I'd be curious to see if there is a real use case in SNS in China
> for person to person payment (as opposed to person paying an app) if
> there is it might be a useful thing to support with something like
> gadget.requestFundTransfer(appEndPointUrl, recipient, amount, params)

I think there is a potential use case for this, although containers
might not be keen on offering this at the beginning.

Yes, we are proposing the req/res model... and we were thinking of
including the server-to-server part as a guideline/example rather than
as part of the spec and allow the container to specify it themselves.
Or should we include it in the spec?
The event model should be accommodated by the current spec, right?

> 6- Another option (to bypass all this) would be to separate the
> concept of payment in commercial world and social world (virtual
> funds). The current proposal then would become
> opensocial.virtualcurrency and in the commerce world would become
> opencommerce.payment and opencommerce.checkout

My feeling is that if we just restrict this discussion to the payments
side (and not consider checkout), then it's do-able to try to handle
both actual and virtual payments. What do people think?

I would also like to add subscriptions (Dave also suggested this) but
yeah the use cases can be a bit complicated. I like your proposal to
have a SubscriptionPlan class and Fields for period, charge cycle, fee
etc.
We can have createSubscription()/removeSubscription()/getSubscriptions()
methods or similar.

thanks!
-- sha-mayn

[eggtea]

I like where this is going, I'd love to see a virtual store prototype
with: item submission, item store/galleries, item rank, user role
stores, user rank items, multiple rank submission process. (look at
deviantart when thinking about stores/galleries, items with xml ids,
public stats (purchased, favs, downloads, etc))

This idea would feel more substantial if there was a working example
of a seem less store module. Keeping the whole shopping process in one
ajax area. With a shopping cart system. maybe drag and drop items into
the cart, & a "purchase" or "download all" button if the items can be
downloaded.

[Chris Chabot]

Hi Egg Tea,

I think there might be some miss-alignment between what this specification proposal is, and your expectations.

On this mailing list we discuss the OpenSocial API specification (ie, what should the programming interface do & what will they be called), and not about how the applications that use this API will look or work like. That later part, how it will look and work for the end-user, is completely upto the application devevelopers, and upto the social networking sites.

Here we 'just' define a standard way in which those things can be build, so that when someone builds a really cool shopping application, that really cool application can be used on all sites that support the OpenSocial standard.

  -- Chris

[狗头]

Hi all,

New revision(#3) is published to the proposal doc (same link as
before) with some feedback from previous discussions:
http://docs.google.com/Doc?docid=dfjcf7w4_10ddst9xd9
A copy of the original spec #1 and revision #2 are linked off of the
appendix doc.


The major changes from the last proposal are some conclusion of our
discussion. The changes including:

1. Moved the namespace from gadgets.* to opensocial.*, and creates two
methods: opensocial.newPayment and opensocial.requestPayment.
2. Added the fetch payment method in DataRequest:
opensocial.DataRequest.newFetchPaymentRequest and related enum.
3. Removed the requestCredit, but reuse requestPayment with a new
CREDIT type enum.
4. Outlined the container server-app backend server interface more
clearly.
TODOs: restful interface, subscription model, fraud guidelines, fund
transfer interface (optional)

We also setup a project for the virtual currency proposal:
http://code.google.com/p/opensocial-virtual-currency/
And will keep the code updated.

Some notes:
For 'requestFundTransfer', we haven't made it yet. We will keep
discussion on this direction.
RESTful interface is not in this version yet, but will be in next
revision.

Thanks everybody!


-Yizi

> > - Invoke App...
>
> read more >>

[Scott Seely]

Is there a reason we are suggesting to follow the pattern in the legacy OpenSocial API instead of the API patterns from the new, lite API introduced for 0.9 (http://www.opensocial.org/Technical-Resources/opensocial-spec-v09/OpenSocial-Specification.html#LightweightJSAPI)?

> -----Original Message-----
> From: opensocial-an...@googlegroups.com [mailto:opensocial-and-
> gadget...@googlegroups.com] On Behalf Of ??
> Sent: Monday, April 20, 2009 7:33 PM
> To: OpenSocial - OpenSocial and Gadgets Specification Discussion
> Subject: [opensocial-and-gadgets-spec] Re: Proposal: Virtual Currency API
>
>

[Paul Lindner]

Did we ever come to a conclusion on how to handle UI element flows in
osapi/oslite?

I don't seem to see it in the released specification.

I'd love to move to something based on osapi, it works better with my
jQuery addicted brain.

[Kevin Brown]

2009/4/21 Paul Lindner <lin...@inuus.com>

Did we ever come to a conclusion on how to handle UI element flows in
osapi/oslite?

No, which is problematic because at least 3 critical calls depend on it already: HTTP (for oauth dance), share app / send message (to avoid spam).
 

[Adam Winer]

We had a partial conclusion, which was:
- any osapi call is potentially container mediated, that is, may
require a UI flow
- such UI element flows happen implicitly within a batch or individual request

This works well for anything that maps on to an existing endpoint,
e.g. activity creation,
and may work for message sending (and perhaps HTTP OAuth requests via
osapi.http?)
It doesn't answer how to handle:

A. UI flows that don't map to a server endpoint (share app, request
permission)
B. Parameters that pertain explicitly to the UI, and should not be
sent to the server
C. How UI flows work with batching, especially if a flow requires
navigation away from the page
D. What HTTP error code should be returned for cancelled UI flows?

We also punted on explicitly specifying message sending in osapi, but
the spec does say "The server SHOULD generate service methods for all
available services", so message sending (and albums, etc.) should be
supported by any container providing those endpoints.

This'd be a good area for early v.Next work, since it's a clear gap.

Some strawman propsals:
A. requestShareApp() is essentially just a a requestSendMessage()
variant. Add type="shareApp" to the message endpoint.
requestPermission() could be a method on any request object or batch, so:
osapi.people.getViewer().needPermission(opt_callback);
... which will request permission for getting a viewer, without
actually getting the viewer. If the callback receives a non-error
response, subsequent calls to get the viewer should succeed.
B. Just throw them in the parameter bag. At most, wrap them in a
"ui" container.
C. Leave it unspecified - it's questionable if this will ever matter
D. 401

-- Adam



2009/4/21 Kevin Brown <et...@google.com>: