Affiliate Services

From Apez

Jump to: navigation, search

Introduction

Contents

This document describes the affiliate services provided by Apez.biz including technical details about how to implement integration with your site. This page is aimed at anyone with a basic understanding of HTML web pages that wishes to use Apez's facilities to resell products from their own site, accept payments or show any of the various RSS feeds Apez provides.

For details on the web-services API that may be called directly from external servers or in-world LSL scripts, see the System API page. For general development information see the Development page.

Apez provides web-site pages that can handle product purchase and delivery (EzBuy), payment processing (DirectPay) and authentication/authorisation of users with in-world avatars. Using this affiliate interface can be as simple as adding an EzBuy link to an external HTML page.

Overview

Currently, Apez offers two web-based affiliate services, called EzBuy and DirectPay. EzBuy provides you with the capability to have users purchase products from your own web-site and have the payment and item delivery automatically handled by Apez (for a small commission). DirectPay allows you to have users make payments for any products or services (or anything) and Apez processes the payments. Which service is appropriate depends on your needs. Details of both services are given in the subsequent sections, but first an overview or how each works.

EzBuy

Suppose you have some in-world items you wish to sell from your own web-site with your own pages designs, pictures etc. To achieve this using EzBuy, you would follow these steps:

  • You'd first go to the Apez site and obtain an Apez.iServ, or compatible, item server. This is an in-world device in which you will put items you wish to have delivered.
  • Next, you go to the on-line Apez.vend service pages. Here you'll see a list of the items now in your inventory. After creating an initial product collection you can create a product for the things you want to sell from your web-site. Each product has a name, description, picture and other information, and is associated with a single item present in your inventory. Each product has a unique product id (prod_id).
  • Finally, for each product you want to sell from your site, you'll make a URL link that redirects the buyer to a special Apez purchase page, or alternatively paste in a small snippet of HTML form code (detailed below), which will submit a form to the purchase page. When the user clicks link or the form submit button on your site (i.e. the 'Buy' button) they'll be presented with the purchase page that you can customize. The form or URL includes parameters that you'll supply to control the Apez purchase processing page, such as the product id, a URL for your site's logo image, optionally an alternate product image and other information.

That's basically all there is to it. When the user clicks the 'Buy' button or link you've rendered next to the product details on your page, they'll be taken to a special Apez purchase page. This page will summarize the product information, offer a selection of their Apez.bank accounts to charge and display a final 'Buy' button. Once clicked, the buyer is charged, the item delivered and your account is credited, minus a small commission (currently 4%). If the user isn't logged in or hasn't yet signed-up for an Apez account, they'll be given an opportunity to do so before making the purchase.

DirectPay

Unlike EzBuy, DirectPay is only concerned with payment processing, not item delivery. Whereas EzBuy is passed a product id and looks up the price, description, picture etc. of a product from the Apez.vend database, DirectPay is more low-level. It also allows you to place a 'Buy' button on your site to accept payments, but it leaves the description, price, images etc. of what product or service you're selling completely up to you to provide via the form. To set-up DirectPay you'd follow these steps:

  • Take the provided snippet of HTML form code (below) and place it on the page where you wish to accept payments.
  • Then, you'd customize all the parameters to control the Apez payment processing page. These parameters include the name of what is being purchased, description, price, which user and Apez account to pay into, logo and product/service images to display etc.

When a visitor to your site clicks your form submit button, they'll be taken to the Apez payment processing page. From there, they will be presented with the summary information you provided and a 'Pay' button to finalize the payment. Your web server is notified of successful payment via a HTTP POST request to a URL you provide, which includes details of the payment.


Implementation

EzBuy

EzBuy is a simple cross-site payment and item delivery scheme where you put some special HTML form code or a URL link (described below) into your pages in order to provide a 'Buy' button or link for products. It could either be static HTML or dynamically generated HTML if you use server-side scripting to implement a shopping site. The order of events goes like this:

  1. The user browsing your site decides to purchase a product. They click on a button (say 'Buy'). The Buy button is a either form submit button that submits the form (via HTTP POST) to a special Apez EzBuy URL, or just a regular link (in which case the URL encodes the necessary parameters - which means the URL the buyer can see will be longer). The form or URL contains information you specify to identify the product.
  2. Next the user is presented with a purchase page (on the Apez site). From the product id you provide via a form variable, the Apez server looks-up the product information you've previously entered via the Apez.vend pages.
    • If they already have an account and are logged in to the Apez site, they'll immediately see a 'Buy' button. Otherwise, they'll be given a login prompt and instructions to sign-up for an account if necessary. The page will also show your logo, your site name, the item description and its cost (if not free).
  3. Once the user clicks 'Buy', funds are transfered from their Apez.bank account into the account you choose for your payments (which you associate with each product collection). The user is then shown a confirmation and a 'continue' button, which when clicked takes them back to your site (to any URL you specify). The item associated with the product is then delivered (via a message sent from the Apez server to the Apez.iServ containing your items in-world).

