CarrotPay API Specification
Document v1.4 WebSite v7.0.0 Release: 15 Feb 2016
Copyright © 2009 - 2016 RMP Protection Limited
1
Table of Contents
1 Introduction 2 Carrot Object Function name: Carrot.pay() Request payment with WebCoins and SiteCoins Accepting SiteCoins for a split payment Price Attribute WebPurse Position Function name: Carrot.purse() Display available funds Get the user’s ID SiteCoin Offers WebPurse Position Function name: Carrot.get_id() Function name: Carrot.DRM() DRM General Process DRM Template in JSP
1 Introduction This specification documents the CarrotPay library which allows you to simply integrate CarrotPay payments for any web page including pages with embedded Flash applications. You will need to register as a CarrotPay merchant before you can actually use this library to request payments. There are actually three libraries available; carrot.js, Carrot.as and carrot-v-1-5.as. carrot.js must be placed somewhere in the html host page and carrot-v-1-5.as and Carrot.as are ActionScript libraries that allow Flash applications to easily communicate with the CarrotPay service through the carrot.js library. Carrot.as is compatible with ActionScript 3.0 projects and carrot-v-1-5.as is compatible with ActionScript 2.0 projects. Each library provides an identical API so only the JavaScript interface is described within this document. For those people who are specifically interested in writing Flash applications please refer to the “Flash Integration Guide”. General Process A page designer must arrange to call one of the Carrot API functions and this will cause the consumer's WebPurse to be displayed directly on the host html page. The specific function and parameters of the call will determine what exactly is displayed to the user. For example, to start a payment request you need to call something like: Carrot.pay({merchant:'
',price:'0.5:USD',description:'A Book',return_url:''});
2
This will cause the user's WebPurse to be displayed and to prompt for confirmation of the payment of US$0.5 for 'A Book'. If the use clicks confirm, USD0.5 is transferred from the user to the merchant and the browser is made to call the return_url. The return_url will normally cause the user to immediately receive the item that has just been purchased or may be used to add points to an account etc.
2 Carrot Object The CarrotPay API is expressed through a single JavaScript object called “Carrot”. Carrot is know as the namespace, because each function is pre-fixed with the word “Carrot”. The core payment functionality is provided by a single method pay(), taking a single JavaScript object as a parameter with named members. The call to Carrot.pay() may be triggered through a “javascript:” URL on a link, a button, an image, an onclick() handler, passed through an ActionScript call or by any other JavaScript means. The carrot JavaScript library must be included on your page using the following script. For HTTP pages: <script src="http://cdn.carrot.org/js/carrot.js">
For HTTPS pages: <script
src="https://cdn.carrot.org/js/carrot.js">
Function name: Carrot.pay() Overview A function that starts a payment request. On successful completion, a processed return_url will normally be called by the browser.
Request payment with WebCoins and SiteCoins This function requires the following parameters; merchant, description and price. The return_url is also normally required unless you include a callback function. Parameters
Name
Description
3
Examples
Type
merchant
(Required) The ID allocated by CarrotPay
merchant: "BBRV-JZHS-RQGZ-WLVL"
String
description
(Required) A UTF-8 encoded string in the user's preferred language.
description: "HD Wallpaper"
String
(Required) The price to be charged.
price: "0.20" //uses the default currency and merchant
NOTE: When computing the payment hash for a return_url, the price field used in the calculation must be exactly as it appears in this field. Ensure there are no leading or trailing spaces and '0' characters are significant.
price: ".20:USD" //uses the default merchant
price
NOTE: See the Price Attribute section for more examples return_url
(Required) A string that normally specifies the address of a server function or the name of a file. You may include anything you wish in this string including product codes, user ids and security elements. Once payment is successful the browser will call this url.
description: "名称: 云彩"
String
//fully specified price price: ".2:USD:BBRV-JZHS-RQGZ-WLVL"
NOTE: When the merchant is explicitly specified (as here), it also means that ‘credit’ is being offered (see the Merchant guide for details). return_url: "http://www.site.com/img/item_[item].png"
String
return_url: "http://www.site.com/fn.php?a=prod&h=[prod]"
NOTE: If you use our 'protected link' format, CarrotPay will process this string and replace everything between ' [ ' and ' ] ' with a cryptographic hash so that you can verify that the payment is genuine see the CarrotPay-Script Integration Guide. callback
(Optional) A JavaScript function to be called after a successful payment with the processed return_url as a parameter. NOTE: When callback is specified, the browser no longer calls the return_url automatically. ActionScript: If callback is undefined Carrot.url(result) will be called. This defaults to getURL(result) unless overridden.
failure_url
(Optional) A URL to be fetched by the browser if the payment is refused or fails for any reason. A 'reason' parameter is added to the URL containing the reason for failure. ActionScript: If this is undefined, on return from a failed payment Carrot.failure(reason) will be called. This defaults to trace(reason) unless overridden.
4
//This example is using JQuery callback: function(result) { //Load the returned result into an iframe $("iframe#myTarget").attr("src",result); }
Function
failure_url: "http://www.carrot.org/fail.php"
String
failure_callback
(Optional) A function to be called on failure to complete a payment. A reason parameter is also passed to the function. The failure reasons are: "cancelled" The user cancelled the payment "system" A system failure was encountered
failure_callback: function(reason) { if (reason=="cancelled") { alert("Transaction Cancelled"); //handle other failure reasons here... } }
Function
domain
(Optional) Merchant's domain, if return_url NOT provided.
domain: "yourdomain.com"
String
hidden
(Optional) If set, return_url is loaded into a hidden iframe.
hidden: true
Boolean
passThrough
(Optional) Specifies that a Merchant wishes the user experience to favour direct use of an external payment gateway such as Sofort Internet Banking or Bitcoin. In specifying this option the Merchant agrees to pay any direct fees that the payment gateway may require.
passThrough: 1
Numeric
email: "[email protected]"
String
NOTE: As of the time of writing, the current fee is EUR0.25. email
(Optional) The customer’s email address if known.
NOTE: The customer will have the opportunity to enter or edit their email address within CarrotPay, but if they have already provided their email address to you, it is good to pass it to CarrotPay as it’s less typing for the customer and demonstrates a link between you the merchant and the CarrotPay service. contactEmail
(Optional) An email address that you would like customers to use for customer enquiries. If not provided CarrotPay will use the email address provided during account registration.
contactEmail: "[email protected]"
String
alert
(Optional) Specifies that the merchant would like to be informed once a payment has successfully completed. This will cause a simple text email message to be sent to the Merchant’s registered email address. The email message will have a subject of “ CarrotPay sales alert” and the body will contain a simple string such as: “Product 1234 | 10:EUR | [email protected] | lsvqgrkhbkbkwgwr”
alert: "email:Product 1234"
String
JavaScript Syntax
5
NOTE: The message must start with the string “email:”, which should be followed by information that may help you identify the payment and the customer. The email body will also contain the price paid, the buyer’s email address and the transaction id that can be matched with the transaction id in the Control panel statement. In the future this function may be extended to include other communications channels such as SMS.
Carrot.pay({ merchant: "BWRV-JZHS-RQGZ-WLVL", //Merchant ID as allocated by CarrotPay registration price: "0.5:EUR", description: "A cool magazine", return_url: "http://www.site.com/mags/cool22_[cool22].pdf" });
In the example above a merchant is selling a magazine from the 'mags' directory of 'www.site.com'. The filename of the pdf file in this example is obfuscated so as to add an element of protection. The return_url is using the CarrotPay 'protected link' format and so will be processed by CarrotPay and the portion containing “[cool22]” will become something like “bhqllzvc”. The resulting pdf file will be fetched from http://www.site.com/mags/cool22_bhqllzvc.pdf. For an in-depth discussion on the use of the protected link technique see the CarrotPay-Script Integration Guide.
Accepting SiteCoins for a split payment The Carrot.pay() function normally accepts both WebCoins and SiteCoins but if the price parameter includes a merchant ID other than the ID in the merchant parameter (i.e. it’s a split payment), you must also include a price_sig parameter to indicate that you acknowledge that some SiteCoins may be sent to another Carrot user. This is to prevent an attack which could result in the attacker obtaining many of your SiteCoins. Here is an example of a price that includes a split payment : price : "0.20:EUR:BMWM-VJQB-LVJC-HKQW+1.80:EUR"
This tells CarrotPay to take a total of EUR 2 and credit the site merchant with EUR 1.80 and credit EUR 0.20 to the ID BMWM-VJQB-LVJC-HKQW. We recommend that you place all split payment elements before your own element (i.e. 0.2 before 1.8 in the example above), because when funds are taken from the WebPurse, SiteCoins will be used first before WebCoins and we assume you would rather allocate SiteCoins to the other merchant and retain the WebCoins (if any), yourself. Parameters
Name
Description
Examples
Type
merchant
(Required) The ID allocated by CarrotPay
merchant: "BBRV-JZHS-RQGZ-WLVL"
String
price
(Required) The price to be charged.
//split payments price:"0.2:USD:BBRV-JZHS-RQGZ-WLVL+1.80:USD"
String
NOTE: When computing the payment hash for a return_url, the price field used in the calculation must be exactly as it appears in this field. Ensure there are no leading or trailing spaces and '0' characters are significant.
6
NOTE: The price_sig parameter is only required when; ●
The price includes a merchant ID other than the merchant referenced in the merchant parameter
●
When SiteCoins are to be accepted.
NOTE: See the Price Attribute section for more examples price_sig
(Required) A cryptographic hash that is used as a signature to prevent fraudulent payments when a merchant is accepting SiteCoins for specific payments. Each signature will be unique for each merchant and price, see the PHP Example in CarrotPay-Script Integration Guide (chapter 6 Preventing Fraud) on how to calculate the p rice_sig (cryptographic hash). When following the examples given, ensure that when calling the carrotpay_hash_word() function the $ word, $ price and $ seed parameters are assigned with the variables as seen in the table below
price_sig:"wjvmhdpj"
String
//PHP $word = "price"; $price = $price; $seed = $hash_seed; //The merchant $hash_seed can b e found in the CarrotPay Account Control Panel > Under t he “Account secrets” panel > expand Reveal secrets
JavaScript Syntax Carrot.pay({ merchant: "HWVV-JZLL-RRGZ-VLVL", price: "0.05:EUR:BBRV-JZHS-RQGZ-WLVL+0.45:EUR", price_sig: "wpvmhdpj", description: "Cool mag", return_url: "http://www.site.com/mags/cool22_[cool22].pdf" });
In the above example a merchant with the ID HWVV-JZLL-RRGZ-VLVL is selling a magazine for EUR0.5 and is sharing 10% of the revenue with a share-n-earn micro-affiliate (with
7
ID BBRV-JZHS-RQGZ-WLVL). The pdf magazine is stored in the 'mags' directory of www.site.com with an obfuscated filename. In this case the merchant also wishes to accept his SiteCoins for the payments and so requires the price_sig parameter to be included. The obfuscated filename adds the minimum level of content security that CarrotPay offers. The return_url is using the CarrotPay 'protected link' format and so will be processed by CarrotPay and the portion containing “[cool22]” will become something like “bhqllzvc”. The resulting pdf file will be fetched from http://www.site.com/mags/cool22_bhqllzvc.pdf. For an in-depth discussion on the use of the protected link techniques see the CarrotPay-Script Integration Guide.
Price Attribute The price attribute sets the total amount to be charged for the item being sold. The amount to be charged may be described as simply as a value (e.g. 10), or may include the currency of the charge (e.g. 5.0:USD). These simple variants express a specific fixed value and are by far the most commonly used examples. However, it is sometimes desirable to request a payment in a more flexible way. For example you may wish to offer the option of a small discount in return for redeeming some Carrot loyalty points. Alternatively, you may wish to reward a micro-affiliate at the point of sale for introducing a buyer, in which case you will need to set the price as a split-payment (see below). Finally, you may wish to accept Bitcoin payments but at the same time fix the price to a real world currency such as GBP. All these things may be achieved by formatting the Price attribute in various ways as we shall show.. The price attribute is made up of one or more PaymentOptions each separated by a semi-colon ( ; ). A PaymentOption is made up of one or more PriceElements each
separated by a plus ( + ). A PriceElement is made up of a Value and an optional Currency and Account field which are each separated by a colon ( : ). With combinations of PatmentOptions and PriceElements it is possible to construct price attributes to meet a wide range of requirements. The most common use of multiple PriceElements in a single PaymentOption is to introduce a split payment or to offer a discount when loyalty points are redeemed. The most common use of multiple PaymentOptions in a price attribute is to provide an alternative when offering a discount. In this case the discounted PriceElement is put in the price attribute before (i.e. to the left of), any non-discounted option. In this way CarrotPay will select the discount option if the user has the correct loyalty points in their purse, but will fall-back to selecting the full payment if the loyalty points are not available. A more unusual (but still legal), use of multiple PaymentOptions is to offer to sell in one of a number of real currencies (e.g. 1.0:GBP;1.5:USD). Although possible, this is normally unnecessary and is discouraged because it’s likely to be less clear to the buyer exactly what the sale price is. A variation on this is to use the ( as ), operator within the Currency part of PriceElement (e.g 5:GBPasmXBT). This declares that a Merchant wishes to charge the buyer the Bitcoin equivalent of GBP5.0. When a sale is made using such a PriceElement the Merchant will receive into their account Bitcoin having the value of GBP5.00 at the time the sale was made. NOTE: CarrotPay will automatically convert the buyer’s funds into the payment currency at the prevailing exchange rate and so there is no actual need to request multiple real currencies in any single price attribute. Value
The decimal value to be charged.
NOTE: Ensure there are no leading or trailing spaces around the value. Also leading or trailing zero ( 0 ) characters are significant. NOTE: Although there is no specific maximum limit for the value there is a limit to the
8
Currency
Format examples:
1
Min value:
0.001
Max value:
No practical limit
1.00
1.000
0.123
.123
The currency code of the value. Examples of ISO currencies: Examples of virtual currencies:
Account
1.0
CNY
#CRT
amount that may be paid using real world currencies within a CarrotPurse. This limit is set by the FSA and is currently EUR 150 or about USD 200. For Bitcoin and virtual currencies no such limit applies.
NOTE: If a currency is not specified, the default currency from the CarrotPay Account Control Panel will be used.
EUR
GBP
#INT
HKD
#BID
USD
mXBT
The account ID of the recipient who will receive this portion of the payment. We call this a split-payment when the ID is different from the Merchant attribute and a credit-payment when it is the same.
NOTE: For Bitcoin, CarrotPay uses the extended ISO currency code of XBT and not the older BTC code that is quite common. However, as a Bitcoin has a much larger numerical value than say GBP of EUR, Bitcoin is always represented as it’s milli value within CarrotPay (i.e. mXBT).
NOTE: If an account ID is not specified, the recipient will default to account specified in the Merchant attribute. NOTE: Split payments are a low overhead way to automatically share revenue with an affiliate. Split payments should be used in conjunction with share-n-earn and may also use at times when you want to make a payment to a customer without the overhead of a complex back-end accounting system. NOTE: Credit payments are used when a Merchant is willing to provide their product immediately but receive payment at a future time. This can be helpful during the selling process when a user does not have sufficient funds to pay at the point of the sale.
PriceElement
A string containing at least a Value with an optional Currency and Account field each separated with by a colon ( : ). The colon is used as a FIELD SEPARATOR character.
NOTE: If an Account is specified a Currency must also be present.
PaymentOption
A string containing one or more PriceElements each separated by a plus ( + ). The plus is an AND operator and indicates that each PriceElement is added together to form a total price.
NOTE: When presented to a buyer, PriceElements of the same currency are added and displayed as a single value. For example 0.8:USD+0.2USD will be presented as “US $1”. However, unlike currencies will be presented as separate value. For example 1:USD+20:#CRT will be presented as “US $1 + Carrots 20”.
9
NOTE: The plus operator has two main uses; 1) To offer loyalty discounts (e.g. 0.8:USD+10:#CRT), and 2) to set up a split-payment (e.g. 0.2:USD:HWVV-JZLL-RRGZ-VLLV+0.8:USD). NOTE: When offering loyalty discounts, it’s always a good idea to include a non-discount price in case the buyer doesn’t have any loyalty points to user. Here’s an example of requesting a USD1.0 payment with a 10% discount when 10 Carrots are redeemed (e.g. “0.9:USD+10#CRT;1.0:USD”). price
A string containing one or more PaymentOptions each separated by a semicolon ( ; ). The semicolon is an OR operator and indicates that any one of the PaymentOptions may be used to satisfy the payment.
NOTE: PaymentOptions within a price are always evaluated from left to right. That means CarrotPay will attempt match funds against each PaymentOption starting with the first (i.e. left most), option and proceeding to the next and the next until an option can be satisfied with the funds available. Once a satisfied option is found, further options will be ignored. This means that you should take care when setting multiple options where one option may preclude another option from ever being considered (see examples below).
Some example Assume a merchant has ID HWVV-JZLL-RRGZ-VLLV and a default currency of USD and wishes to charge $10, $1.5 and $0.01 for three different items, the following price field specifications may be used: price : "10" //Sale of $10 - uses integer notation and the default currency and merchant id price : "10.000" //Sale of $10 - uses decimal notation and the default currency and merchant id price : "10.0:USD" //Sale of $10 - uses decimal notation and explicit currency but default merchant id price : "10:USD:HWVV-JZLL-RRGZ-VLLV" //Sale of $10 explicitly specified //Sale of $1.5 price : "1.5" or "1.50" or "1.500" or "1.5:USD" or "1.5:USD:HWVV-JZLL-RRGZ-VLLV" //Sale of $0.01 price : ".01" or "0.01" or "0.010" or "0.01:USD" or "0.01:USD:HWVV-JZLL-RRGZ-VLLV"
Assume the same merchant as above wishes to sell a 50 cent item and offer a 5% discount when 3 Carrots are redeemed: This requires a combination of PaymentOptions and PriceElements price: "0.475+3:#CRT;0.5" This tells CarrotPay to take a total of US$0.475 and 3 Carrots and credit the merchant with the USD and the #CRT OR take US$0.5 if the buyer
10
doesn’t have at least 3 Carrots in their WebPurse.
If a Merchant wants to receive Bitcoin for some reason but has real world costs that they wish to cover, they can fix the real world sale price but have that price presented as a fluctuating Bitcoin value. Fix the sale price as EUR 3.50 and have it presented as a value that fluctuates according the the EUR to Bitcoin exchange rate. price: "3.5:EURasmXBT" this will be presented in the WebPurse something like this “mBTɃ 8.799”
The following example is just about as complicated an example as you are likely to see in actual use. It is a payment for EUR1 with a share-n-earn 20% split payment and 10% discount offer for 10 Carrots. This tells CarrotPay to take a total of € 0.80 and 10 C arrots a nd credit the merchant with id B MWM-VJQB-LVJC-HKQW with 20% of the funds received OR take a total of €1.0 if the u ser doesn’t h ave 10 C arrots and credit the merchant w ith id BMWM-VJQB-LVJC-HKQW with ¢20. price: "0.16:EUR:BMWM-VJQB-LVJC-HKQW+0.64:EUR+2:#CRT:BMWM-VJQB-LVJC-HKQW+8:#CRT;0.2:EUR:BMWM-VJQB-LVJC-HKQW+0.8:EUR"
WebPurse Position The WebPurse can be positioned on a page using the optional parameters from the table below Parameters
Name
Description
Example
Type
element_id
(Optional) Positions the WebPurse iframe by centring it over the specified html element.
element_id: "contents"
String
purse_position: {top:100,left:200}
Object
NOTE: Overrides all other positioning. DesktopPurse: If a DesktopPurse is active this will have no effect. purse_position
(Optional) Position the WebPurse on the page with an offset from the top-left corner. The units are pixels. NOTE: When this parameter is not used, the default location will be the centre of the page or element_id (if provided). If Desktop Purse is used this will have no effect.
11
hourglass_position
(Optional) Position the Carrot hourglass on the page with an offset from the top-left corner. The units are pixels.
hourglass_position: {top:100,left:200}
Object
NOTE: When this parameter is not used, the default location will be the same as of the purse_position. Javascript Syntax Carrot.pay({ merchant: "HWVV-JZLL-RRGZ-VLVL", price: "0.45:EUR+0.05:EUR:BBRV-JZHS-RQGZ-WLVL", price_sig: "wpvmhdpj", description: "Cool mag", return_url: "http://www.site.com/mags/cool22_[cool22].pdf" element_id: "contents", hourglass_position: {top:100,left:200} });
Function name: Carrot.purse() Overview A function that opens a user's CarrotPurse (WebPurse or DesktopPurse) directly on your site or on the user’s computer. This normally displays their available funds and allows them to view their SiteCoins, add money if required and other house-keeping functions. This function may be called with no parameters, null or with an object containing function specific parameters.
Display available funds No parameters are required but it is recommended that you always include your Merchant ID. When a Merchant ID is included, the value of any SiteCoins are added to the available funds. SiteCoins are issued by and are keyed to specific Merchant ID’s. Parameters
Name
Description
12
Examples
Type
merchant
(Recommended) The Merchant ID allocated by CarrotPay
merchant: "VVRV-JZHS-RQGZ-WLVL"
String
JavaScript Syntax Carrot.purse({ merchant: "VVRV-JZHS-RQGZ-WLVL" });
Get the user’s ID
This function may be used to obtain the user’s CarrotPurse ID. It differs from the Carrot.get_id() function in that it allows the user to login if they are not already logged into their WebPurse. Requires the get_id and callback parameters.
Parameters
Name
Description
Examples
merchant
(Optional) The Merchant ID allocated by CarrotPay
merchant: "VVRV-JZHS-RQGZ-WLVL"
get_id
(Required) Return the purse id (without displaying), if known OR display login and return id when known OR null if login fails.
get_id: true
Boolean
callback
(Required) A function to be called when the purse id is known OR null if not.
callback: function(id) { //handle id here }
Function
JavaScript Syntax Carrot.purse({ get_id: true, callback: function(id) { // handle id here } });
13
Type
SiteCoin Offers SiteCoins represent a promise that a site will honour a request for redemption against some or all of its products and services. A SiteCoin may be thought of as a managed e-coupon for a fixed currency and monetary value (including virtual currencies such as Carrots). SiteCoins may only be redeemed when a payment is requested by the same merchant that issued them and are typically used for marketing campaigns to encourage people to try out new products or services. The value of all SiteCoins issued by a particular merchant will be reflected in the user’s available funds whenever the ‘merchant’ parameter is added to the Carrot.purse() call (e.g. Carrot.purse({merchant: "VVRV-JZHS-RQGZ-WLVL"});). In addition to SiteCoins having a currency and a value, they also have an ‘expiry date’ and an optional ‘validFrom date’. If the validFrom parameter is provided with a future date, the SiteCoin may still be accepted immediately but it can only be spent after the date indicated. When validFrom is omitted the SiteCoin can be accepted and spent immediately. Once a WebPurse contains a given SiteCoin, it may split the coin to make a payment and retain the balance. If a coin expires before being spent, that coin will be deleted without warning and its value returned to the merchant who issued it. SiteCoin Offers are the mechanism by which WebPurse users may obtain SiteCoins. Offers are named and once an offer with a given name has been accepted, that offer has a fixed currency that cannot be changed (although the value may vary for each subsequent call). As mentioned above, the most frequent use of SiteCoin offers is for marketing campaigns but they may also be used to issue refunds or to make individual awards. When used to make a specific one-time offer (or refund), the ‘offer_private’ parameter must be used. This parameter alters the normal semantics of an offer from ‘once only for any number of users’ to ‘once only’. This is achieved by allowing the offer to be accepted within a small window of time and then only once. For this to work the offer_private parameter contains a time stamp which must be within +/- 30 minutes of the CarrotPay server’s clock. Parameters
Name
Description
Example
Type
merchant
(Required) The Merchant ID allocated by CarrotPay using the standard AAAA-BBBB-CCCC-DDDD format.
merchant: "VVRV-JZHS-RQGZ-WLVL"
String
offer_id
(Required) A unique string representing a SiteCoin Offer. Max length 255 characters. Required: only when issuing a SiteCoin Offer.
offer_id: "1112" offer_id: "introductory offer"
String
offer_price
(Required) The value and currency of a SiteCoin Offer.
offer_price: "2.00:USD" offer_price: "10:#CRT"
String
expiry
(Required) The date and time that this SiteCoin will expire.
//Greenwich Mean Time expiry: "2013-02-26T23:20:01+00:00"
String
There are two options for setting the expiry date: ● A formatted future date and time in ISO8601 date format.. NOTE: The time requires a timezone setting. ○ General form “yyyy-MM-ddTHH:mm:ssz”
14
//Central Standard Time expiry: "2012-03-26T17:20:13+05:00" //minutes expiry: "10080" //seven days
○ ○ ●
For Java use javax.xml.bind.DatatypeConverter.printDateTime(c) For PHP use date(“c”)
A period in integer minutes from the date and time that the Offer is accepted.
NOTE: Offers will be rejected if the date and time has already expired or if the format of the date cannot be recognized or if the period is less than 5 mins. validFrom
(Optional) The date and time that this SiteCoin can start to be used. There are two options for setting the validFrom date: ● A formatted future date and time in ISO8601 date format.. NOTE: The time requires a timezone setting. ○ General form “yyyy-MM-ddTHH:mm:ssz” ○ For Java use javax.xml.bind.DatatypeConverter.printDateTime(c) ○ For PHP use date(“c”) ●
//Greenwich Mean Time validFrom: "2013-02-26T23:20:01+00:00"
String
//Central Standard Time validFrom: "2012-03-26T17:20:13+05:00" //minutes validFrom: "10080" //seven days
A period in integer minutes from the date and time that the Offer is accepted.
NOTE: If supplied, the date and time must be prior to the value of the expiry date parameter. If this parameter is NOT supplied, the SiteCoin will be valid from the time the offer is accepted. sig
(Required) A cryptographic hash that is used as a signature to prevent fraudulent issuing of SiteCoins. Each signature is unique for each merchant, see the PHP Example in CarrotPay-Script Integration Guide (chapter 6 Preventing Fraud) on how to calculate the sig (cryptographic hash) and ensure that when calling the carrotpay_hash_word() function the $ word, $ price and $ seed parameters are assigned with the variables as shown in the table below //PHP //’validFrom’ with its separating space is optional //’offer_private’ with its separating space is only included in the hash calculation for private offers (see below) $word = $merchant." ".$offer_id." ".$offer_price. [" ".$offer_private.][" ".$validFrom.]" ".$expiry; $price = $offer_price;
15
sig: "wjvmhdpj"
String
$seed = $hash_seed; //The merchant $hash_seed c an be found in the CarrotPay Account Control Panel > Under the “ Account secrets” panel > expand Reveal secrets
offer_private
(Optional) A time stamp indicating the time at which this offer was made. Use of this parameter indicates that this is a one-time offer. The time stamp must be accurate to within +/- 30 minutes of the CarrotPay server and the user must accept the offer promptly otherwise it will be rejected.
//Hong Kong Time offer_private: "2012-01-19T10:10:11+08:00"
● A formatted future date and time in ISO8601 date format.. NOTE: The time requires a timezone setting. ○ General form “yyyy-MM-ddTHH:mm:ssz” ○ For Java use javax.xml.bind.DatatypeConverter.printDateTime(c) ○ For PHP use date(“c”) callback_url
(Optional) A callback_url that will be called by CarrotPay when this offer has
been accepted. This is most useful when a merchant wishes to limit the number of times an Offer may be accepted. The callback_url has the following parameters attached: (offer_id, count, currency, accepted_value, spent, latest_expiry, h) Here’s an example of how this callback_url may be called for the 99th person who accepts the offer: https://www.yoursite.com/newoffer?offer_id=1112&count=99¤cy =USD&accepted_value=198.0&spent=42.36&expired=67.999&latest_expir y=2013-02-26T23:20+00:00&h=zdrqqnbp
The value of the callback_url parameter h is a cryptographic hash and is made available to the merchant to allow them to detect fraudulent use of the callback_url by an attacker. The hash may be calculated by your server using the PHP code example described in CarrotPay-Script Integration Guide (chapter 6 Preventing Fraud) and when the c arrotpay_hash_word() function is called, the $ word, $price and $ seed parameters are assigned in the manner shown below:
16
callback_url: "https://www.yoursite.com/newoffer"
String
//PHP $word = $offer_id." ".$count." ".$currency." ".$accepted_value." ".$spent." ".$expired." ".$latest_expiry; $price = ""; $seed = $hash_seed; //The merchant $hash_seed can be found in the CarrotPay Account Control Panel > Under the “Account secrets” panel > expand Reveal secrets
description
(Optional) A UTF-8 encoded string in the user's preferred language.
description: "US$ 2.0 to spend!"
String
link_description: "toys-R-us"
String
//The site url site_url: "https://www.site.com"
String
Displayed to the use before they accept the offer. link_description
(Optional) A UTF-8 encoded string in the user's preferred language. Displayed in the SiteCoin table of the WebPurse. If not defined then the domain of the site_url will be displayed.
site_url
(Optional) A web site address where this SiteCoin may be spent. It will be available to the user as a link in the SiteCoin table. When clicked the user will be sent to this url. When the site_url is not defined, the link will be obtained from the ‘web site url’ as set in the Merchant’s CarrotPay Account Control Panel (if defined), otherwise it will default to the URL of the web page the SiteCoins offer was offered.
JavaScript Syntax
Marketing campaign example
Carrot.purse({ merchant: "WWRV-JZHS-RQGZ-WLVL", //Merchant ID as allocated by CarrotPay during registration offer_id: "email-009", //Perhaps the name of your marketing campaign for easy identification offer_price: "1.00:USD", //This offer will credit (USD) $1 to the user’s WebPurse expiry: "43200", //This SiteCoin will expire 30 days after being accepted
sig: "wlvmcdkj", //The cryptographic hash of the data of this offer, see CarrotPay-Script Integration Guide callback_url: "https://www.yoursite.com/acceptedoffer", //To track the campaign progress in real time description: "Here’s US$1.0 to spend over the next 30 days", //The SiteCoin offer description.
17
site_url: "http://www.yoursite.com" //The domain where the $1 can be spent. });
Refund example
Carrot.purse({ merchant: "WWRV-JZHS-RQGZ-WLVL", //Merchant ID as allocated by CarrotPay during registration offer_id: "refund-USD", //Easy to monitor USD refunds offer_price: "4.49:USD", //The amount of the refund expiry: "2013-01-01T00:00:00+08:00", //Expire at the end of the year HKT offer_private: "2012-05-01T23:47:19+08:00", //Time when refund was made HKT sig: "xlmmcdlj", //The cryptographic hash of the data of this refund description: "Refund for image $4.49", //The SiteCoin offer description. site_url: "http://www.yoursite.com", //The domain where the $1 can be spent. link_description: "image refund" });
WebPurse Position The WebPurse can be positioned on a page using the optional parameters from the table below Parameters
Name
Description
Example
Type
element_id
(Optional) Positions the WebPurse iframe by centring it over the specified html element.
element_id: "contents"
String
purse_position: {top:100,left:200}
Object
hourglass_position: {top:100,left:200}
Object
NOTE: Overrides all other positioning. DesktopPurse: If a DesktopPurse is active this will have no effect. purse_position
(Optional) Position the WebPurse on the page with an offset from the top-left corner. The units are pixels. NOTE: When this parameter is not used, tahe default location will be the centre of the page or element_id (if provided). If Desktop Purse is used this will have no effect.
hourglass_position
(Optional) Position the Carrot hourglass on the page with an offset from the top-left corner. The units are pixels.
18
NOTE: When this parameter is not used, the default location will be the same as of the purse_position. Javascript Syntax Carrot.purse({ merchant: "WWRV-JZHS-RQGZ-WLVL", //Merchant ID as allocated by CarrotPay registration purse_position: {top:100,left:200}, hourglass_position: {top:100,left:200} });
Function name: Carrot.get_id() Overview This function obtains the user's unique Purse ID (e.g. KDPM-JLZR-VGWZ-DMRW). It differs from the Carrot.purse() function in that it does not give the option to the user to login if they are not already logged into their WebPurse.
Get the user’s ID Parameters
Name
Description
Example
Type
callback
(Required) A function to receive the unique purse ID returned by the user's Purse. May return null if purse not yet established.
callback: function(id) { //handle id here }
Function
merchant
(Recommended) The ID allocated by CarrotPay
merchant: "BWRV-JZHS-RQGZ-WLVL"
String
JavaScript Syntax Carrot.get_id()({ merchant: "BWRV-JZHS-RQGZ-WLVL",
19
c allback: function(id) //handle id here });
Function name: Carrot.DRM() Overview This function enables a merchant to execute some server-side code prior to calling Carrot.pay(). It is typically used to query a Digital Rights Management (DRM), service to determine if a user already owns the 'right to view' a particular digital asset. Such functions can usually be made more directly by using AJAX, however, Carrot.DRM() can also be used in situations where AJAX calls will fail i.e where the DRM is located in a domain other than the domain of the host page (this is due to browser cross-site rules). This function is therefore most useful if you wish to use a third party DRM service or if you intent to sell content from a site other than your own (perhaps from a posting on a social site). For example you may allow another site to sell your videos and also to offer extended viewing rights (i.e. 24 hr access). In this case the site may have a problem contacting your DRM which records the viewer’s rights. By using Carrot.DRM() you can query your DRM no matter what the domain is of the host page. Typically, if an asset is already authorised the merchant can release the product without the need for further payment, otherwise purchase data is typically returned. If there is only one purchase option available, then this can be displayed directly in the user's CarrotPurse by passing payment data Carrot.pay(). However, if multiple options are available (e.g. pay-per-view, 24 hr rental or monthly subscription etc), the options must be displayed for the user to select one. Ultimately payment data must be passed back to the callback function and on Carrot.pay() for a payment request to be made. NOTE: If a WebPurse has been established, its ID is also passed to the DRM service in a parameter called 'webpurse_id'. The webpurse_id may be used to determine who the user is but be aware that attackers may be able to call your drm_url with a webpurse_id that belongs to someone else.
Parameters Name
Description
Example
Type
asset_id
(Required) A token representing the digital asset to be 'viewed'.
asset_id: "movie.toy_story_2"
String
drm_url
(Optional) The URL of the DRM service to be used.
drm_url:"https://www.yoursite.com/DRM.php"
String
NOTE: If this URL is NOT provided, the default setting is https://secure.carrot.org/DRM.do DRM.do simply uses the partner_id parameter to find a URL previously set by the merchant in the Carrot control panel. Once found, Carrot will redirect
20
the call to the URL. partner_id
(Optional) A merchant specific identifier that must be unique across all CarrotPay merchants. NOTE: Needed only when a merchant wishes to use the redirection service provided through the CarrotPay Account Control Panel.
partner_id: "kaltura:123456"
String
When used with a kaltura video player, the CarrotPay plug-in automatically passes the Kaltura partner_id to the DRM function. The partner id is prefixed with a namespace so as to ensure it is unique (e.g. kaltura:123456).
callback
(Optional) A function to handle the result of the DRM call.
callback: function(data) { //process t he returned data }
Function
failure_callback
(Optional) A function to handle a failure. A 'reason' parameter will also be added.
failure_callback:"http://www.site.org/payment_f ailed.php"
Function
element_id
(Optional) Positions the DRM iframe by centring it over the specified html element.
element_id: "player"
String
NOTE: Overrides all other positioning. NOTE: If a DesktopPurse is active this will have no effect. purse_position
(Optional) Position the DRM on the page with an offset from the top-left corner. The units are pixels. NOTE: When this parameter is not used, the default location will be the centre of the page or element_id (if provided). NOTE: If Desktop Purse is used this will have no effect.
purse_position: {top:100,left:200}
Object
hourglass_position
(Optional) Position the Carrot hourglass on the page with an offset from the top-left corner. The units are pixels.
hourglass_position: {top:100,left:200}
Object
NOTE: When this parameter is not used, the default location will be the same as of the purse_position. DRM General Process
The sequence diagram below shows how the drm_url is called and how data is passed from the DRM back to the the host page.
21
22
DRM Template in JSP
A template to pass DRM data back to the host page <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <script type="text/javascript" src="https://cdn.carrot.org/js/carrot.js" > <script type="text/javascript">
