Complexity: Beginner Developer
In order for Refersion to operate as expected, we must be able to capture your transactions. If you are not using a shopping cart platform that we already integrate with, you must implement our tracking solution on your web site manually. Our tracking isn't very complicated and is installed similar to how Google Analytics is installed.
To install, you must complete the following steps.
For most of our APIs you must identify your account with your own unique Refersion API Public and/or Secret key. You may see existing or create new API keys right from your account settings.
Please copy/paste the following code on every page on your web site where you expect your affiliates to drive traffic. Make sure to place the code just before the </body>
tag in your HTML.
Code
<!-- REFERSION TRACKING: BEGIN -->
<script src="//www.refersion.com/tracker/v3/pub_0123456789DEMO.js"></script>
<script>_refersion();</script>
<!-- REFERSION TRACKING: END -->
In order for us to calculate any commissions owed, each order must be reported to us. You may do so in one of two ways:
Option 1: JavaScript on "Thank You" Page Easier Implementation
For this type of tracking, you must add code into your "thank you" or confirmation page. This would be the page that all customers are directed to after completing their order. Below is sample code which you should use as a starting template.
Within this code, you must dynamically insert the customer's transaction information from the respective order. We've added some dummy order information for your reference. Not all data is required, but all is recommended. A description of each field is available at the end of this article.
For best performance, place this code just before the </body>
tag in your HTML.
Code
<!-- REFERSION TRACKING: BEGIN -->
<script src="//www.refersion.com/tracker/v3/pub_0123456789DEMO.js"></script>
<script>
_refersion(function(){
_rfsn._addTrans({
'order_id': '12345',
'shipping': '11.90',
'tax': '5.23',
'discount': '2.32',
'discount_code': 'TESTCOUPON',
'currency_code': 'USD'
});
_rfsn._addCustomer({
'first_name': 'Nancy',
'last_name': 'Parker',
'email': '[email protected]',
'ip_address': '808.53.77.22'
});
_rfsn._addItem({
'sku': 'DD23444',
'quantity': '2',
'price': '100'
});
_rfsn._addItem({
'sku': 'XJ66778',
'quantity': '3',
'price': '50'
});
_rfsn._addItem({
'sku': 'MP39592',
'quantity': '2',
'price': '1000'
});
_rfsn._sendConversion();
});
</script>
<!-- REFERSION TRACKING: END -->
Option 2: Server-Side JSON Webhook Greater Security
Another way to report orders to us is by creating a Webhook. Usually this option requires a greater amount of development work since you'll be "posting" order information to us directly from your server.
There are two requirements for this implementation:
cart_id
using a short JavaScript code on your "thank you" page so that we may reference any future Webhook reported to the session.cart_id
.The cart_id
value
When we receive any Webhooks, we must associate it with a previously captured browser session. However, since Webhooks are reported from the server-side and not the browser-side, we can not access the relevant customer's session information. For this reason, we use the cart_id
value as a common identifier that we can reference. We ask you to report a cart_id
on your "thank you" page where we store session information and then a second time in the Webhook so that we may associate it with the aforementioned browser session from the JavaScript call.
The cart_id
may be any string value up to 255 characters.
cart_id
is not sequential or may be easily guessed such as a session ID or an encrypted version of several strings.Reporting cart_id
Please copy/paste the following code into your "thank you" or confirmation page. This would be the page that all customers are directed to after completing their order.
Code
<!-- REFERSION TRACKING: BEGIN -->
<script src="//www.refersion.com/tracker/v3/pub_0123456789DEMO.js"></script>
<script>_refersion(function(){ _rfsn._addCart("YOUR-CART-ID"); });</script>
<!-- REFERSION TRACKING: END -->
You must replace "YOU-CART-ID" with the actual cart_id
value. Please make sure to include the double quotes.
Posting the Webhook
Data must be reported as JSON string which contains the order data as well as the cart_id
. You Refersion API keys (public and secret) should be sent in the header. Below is an example of the JSON that we are expecting.
{
"cart_id": "DDXqfBngTWuX8N8Asqr2mY3RkmHCXdM7Vz6mdHkjwrEnN5zyRY",
"order_id": "20150401102883",
"shipping": 9.99,
"tax": 0.57,
"discount": 2.25,
"discount_code": "HOLIDAY1",
"currency_code": "USD",
"customer":{
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"ip_address": "234.192.4.75"
},
"items": [
{
"price": 5.50,
"quantity": 2,
"sku": "PROD_A",
"name": "Product A"
},
{
"price": 10.00,
"quantity": 1,
"sku": "PROD_B",
"name": "Product B"
},
{
"price": 15.00,
"quantity": 3,
"sku": "PROD_C",
"name": "Product C"
}
]
}
To deliver this data to us to you must send it via an HTTP POST. Below is example PHP code using cURL.
<?php
// The complete data that you are sending
$order_data = array(...); // Omitting data for demonstration
// Convert array into JSON
$json_data = json_encode($order_data);
// The URL that you are posting to
$url = 'https://inbound-webhooks.refersion.com/tracker/orders/paid';
// Start cURL
$curl = curl_init($url);
// Verify that our SSL is active (for added security)
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, TRUE);
// Send as a POST
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'POST');
// The JSON data that you have already compiled
curl_setopt($curl, CURLOPT_POSTFIELDS, $json_data);
// Return the response
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
// Set headers to be JSON-friendly
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Content-Length: ' . strlen($json_data),
'Refersion-Public-Key: YOUR-PUBLIC-KEY',
'Refersion-Secret-Key: YOUR-SECRET-KEY')
);
// Seconds (30) before giving up
curl_setopt($curl, CURLOPT_TIMEOUT, 30);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 30);
// Execute post, capture response (if any) and status code
$result = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
// Close connection
curl_close($curl);
Transaction Data
A transaction represents the entire order that occurred, and contains the following values:
Value | Type | Required | Description |
---|---|---|---|
cart_id | String | Yes - Webhook only | Cart ID that matches what you're reported in _addCart , as per above. This field is only required when reportinng transactions via a Webhook (option 2). |
order_id | String | Yes | Unique shopping cart order ID or transaction number used to reference the purchase that you're reporting. |
subscription_id | String | Yes - Subscriptions only | For subscription purchases only: A unique identifier that represents the whole subscription, which can be a reference to all of the individual order_ids within this subscription. Only available in webhook reporting. |
is_subscription | Boolean | Yes - Subscriptions only | If you are reporting an event which belongs to a subscription, set this to TRUE , otherwise leave blank.Only available in webhook reporting. |
shipping | Number | No | Total shipping and handling the customer was charged for the order. |
tax | Number | No | Total tax the customer was charged for the order. |
discount | Number | No | Total in discounts that were applied to the order. |
discount_code | String | No | The discount or coupon code that was used on the order. |
currency_code | String | Yes | The three letter currency code of the order totals that you are reporting. Example: USD, CAD, GBP. |
Customer Data
A customer represents the individual customer who purchased, and contains the following values:
Value | Type | Required | Description |
---|---|---|---|
first_name | String | No | Customer’s first name. |
last_name | String | No | Customer’s last name. |
String | No | Customer’s email address. | |
ip_address | String | No | The IP address of the customer. |
Item Data
An item represents an individual product that the customer had ordered, and contains the following values:
Value | Type | Required | Description |
---|---|---|---|
sku | String | Yes | A unique Product SKU or identifier ID. Can be blank, but we highly recommend that you populate the field. |
name | String | No | The name of the item. |
quantity | Number | Yes | Total quantity ordered of the product. |
price | Number | Yes | Price of each item. For example, if the customer ordered 10 items at $5 each, you should report $5, not $50. Do not include currency symbols. |