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.

Table Of Contents

Previous topic

Vingd

Next topic

Vingd library reference

This Page