In the event that there is an item delivery problem (for example, if the SL Grid or region where your item server is located is down), the delivery is retried several times for up-to 30mins. If delivery is unsuccessful after 30mins, the buyer is refunded the purchase price and notified.

Setting up your item server

Grab an Apez item server (the Apez.iServ is available for free from the site). Rez it in a suitable permanent location. It must remain owned by you, so don't deed it to a group or it won't work. Next, place items you wish to have delivered into the contents tab of the item server. You can copy multiple item servers and rename them to keep your items organized. You can even place the same item in several item servers (place in seperate regions to guard against region outages or high-load, for example). Finally, use the menu or appropriate mechanism to have the item server update the Apez site. Now, the Apez.vend.inventory page will show a list of all the items you've placed in all the item servers you own. You can now create products and associate them with any of the items in your inventory. Each product belongs to a product collection, called anything you like. You can associate an Apez.bank account with the collection in which all sales funds will be deposited. You can also associate a group for management so that anyone in the group will be allowed to manage and edit the product details from the collection. The product information includes price, quantity available, short description (one line), long description and images. Currently, only one (default) image is utilized on the purchase page shown to the buyer.

An example

Suppose you want to create a static page for your site 'My online store' at my.site.com on which you wish to allow users to purchase a 'Virtual Widget', which you've previously set-up as a product with prod_id 1009. The HTML necessary to place a 'Buy' form button or link on your page is shown below. The form field variables are described next. Click here to see the result (shown below).

Image:EzBuyPurchasePage.jpg 

<p>Purchase the following item</p>
<p>Virtual Widget : $L 500</p>

<!-- Apez EzBuy form -->
<form action="http://www.apez.biz/modules.php?name=Vend&op=buy" method="post">
<input type="hidden" name="affiliateaction" value="ezbuy">
<input type="hidden" name="affiliate" value="My on-line store"> <!-- your site name here -->
<input type="hidden" name="affiliateimageurl" value="http://my.site.com/logo.jpg">
<input type="hidden" name="deliverto" value="Cenji Neutra"> <!-- optional, for gift delivery -->

<input type="hidden" name="buyer" value="Noob Neutra"> <!-- optional hint (to pre-fill login) -->
<input type="hidden" name="seller" value="Your Name"> <!-- optional, receiver of sales commission -->

<input type="hidden" name="doneurl" value="http://my.site.com/completed">
<input type="hidden" name="backurl" value="http://my.site.com/prodpage">
<input type="hidden" name="purchasenotifyurl" value="http://my.site.com/purchasecomplete">

<input type="hidden" name="prod_id" value="1009">

<input type="hidden" name="test" value="yes"> <!-- optional: yes FOR TESTING -->

<input class=button type="submit" value="Buy Now">
</form>

You can paste this HTML source into a page and try it with your browser. As long as you have the 'test' form field with the value 'yes' present, no actual funds will be transferred or products delivered, but the pages will still be displayed (and the specified server will be notified via the paymentnotifyurl - more on that below).

If you prefer to use the longer URL form, where the parameters are encoded in the URL, you could insert a 'buy' link like this: 

<a href="http://www.apez.biz/modules.php?name=Vend&op=buy&affiliateaction=ezbuy&affiliate=My+on-line+store&prod_id=1009
  &affiliateimageurl=http%3A%2F%2Fmy.site.com%2Flogo.jpg&&doneurl=http%3A%2F%2Fmy.site.com%2Fcompleted
  &backurl=http%3A%2F%2Fmy.site.com%2Fprodpage&purchasenotifyurl=http%3A%2F%2Fmy.site.com%2Fpurchasecomplete
  &test=yes">Buy<a>

