- Requirements
- Research
- Use Cases
- Deployment Architecture
- Analysis
- Design
- API
- users_has_paid( $pid, $aid, $nid )
- users_has_paid( $uid, $nid1, $aid, $nid2 )
- app_has_paid( $aid1, $nid1, $aid2, $nid2 )
- network_has_paid_app( $nid, $aid )
- network_has_paid_network( $nid1, $nid2 )
- merchant_add_network_acct( $nid, $gatewayid, $gatewaykey )
- subscription_add_app_plan( $aid, $plan_name, $price, $description )
- subscription_add_app_plan( $aid, $nid, $plan_name, $price, $description )
- subscription_add_network_app_plan( $aid, $nid1, $nid2, $plan_name, $price, $description )
- subscription_add_network_plan( $nid, $plan_name, $price, $description )
- subscription_get_app_plans( $aid )
- subscription_get_network_plans( $nid )
- subscription_retirePlan( $planid )
- subscribe_user_to_app( $pid, $aid, $planid )
- subscribe_user_to_app( $uid, $nid, $aid, $planid )
- subscribe_users_to_app( $users, $aid, $planid )
- subscribe_user_to_network( $pid, $nid, $planid )
- subscribe_user_to_network( $uid, $nid1, $nid2, $planid )
- subscribe_network_to_app( $nid, $aid, $planid )
- subscribe_app_to_app( $aid1, $aid2, $planid )
- subscribe_app_to_app( $aid1, $nid1, $aid2, $nid2, $planid )
- pay( $gatewayid, $gatewaykey, $amount, $lineitems, $uid, $ccinfo )
- Payment Tags
- Other Considerations
Requirements
- Applications can charge these customers:
- Single users using the application
- Single users using a subset of the application's features
- Other applications using the application's APIs
- Other applications using the application's tags
- Other applications using a subset of the application's APIs
- Other applications using a subset of the application's tags
- Communities using the application
- Applications can charge:
- by the month/year (subscription)
- for a range of # of users
- for a range of usage
- # of API calls
- # of tag renderings
- amount of data used
- one time fee
- by # of users
- by amount of usage
- # of API calls
- # of tag renderings
- amount of data used
- Credit card information must be captured via a secure interaction with the user
Note that payment services are functionally different than a Ringside marketplace offering. Marketplace requirements would be detailed here should they become part of the scope of this work. While I'm thinking about it, might want to check out Magneto for integration if we want to implement marketplace functionality.
Research
Existing APIs
Providers
Blog Posts
SSL Certificate Providers
Use Cases
Basic use cases:
Payment Types
The two major use cases, "Pay for Network Access" and "Pay for Application Use" can both be extended to allow for the following specific types of payments:
- One time payment
- One time payment for access that expires on a given date
- One time setup fee + provisioned subscription
- Subscription
- Periodic payment for actual usage
Application User
- An application user can pay for access to a social network, and its entire directory of social applications.
- Payment will be received by the network operator
- An application user can pay for access to a single application deployed within a social network.
- Payment will be received by the application provider/developer
- or
- Payment will be received by the network operator
3rd Party Community
- A 3rd party community/web site can pay for all of its users to access applications on an external social network
- Payment will be received by the network operator
- A 3rd Party community/web site can pay for access to a single application deployed within an external social network.
- Payment will be received by the application provider/developer
- or
- Payment will be received by the network operator
Application
- An application can pay for access to a social network, and its entire directory of social applications.
- Payment will be received by the network operator
- An application can pay for access to a single application deployed within a social network.
- Payment will be received by the application provider/developer
- or
- Payment will be received by the network operator
Payment Processor Specific Use Cases
These cases are more specific to the payment processing entity. Basically, they express the security requirement, and the need for Application Providers and 3rd Party Communities to be able to provision merchant accounts.
Value added use cases:
Payment Gateway Use Cases/Data Flow
Deployment Architecture
The deployment architecture reflects the basic use cases above. An application user can pay for use of the application when using it through facebook or a third party community web site. The user can also pay for and use the application directly via the application's deployed social network. Additionally, the user could pay to be part of the 3rd party community, and thus gain access to all social applications available there. A 3rd party community web site can pay for its users to use all of the applications available there or just a single application.
Ringside will communicate with a payment service vendor via a vendor specific adaptor.
Analysis
Terminology
Merchant: The entity selling something (such as a social application selling a subscription for its use)
Merchant Account: An account opened by a merchant into which payments are deposited.
Payment Gateway: An intermediary that simplifies interacting with various payment processing services. A payment gateway must somehow have knowledge of a Merchant's Merchant Account in order to be of any use.
Provider Comparison
| Criterion |
Authorize.net |
PayPal |
ARIA |
Google Checkout |
| Is payment gateway? |
Yes |
Yes |
Yes |
Yes |
| Can provide merchant accounts? |
No |
Yes |
No |
? |
| Is brandable? |
Yes |
Yes |
Yes |
Yes |
| Supports subscriptions |
Yes |
Yes |
Yes |
No |
| Allows dynamic creation of merchant accounts? |
No |
? |
No |
? |
| Supports transaction based commissions for customers with existing merchant acccounts? |
Yes |
? |
? |
? |
| Supports transaction based commissions for customers with existing gateway acccounts? |
No |
? |
? |
? |
| Allows identical, social subscriptions |
? |
? |
? |
? |
API Research
Authorize.net
| API Provider |
API Name |
Functional Benefit |
Methods |
| Authorize.net |
ARB API |
Subscriptions |
ARBCreateSubscriptionRequest |
| |
|
|
ARBUpdateSubscriptionRequest |
| |
|
|
ARBCancelSusbscriptionRequest |
A response message is sent back for the create and cancel requests containing the subscription ID. Error codes are returned in failure cases.
Design Considerations
Application developers will need to keep track of their user subscriptions. This could be done as part of their own database, or the Ringside server could provide this facility for them. If so, we may need a user_app_subscription table in the database. Pending investigation of other API providers, this may turn out to couple us tightly to Authorize.net (not good). My guess is that application developers will differ in their preferences regarding preferred payment service providers, and thus we could provide an API that generalizes the inner workings of the APIs offered by the main players.
Note that using Authorize.net relieves the application provider of having to store customer information - that is what Authorize.net provides, as I understand it currently.
There will be security considerations from an application provider perspective. For example, do we need certificate management capabilities to be part of the server, or does this get delegated to the application provider?
Architectural Options
Option A - Payment System Application
With this option, payment requests come in through the web container, through the social engine, to the payment system application. The system application communicates directly with the payment gateway (like Authorize.net).
Pros
- <rs:require-payment/> would fit in nicely.
Cons
- Tightly coupled to payment gateway
Option B - Payment System Application with API Implementation
This option decouples the payment system application from the payment gateway, thus enabling a payment gateway abstraction.
Pros
- We can plug in any payment gateway
Cons
- ?
Option C - API Implementation Only
This option would require application developers to use the API directly and create their own user interface for gathering payment information.
Pros
Option D - We Are the Payment Gateway
Pros
- ?
Cons
- We may need to integrate with several merchant processing services
- We have to store private user credit card information securely and follow (unknown) legal obligations
Design
API
users_has_paid( $pid, $aid, $nid )
Returns true if the user with the given principal id has paid for the specified application or network. $aid and $nid are mutually exclusive.
- pid - required - principal id
- aid - application id
- nid - network id
users_has_paid( $uid, $nid1, $aid, $nid2 )
Returns true if the user with the given user id and network id ($nid1) has paid for the specified application or network ($nid2). $aid and $nid2 are mutually exclusive.
- uid - required - user id
- nid1 - required - network id associated with this user. If null, defaults to current network.
- aid - application id
- nid2 - network id
app_has_paid( $aid1, $nid1, $aid2, $nid2 )
Returns true if the first application has paid for the second application. If $nid1 or $nid2 is null, defaults to the current network.
network_has_paid_app( $nid, $aid )
network_has_paid_network( $nid1, $nid2 )
Returns true if the first network ($nid1) has paid for the second network ($nid2).
merchant_add_network_acct( $nid, $gatewayid, $gatewaykey )
- nid - required - the application for which to associate the merchant account
- gatewayid - required - the merchant's unique identifier with the payment gateway. This will typically be provided to the
subscription_add_app_plan( $aid, $plan_name, $price, $description )
Add a pricing plan for the specified application.
Note: it does not appear that this capability is available dynamically from either Aria or Authorize.net. Thus, plan information will need to be stored by Ringside.
subscription_add_app_plan( $aid, $nid, $plan_name, $price, $description )
Add a pricing plan for the specified application from the specified network.
Note: it does not appear that this capability is available dynamically from either Aria or Authorize.net. Thus, plan information will need to be stored by Ringside.
subscription_add_network_app_plan( $aid, $nid1, $nid2, $plan_name, $price, $description )
Add a pricing plan for application 1 from network 1 for users of network 2. Pricing plans specified for applications AND networks are more specific, and thus override general application pricing. For example, if a user from network X want to subscribe to application A, they will have to pay price XA even thoughthe price for users from all other networks pay price B.
Note: it does not appear that this capability is available dynamically from either Aria or Authorize.net. Thus, plan information will need to be stored by Ringside.
subscription_add_network_plan( $nid, $plan_name, $price, $description )
Add a pricing plan for the specified network.
Note: it does not appear that this capability is available dynamically from either Aria or Authorize.net. Thus, plan information will need to be stored by Ringside.
subscription_get_app_plans( $aid )
subscription_get_network_plans( $nid )
subscription_retirePlan( $planid )
subscribe_user_to_app( $pid, $aid, $planid )
Subscribe the specified user to the specified application according to the terms of the specified plan.
- pid - required - principal id
- aid - the application id of the application being subscribed to
- planid - required - the plan id to which the user is subscribing
subscribe_user_to_app( $uid, $nid, $aid, $planid )
Subscribe the specified user to the specified application according to the terms of the specified plan.
- uid - requried - user id
- nid - network id of user. If null, defaults to current network
- planid - required - the plan id to which the user is subscribing
subscribe_users_to_app( $users, $aid, $planid )
Subscribe each of the specified users to the specified application according to the terms of the specified plan. The price associated with the plan will be multiplied by the number of users to arrive at the total charge.
- users - requried - an array of arrays, where the inner array is of the form ('uid'=>12345, 'nid'=>12345 )
- nid - network id of user. If null, defaults to current network
- planid - required - the plan id to which the user is subscribing
subscribe_user_to_network( $pid, $nid, $planid )
Subscribe the specified user to the specified network according to the terms of the specified plan.
- pid - required - principal id of the user subscribing to the network
- nid - network id of the network being subscribed to. If null, defaults to current network
- planid - required - the plan id to which the user is subscribing
subscribe_user_to_network( $uid, $nid1, $nid2, $planid )
Subscribe the specified user to the specified network according to the terms of the specified plan.
- pid - principal id
- nid1 - network id of the user. If null, defaults to current network
- nid2 - required - network id of the network being subscribed to
- planid - required - the plan id to which the user is subscribing
subscribe_network_to_app( $nid, $aid, $planid )
Subscribe the specified network to the specified application according to the terms of the specified plan.
subscribe_app_to_app( $aid1, $aid2, $planid )
Subscribe application 1 to application 2 according to the terms of the specified plan.
subscribe_app_to_app( $aid1, $nid1, $aid2, $nid2, $planid )
Subscribe application 1 from network 1 to application 2 from network 2 according to the terms of the specified plan.
pay( $gatewayid, $gatewaykey, $amount, $lineitems, $uid, $ccinfo )
Payment Tags
Initial, unfiltered thoughts:
<rs:require-payment type="{subscription|onetime|onetimeexpires|actualuse}" returnurl="someapp.com" />
<rs:if-has-paid plan="silver" />
<rs:payment-ad type="{button|link}" description="For $3.99/month get super features x, y, and z" />
<rs:payment-panel inline="{true|false}" />
<rs:payment-plans aid="12345" nid="12345" editable="true|false" />
<rs:require-payment />
- returnurl - the URL the user should be directed to after having successfully paid
<rs:if-has-paid />
Display the enclosed content only if the user or their network has paid for access.
Attributes:
- plan - the plan name for which this content is accessible. Multiple plan names can be specified via a comma delimited list, for example "plan='bronze,silver,gold'".
<rs:payment-ad />
Attributes:
- type - the type of payment ad to be displayed. Valid values are either 'button' or 'link'. Default type is 'button' if attribute is not specified.
- description - The description of what's for sale.
<rs:payment-panel />
<rs:payment-plans />
Displays the provisioned payment plans for the given application id or network id. This tag is embeddable as a child of the <rs:payment-panel /> tag.
Attributes:
- aid - the application id for which to display available payment plans
- nid - the network id for which to display available payment plans
- editable - if 'true', an edit button will allow the user to change aspects of the provisioned plan. Requires developer access to the application in question or network administration rights for the network in question.
Specifying both aid and nid will display payment plans that have been configured for the given application AND network.
Other Considerations
What about Ad Revenue sharing? If one app uses another and gains revenue from advertising, should they be able to arrange advertising revenue sharing? Is this in scope for Ringside?
