Vingd interaction overview¶
You communicate with Vingd system thru Vingd Broker, using the
Vingd
PHP class. Direct communication with Vingd Broker over HTTP
is also simple (see A few technical details), but discouraged.
Vingd enables you to monetize your digital goods by “selling” the access rights to your content/service. You host the content and you control the access, and we handle the access rights. As the first approximation, Vingd can be seen as a payment gateway.
Thru Vingd, you can also reward users with vingds via Vingd Vouchers, or directly transfering vingds to user account in backend.
Purchase¶
The content or service of yours has an abstract representation on Vingd, called Vingd Object. Object enrollment (aka registration) is a one-time process, after which an object can be “sold” to Vingd users. Terms of purchase (namely, the price) are defined by you, the seller, in what is called Purchase Order. Orders can be viewed as bills you give to users. User pays that bill on Vingd user frontend and it gets object access rights assigned for the object you referenced in the order. Each time a user tries to access your object (the location you specified upon object enrollment and which you control), you should demand an access token from your user, issued by Vingd Broker. With the access token we shall vouch that the specific user has paid for the access, and you should allow him to view the object (content/service).
Registering objects¶
In order to sell anything thru Vingd, you must enroll (i.e. register) an
abstract representation of that item, as an object in our Object Registry
(thru Vingd Broker). Objects are enrolled with Vingd::createObject
function. During object enrollment, a unique Object ID (oid
) is assigned
to that object. Store that oid
, since you’ll be using it as the object
handle.
Object description is a dictionary (associative array) with only two mandatory
keys: name
and url
. Make sure the url
points to a valid location,
because users will be redirected there upon object purchase (consider this URL
to represent the object location, according to the REST paradigm). More
precisely, the complete URL where user will be redirected is object’s url
with Token ID and Object ID glued as GET parameters (tid
and oid
).
Selling an object¶
To sell any of your enrolled objects, you must create an Object Order which
shall encapsulate the terms under which the object is being sold to the customer
(e.g. price). Vingd::createOrder
method facilitates order creation. Object
and price are defined with $oid and $price in vingds (rounded to
cents). Expiry date of the very order is defined with $expires.
It is important to note that orders are not bound to a specific user. That means you could (and preferably would) generate one order with expiry time longer than the default 15mins and offer that same order to more than one user (e.g. you could have special order for each “class” of your users). The advantage of having pre-generated orders is you are cutting down the overhead of object purchase on your site - you don’t have to generate a new order in background for every user’s “buy-click”, but simply direct the user to order-purchase-link on Vingd (as returned upon the initial order making).
On a successful order creation, you shall be given an URL pointing to your order
on Vingd frontend (see ['urls']['redirect']
element of a value returned from
Vingd::createOrder
). To enable an user to pay the access to your
object, you should direct her exactly to that very URL (if you’re using Vingd
Popup Library you should use the order['urls']['popup']
URL).
Verifying user access rights¶
Upon successful confirmation of an order (specified amount of vingds is reserved
from user’s account), a Vingd Token is issued by Vingd Broker. User is
redirected to the (callback) object url with the Token (tid
) and Object
ID (oid
) appended. This token is short-lived (typically 15 minutes) and
during its lifespan it represents a voucher that can be checked to see if the
carrier of the (tid, oid)
pair has rights for accessing object oid
.
To verify the token, use Vingd::verifyPurchase
. If user access is
granted, token verification interface returns Token Description.
In a popup mode, you will also want to verify the token when user returns from Vingd frontend (see Vingd Popup onSuccess() callback).
Wrapping up the purchase¶
Once you have successfully served the content user has paid for, you should notify the Vingd Broker, referencing the Order ID, Purchase ID and Transfer ID (the last two are returned in Token Description upon token verification). This completes the purchase.
If you don’t do Vingd::commitPurchase
, Vingd Broker assumes a seller
(you) failed to deliver the content or service to the user and does an automatic
refund.
Rewarding¶
Vingd::createVoucher
allows you to allocate a certain amount of
vingds from your account and offer it to a Vingd user. Voucher code looks like
LXKG-TBR-HQV
(only letters A-Z and digits 0-9 are significant; all other
characters are ignored). Upon voucher creation, Vingd::createVoucher
returns a structure with an URL pointing to Vingd frontend which user can follow
to use the voucher. Vingd popup can also be used, see Vingd Popup Voucher
example.
A few technical details¶
Vingd Broker (https://api.vingd.com/broker/v1/) has a very simple REST
interface to a complete Vingd backend. For example, to retrieve a list of
objects you registered, execute a GET
request on the Vingd Objects resource
(https://api.vingd.com/broker/v1/registry/objects/) authenticating using HTTP
Basic Auth (with Vingd username and password SHA1 hash). The response should be
a JSON list of object descriptions.
Creating (enrolling, or registering) a new object is slightly more complex, but
nevertheless still trivial: POST
a JSON-encoded description of the object to
that same URL (which, btw, represents a collection of your objects).
However, if you are using Python/PHP/.NET/Java there should never be a need for you to manually implement a client for our REST backend, since we already support libraries for those environments.