Vingd library reference

Vingd class

class Vingd

Vingd API interface class.

Constants

constant Vingd::URL_ENDPOINT

https://api.vingd.com/broker/v1

constant Vingd::URL_FRONTEND

https://www.vingd.com

constant Vingd::URL_ENDPOINT_SANDBOX

https://api.vingd.com/sandbox/broker/v1

constant Vingd::URL_FRONTEND_SANDBOX

http://www.sandbox.vingd.com

constant Vingd::EXP_ORDER

Default order expiry, ‘+15 minutes’. The order expires in 15 minutes, relative to the time of creation.

constant Vingd::EXP_VOUCHER

Default voucher expiry, ‘+1 month’. The voucher expires in one month, relative to the time of creation. When it expires, allocated funds are refunded to the issuer’s Vingd account.

Purchase

Vingd::createObject($name, $url)

Creates (registers) an object in the Vingd Object Registry.

Parameters:
  • $name (string) – Object’s name.
  • $url (string) – Object’s callback URL.
Returns:

(integer) Object ID assigned in Vingd.
Throws:

VingdException, Exception
Vingd::updateObject($oid, $name, $url)

Updates an object enrolled in the Vingd Object Registry.

Parameters:
  • $oid (integer) – Object ID, as returned by Vingd::createObject.
  • $name (string) – Object’s new name.
  • $url (string) – Object’s new callback URL.
Returns:

(integer) Object ID assigned in Vingd.
Throws:

VingdException, Exception
Vingd::getObject($oid)

Fetches object with id $oid.

Parameters:
Returns:

(array) Vingd object description.
Throws:

VingdException, Exception
Vingd::getObjects()

Fetches all objects for the authenticated user.

Returns:(array) A list of Vingd objects.
Throws:VingdException, Exception
Vingd::createOrder($oid, $price, $context = null, $expires = Vingd::EXP_ORDER)

Creates an order for object $oid, with price set to $price and validity until $expires.

Parameters:
  • $oid (integer) – Identifier of the object to be sold, as returned by Vingd::createObject.
  • $price (float) – Object’s price in VINGDs. Rounded to two decimal digits.
  • $context (string) – Arbitrary (user-defined) context handle of this purchase. $context shall be retrieved upon purchase/token verification. (Usage discouraged for sensitive data.) Default: no context associated with order.
  • $expires (string) – Expiry timestamp / validity period of the order being generated (accepts any PHP/strtotime-parsable date/time string, including ISO 8601, RFC 822, and most English date formats, as well as relative dates). Default: Vingd::EXP_ORDER (‘+15 minutes’, i.e. order expires in 15 minutes).
Returns:

(array) Vingd order description.
Throws:

VingdException, Exception
Vingd::verifyPurchase($token)

Verifies purchase token $tid and returns token data associated with it (and bound to object $oid).

Note:

If token was invalid (purchase can not be verified), a VingdException is thrown.
Parameters:
  • $token (array/string) –

    Access token user brings in, as returned from Vingd user frontent on object’s callback URL.

    verifyPurchase accepts $token as either string (as read from $_GET['token'] on callback processor), or as array (json-decoded from the URL).

    You should always verify the token the user brings in from Vingd frontend to ensure the user has access rights for your object and/or service. Successful token verification guarantees Vingd Broker has reserved user vingds for the seller. Those vingds will be transfered after seller commits the purchase (see commitPurchase).
Returns:

(array) Purchase details:
  • ‘object’ key: Object name.
  • ‘huid’ key: Buyer’s seller-bound user id (user id unique for the authenticated owner/seller of $oid).
  • ‘purchaseid’: Vingd Purchase ID.
  • ‘transferid’: Vingd transfer ID.
Throws:

VingdException, Exception
Vingd::commitPurchase($purchase)

Commits the purchase (defined with $purchaseid and $transferid) as finished.

Call commitPurchase upon successful delivery of paid content to the user. If you do not call commitPurchase, the user shall be refunded automatically.

Parameters:
  • $purchase (array) – User purchase description, as returned by verifyPurchase upon successful token verification.
Returns:

(array) (‘ok => true), or fails with VingdException.
Throws:

VingdException, Exception

Rewarding

Vingd::createVoucher($amount, $until = Vingd::EXP_VOUCHER, $message = '', $gid = null, $description = null)

Makes a new voucher.

Parameters:
  • $amount (float) – Voucher amount in VINGDs.
  • $until (date) – Timestamp of voucher expiry (accepts any PHP/strtotime-parsable date/time string, including ISO 8601, RFC 822, and most English date formats, as well as relative dates; e.g. ‘+1 day’, ‘+1 month’, etc.). Default: Vingd::EXP_VOUCHER (‘+1 month’, i.e. voucher expires in one month). When it expires, allocated funds are refunded to the issuer’s Vingd account.
  • $message (string) – A message user shall be presented with after submitting the voucher (on Vingd frontend).
  • $gid (string) – Voucher Group ID (alphanumeric string: [-_a-zA-Z0-9]{1,32}). User can use only one voucher per group.
  • $description (string) – Voucher internal description. Optional, but can be helpful for tracking.
Returns:

(array) Voucher description. The most interesting keys being: code and urls (which branches to redirect URL and popup URL).
Throws:

VingdException, Exception
Vingd::getActiveVouchers()

Fetches a list of all active (non-expired) vouchers for the authenticated user.

Returns:(array) A list of voucher descriptions.
Throws:VingdException, Exception
Vingd::getVouchers()

Fetches a complete vouchers history (for the authenticated user). The list includes active, expired, used and revoked vouchers (discriminated via action key in voucher description).

Returns:(array) A list of voucher descriptions.
Throws:VingdException, Exception
Vingd::rewardUser($huid, $amount, $description = null)

Rewards user defined with $huid with $amount vingds, transfered from the account of the authenticated user.

Parameters:
  • $amount (float) – Voucher amount in VINGDs.
  • $until (date) – Timestamp of voucher expiry (accepts any PHP/strtotime-parsable date/time string, including ISO 8601, RFC 822, and most English date formats, as well as relative dates; e.g. ‘+1 day’, ‘+1 month’, etc.). Default: Vingd::EXP_VOUCHER (‘+1 month’, i.e. voucher expires in one month). When it expires, allocated funds are refunded to the issuer’s Vingd account.
  • $message (string) – A message user shall be presented with after submitting the voucher (on Vingd frontend).
  • $gid (string) – Voucher Group ID (alphanumeric string: [-_a-zA-Z0-9]{1,32}). User can use only one voucher per group.
  • $description (string) – Voucher internal description. Optional, but can be helpful for tracking.
Returns:

(array) Voucher description. The most interesting keys being: code and urls (which branches to redirect URL and popup URL).
Throws:

VingdException, Exception