Notice that any URL parameters that themselves contain characters having special meaning within a URL, must be URL encoded. For example, above, the doneurl parameter, when encoded, has "+" in place of space, %3A in place of ":" and %2F in place of "/". As you can see, this is a long URL to expose to the buyer in their browser address-bar. Hence, the form method is prefered where available.

Here is a description of the form fields you need to supply.

  • affiliateaction - [required] This should always have the value 'ezbuy'.
  • affiliate - [required] This is the name of your 'business' or service which is displayed to the user on the payment page. It can be anything you like.
  • affiliateimageurl [optional] If you have an logo image for your site, provide it's URL here and it will be displayed at the top of the payment page (in an <img> src attribute).
  • deliverto - [optional] If the avatar the item should be delivered to is different from the user making the purchase (for example, for gifts), this should be the avatar name or avatar key to deliver the item to. If an avatar name is used, the avatar must be known to the Apez database, or the delivery will fail. If an avatar key is supplied, it must simply be valid. If invalid, the delivery will silently fail.
  • backurl - [recommended] On the payment page presented to the user there will be a link to return to your site. Set this to a URL to which they can return (for example, the item page). The user may want to return if they changed their mind or don't have sufficient funds in their Apez.bank account. This is a regular link (HTTP GET).
  • doneurl - [recommended] Once the user has purchased the product they are shown a confirmation page containing a 'continue' button. The continue button will submit a form to the URL specified here (via HTTP POST from the user's browser). The POST will also include some of these form fields (as detailed below).
    • You should not use this as a payment confirmation, since any user can enter this URL into their browser.
  • purchasenotifyurl - [recommended] This is the most important URL - the one used to notify your server of a successful purchase. Once the payment has been processed, a HTTP POST is made to this URL from the Apez web server. The POST includes some of these form variables, plus some additional ones described below (such as confirmation number and a security hash you can check).
    • The page content returned to the Apez server by your server upon receiving this request should include the text "NOTIFY_OK" somewhere (i.e. a substring). Otherwise the page content doesn't matter, but it is best to return just that string or at lease only a small amount of HTML content, since you'll be using up bandwidth for nothing otherwise. If the Apez server doesn't get this text in the content you return, it will continue to repeat the notification until it does (up to some maximum number of retries). That way, you'll still get notifications even if your server goes down while a purchase is being processed.
  • prod_id - [required] This is the product id of the product being purchased. You can find the id of a product by using the 'edit' icon from the products page.
  • buyer - [optional] This is just a hint. If you have login information on your site, your server-side code may know the SL Avatar identify of the user browsing your pages. If so, you can supply it here and it will be used to auto-fill the Apez login username in case the user isn't logged in. The actual identify of the buyer will be determined via their Apez account and forwarded back to your site through notification.
  • seller - [optional] This is useful if you're planning to sell product from other merchants. Supply your avatar's name here to receive sales commission (for sales of products other than your own). Of course you can put anyone's avatar name here if you'd like to award the sales commission to them.
  • test - [required] This should be either the value 'yes' or 'no'. You can use the 'yes' value during integration and testing of EzBuy with your site. In this case the purchase will be 'simulated' but no funds will actually be transferred or items delivered. The purchase page will show a message indicating test mode. The confirmation for simulated test payment will always be '999999'.

Form variables passed to your web-server

When the user clicks the 'continue' button from the confirmation page, a form is submitted to the doneurl URL. The following variables from above are included in the request: affiliate, buyer, deliverto, buyer, and prod_id. Once the payment has been processed, a POST from an Apez web-server is made to the purchasenotifyurl. It includes these variables: affiliateaction, affiliate, paytoavatar, paytoacct, confirmation, buyerkey, buyer, prod_id, prodvalue, commissionRate, and test. Many of these are identical to those passes (see above), but some are unique (described below).

  • buyerkey - This is the SL 36-digit Second Life key associated with the avatar who made the purchase.
  • buyer - The name associated with the buyerkey.
  • paytoavatar - The name of the avatar who was payed for the purchase (the creator of the product collection the product belongs to).
  • paytoacct - The name of the account the the payment was made into (belonging to paytoavatar). This is associated with the product collection.
  • productvalue - The price paid for the product.
  • commissionRate - The rate of commission applied to the purchase (percent).
  • confirmation - An Apez transaction confirmation number. This is unique for every payment transaction.
  • hash - An MD5 hash you can use to verify that the POST really came from Apez. It is an MD5 hash of the string concatenation of the confirmation number and the MD5-hashed password of the paytoavatar's Apez account. For example, if the confirmation number was '1826473' and the paytoavatar's Apez password is 'MyPassword', then the hash value will be MD5('1826473'+MD5('MyPassword')) == MD5('182647348503dfd58720bd5ff35c102065a52d7') == 'f909d53613986fb6cb8d42e958f23b2e'.

Your server-side script code will know both the confirmation number and your Apez account password. So, if you perform this computation and get the same result as passed in hash, you can be sure the notification POST came from Apez (unless someone else obtains your password!).

DirectPay

DirectPay is a simple cross-site payment scheme where you can put some special HTML form code (described below) into you pages in order to provide a 'Buy' button for items or services. It could either be static HTML or dynamically generated HTML if you use server-side scripting to implement a shopping site.

The basic order of events goes like this:

  1. The user browsing your site decides to purchase an item/service, make a donation or whatever. They click on a button (say 'Buy'). The Buy button is a form submit button that submits the form (via HTTP POST) to a special Apez DirectPay URL. The form also contains extra information you specify as needed for payment processing.
  2. Next the user is presented with a payment page (on the Apez site). If they already have an Apez.bank account and are logged in to the Apez site, they'll immediately see a 'Pay' button. Otherwise, they'll be given a login prompt and instructions to sign-up for an account if necessary. The page will also show your logo, your site name, the item description and its cost.
  3. Once the user clicks 'Pay', funds are transfered from their Apez.bank account into the account you choose for your payments. The user is then shown a confirmation and a 'continue' button, which when clicked takes them back to your site (to any URL you specify).
  4. After the Apez server processes the payment (usually a few seconds), it notifies your server by POSTing to a URL you provide. The HTTP POST contains all the information you may need to process the order (such as the buyer avatar, the item id you gave, your transaction id, an Apez transaction confirmation number, the amount, etc.)

An example

Suppose you want to create a static page for your site 'My online store' at my.site.com on which you wish to allow users to purchase a 'Virtual Widget'. The HTML necessary to place a 'Buy' button on your page is shown below. The form field variables are described next. 

<p>Purchase the following item</p>
<p>Virtual Widget : $L 500</p>

<!-- Apez DirectPay form -->
<form action="http://www.apez.biz/modules.php?name=Bank&op=payment" method="post">
<input type="hidden" name="affiliateaction" value="directpay">
<input type="hidden" name="affiliate" value="My on-line store">
<input type="hidden" name="affiliateimageurl" value="http://my.site.com/logo.jpg">
<input type="hidden" name="paytoavatar" value="ImAn Avatar">
<input type="hidden" name="paytoacct" value="working">
<input type="hidden" name="buyer" value="Sato Neutra"> <!-- optional hint -->

<input type="hidden" name="doneurl" value="http://my.site.com/completed">
<input type="hidden" name="backurl" value="http://my.site.com/itempage">
<input type="hidden" name="paymentnotifyurl" value="http://my.site.com/transactioncompleted">

<input type="hidden" name="item" value="Virtual Widget">
<input type="hidden" name="itemid" value="1234">
<input type="hidden" name="itemvalue" value="500">
<input type="hidden" name="transid" value="123456789">

<input type="hidden" name="test" value="yes"> <!-- optional: yes FOR TESTING -->

<input class=button type="submit" value="Buy">
</form>

You can paste this HTML source into a page and try it with your browser. As long as you have the 'test' form field with the value 'yes' present, no actual funds will be transfered, but the pages will still be displayed (and the specified server will be notified via the paymentnotifyurl - more on that below).

Here is a description of the form fields you need to supply.

  • affiliateaction - [required] This should always have the value 'directpay'.
  • affiliate - [required] This is the name of your 'business' or service which is displayed to the user on the payment page. It can be anything you like.
  • affiliateimageurl [optional] If you have an logo image for your site, provide it's URL here and it will be displayed at the top of the payment page (in an <img> src attribute).
  • paytoavatar - [required] This is the name of the SL avatar that will be payed when the item is purchased. The avatar must have an Apez account.
  • paytoacct - [required] The Apez.bank account into which payment should go. Every Apez user has the default 'working' account, but you can create extra accounts on the bank page.
  • buyer - [optional] This is just a hint. If you have login information on your site, your server-side code may know the SL Avatar identify of the user browsing your pages. If so, you can supply it here and it will be used to auto-fill the Apez login username in case the user isn't logged in. The actual identify of the buyer will be determined via their Apez account and forwarded back to your site through notification.
  • backurl - [required] On the payment page presented to the user there will be a link to return to your site. Set this to a URL to which they can return (for example, the item page). The user may want to return if they changed their mind or don't have sufficient funds in their Apez.bank account. This is a regular link (HTTP GET).
  • doneurl - [required] Once the user has payed for the item they are shown a confirmation page containing a 'continue' button. The continue button will submit a form to the URL specified here (via HTTP POST from the user's browser). The POST will also include some of these form fields (as detailed below).
    • You should not use this as a payment confirmation, since any user can enter this URL into their browser or use tools or code to perform a POST to your server. You shouldn't deliver the item (or whatever) until your server received a POST from the paymentnotifyurl.
  • paymentnotifyurl - [required] This is the most important URL - the one used to notify your server of a succesful transaction. Once the payment has been processed, a HTTP POST is made to this URL from the Apez web server. The POST includes some of these form variables, plus some additional ones described below (such as confirmation number and a security hash you can check).

The page content returned to the Apez server by your server upon receiving this request should include the text "NOTIFY_OK" somewhere (i.e. a substring). Otherwise the page content doesn't matter, but it is best to return just that strng or at lease only a small amount of HTML content, since you'll be using up bandwidth for nothing otherwise. If the Apez server doesn't get this text in the content you return, it will continue to repeat the notification until it does (up to some maximum number of retries). That way, you'll still get notifications even if your server goes down while a payment is being processed.

  • item - [required] The item (or service) name the user is purchasing. This is displayed on the payment page for the user. It may be anything you like.
  • itemid - [required] This isn't displayed for the user, but it is returned to your server via both the doneurl and paymentnotifyurl. It can be anything; perhaps corresponding to your site's internal database ID for the item.
  • itemvalue - [required] The cost of the item (In Linden Dollars).
  • transid - [required] This is your site-specific transaction ID. It can be anything you require and is passed back to your server via the doneurl and paymentnotifyurl. If you are dynamically generating the item pages using server-side scripting, it is a good idea to make this unique for each page display.
  • test - [required] This should be either the value 'yes' or 'no'. You can use the 'yes' value during integration and testing of DirectPay with your site. In this case the payment will be 'simulated' but no funds will actually be transfered. The payment page will show a message indicating test mode. The confirmation for simulated test payment will always be '999999'.

Form variables passed to your web-server

When the user clicks the 'continue' button from the confirmation page, a form is submitted to the doneurl URL. The following variables from above are included in the request: affiliate, paytoavatar, paytoacct, buyer, itemid, itemvalue, and transid. Once the payment has been processed, a POST from an Apez web-server is made to the paymentnotifyurl. It includes these variables: affiliate, paytoavatar, paytoacct, buyer, itemid, itemvalue, transid, and test. Additionally, these extra variables are passed:

  • buyerkey - This is the SL 36-digit Second Life key associated with the avatar who made the purchase.
  • confirmation - An Apez transaction confirmation number. This is unique for every payment transaction.
  • hash - An MD5 hash you should use to verify that the POST really came from Apez. It is an MD5 hash of the string concatenation of the confirmation number and the MD5-hashed password of the paytoavatar's Apez account. For example, if the confirmation number was '1826473' and the paytoavatar's Apez password is 'MyPassword', then the hash value will be MD5('1826473'+MD5('MyPassword')) == MD5('182647348503dfd58720bd5ff35c102065a52d7') == 'f909d53613986fb6cb8d42e958f23b2e'.

Your server-side script code will know both the confirmation number and your Apez account password. So, if you perform this computation and get the same result as passed in hash, you can be sure the notification POST came from Apez and go ahead and deliver the item to the user (unless someone else obtains your password!). Another extra check that can be made is to verify that the POST request came from an IP address that resolves to the apez.biz domain (though even a clever cracker could spoof the identify of their POST requests, so it isn't foolproof).

Retrieved from "http://www2.apez.biz/wiki/Affiliate_Services"
Personal tools

A d v e r t i s m e n t