Server-to-server (S2S) Tracking
Basic Principles
Order API
The Order API is used to track transactions. All transactions will first register as a “pending” status. Pending transactions will need to be validated in order to grant cashback.
Order Process Flow
- ShopBack will redirect to the merchant website with affiliate parameters such as utm_source=shopback. One key parameter is transaction_id. Merchants may choose to add or change any of the parameter names to suit their preferences.
- Merchant identifies the traffic coming from ShopBack and records
transaction_id
. - When users purchase, the merchant will call the Order API webhook and pass the
transaction_id
along with other parameters such asorder_id
,product_id
, andpurchase_amount
. - The user cashback will be created by ShopBack and the order will be tracked as
pending
. - To approve or confirm the
pending
cashback, the merchant will have to go through the validation process.
Recommended Precautions
Due to constant merchant updates, it is recommended that merchants store the transaction_id in the database to maintain a temporary
transaction_id
history. In the event of an Order API outage, the merchant is able to clawback thetransaction_id
from the order history and reinstate the Order API.
Validation API
The Validation API is used to validate Order API transactions with either rejected
or approved
statuses. Below are the cases of the 2 different statuses.
Approved Status | Rejected Status |
---|---|
Customer has received the product and the transaction is past the return period | Customer has returned the entire order product |
Customer has completed payment and services rendered | Customer canceled the order |
Transaction has past any return policy and will be locked | Customer did not complete the payment |
Customer is identified as fraudulent |
Transactions that are still in pending
status will remain in pending
status until a Validation API is given to that particular transaction.
Validation Process Flow
- Users who transact under ShopBack will have the
order_id
recorded in the merchant database - When the product has been received by the customer and the order has passed the return policy or the customer has returned the product, the merchant may approve or reject the
order_id
by calling the Validation API. - This serves as a feedback loop to ShopBack that the order is applicable for cashback and ShopBack may be able to release the cashback to users or the transaction is rejected entirely.
- For Item-tracking merchants, partial order approval and rejection are possible using the Validation API.
Tracking Methods
ShopBack provides 2 methods of tracking transactions.
Method 1 - Order Tracking
Basic tracking method that only tracks [order_id]
and [sale_amount]
including any shipping fees exclusion and coupon discounts.
In this method, the merchant only needs to provide the order id and amount values.
Method 2 - Line Item Tracking
ShopBack uses line-item tracking whereby each line item is captured in one line with the quantity amount and amount as line item subtotal amount.
For Regional Merchants
ShopBack works with merchants that have a regional presence with multiple websites. For regional merchants, ShopBack will allow customization to have either 1 merchant account or multiple merchant accounts. ShopBack API indicates merchant account as “offer id” and the main parameter is {order_offer_id}
. See the examples below:
Example 1
Merchant_A operates www.testshopA.com which has a regional presence and offers customers from any location to purchase Merchant_A services. Therefore, 1 merchant account should suffice, and only 1 {order_offer_id}
and 1 {validation_offer_id}
will be assigned to Merchant_A.
Example 2
Merchant_B operates www.testshopB.com.my (MY), www.testshopB.sg (SG), www.testshopB.co.id (ID) that is independently operated by local entities. Merchant B then has the following options:
Option A
Merchant B HQ requests 3 merchant accounts and will be assigned 3 {order_offer_id}
and 3 {validation_offer_id}
. In this case, the 3 APIs can be configured to receive different information and are tailored for local currency and local timezone.
Option B
Merchant B HQ requests only have 1 merchant account with only 1 {order_offer_id}
and 1 {validation_offer_id}
for all 3 websites. In this case, the API will be configured to capture currency and a standardized timezone.
Currency Settings
ShopBack allows the ability to have a single currency account or multi-currency account when operating from 1 website. For example,
- www.testshopA.com allows customers to pay in any currency and therefore is configured as a multi-currency account.
- www.testshopB.com.my only allows customers to pay in MYR and therefore is configured as a single currency account.
The currency setting chosen is for data capturing purposes only and does not mean invoice payment has to be made in that currency. Please discuss this further with your ShopBack representative.
For single currency merchant account
ShopBack will configure the merchant account to accept the desired currency and all {sale_amount}
captured will be tracked in that specific currency.
For multi-currency merchant account
ShopBack will configure the merchant account to accept the multi-currency and all {sale_amount}
captured will be tracked as a number. The currency used will be determined by the parameter adv_sub5
in the postback.
Parameter Name | Parameter Value | Parameter Example | Description | Format | Required |
---|---|---|---|---|---|
adv_sub5 | [iso_currency_code] | MYR | ISO currency code values allowed only. Reference | Alphabetic in all capital letters | mandatory |
Timezone and Datetime Settings
ShopBack API endpoints are designed to capture postbacks in real-time and are recommended for all merchants to allow ShopBack users to track the cashback with a shorter delay.
For regional merchants that operate multiple websites with a single account, ShopBack allows the merchant to standardize the datetime by adding the datetime
parameter to the postback.
ShopBack only has 2 modes for controlling datetime
of the conversion or postback.
Mode 1 - No datetime
parameter is used in the postback
datetime
parameter is used in the postbackMode 1 will track all postbacks in real time and according to the local time zone. This means the datetime
captured when the postback is received by ShopBack. This mode is most suitable for local merchants operating a local website.
Example scenario
Transaction datetime
= 12:00PM UTC+8
Postback sent datetime
= 12:00PM UTC+8
ShopBack user cashback will be recorded as 12:00PM UTC+8
Mode 2 - A datetime
parameter added in the postback
datetime
parameter added in the postbackBy adding the datetime
parameter, ShopBack will record the conversion following the datetime
value instead and NOT when the postback is received by ShopBack. To use Mode 2 effectively, the merchant should adjust the datetime
value to UTC+0.
Example scenario
Transaction datetime
= 2023-01-01 12:00PM UTC+8
Postback sent datetime
= 2023-01-01 2:00PM UTC+10
In order to capture the transaction at the correct time, datetime=2023-01-01 04:00:00 is added to the postback as this is the correct time at UTC+0 when the transaction takes place.
Basically, if datetime is used, it has to be adjusted to UTC+0 timezone. Please see the below details.
Parameter Name | Parameter Value | Parameter Example | Description | Format | Required |
---|---|---|---|---|---|
datetime | [datetime] | 2023-01-01 12:00:00 | Datetime adjusted to UTC+0 | YYYY-MM-DD HH:MM:SS Must be URL-encoded | mandatory |
Updated about 1 year ago