When integrating an offer by means of postback (server to server aka s2s), the Advertiser's server sends a request via the postback URL with data on the targeted actions performed on the Advertiser's website (landing page, application, etc.) to the HOQU server. The HOQU server receives this data and it appears in the platform statistics.

Features
Changes to the site interface do not affect sending requests via postback
To implement the solution, you need to have access to the server side of the site or CRM (back-end) on the Advertiser's side
Data refresh can be fully automated

How the affiliate link works

In the course of working with the affiliate program, an Affiliate places an affiliate link on his site (or any other traffic source). An affiliate link is generated based on a link leading to your site (landing page, application, etc.) and contains GET parameters and UTM tags which you and the HOQU platform need.

One of the GET parameters must pass the click_id value — a unique identifier that is generated on the HOQU platform side when the user clicks the link.

Example of a link after clicking on an affiliate link:
https://site.com/?click_id=c7e2206f-03af-49fa-9046-dd6aeaa44e9b

The click_id value must be obtained from the GET parameter at the user's entrance to the site and saved for (as a rule) 30 days in the user's cookies. The click_id parameter is configured when creating an offer:



After that, you need to associate the click_id with the target user action and write it to your database (Advertiser database). Next, the Advertiser needs to pass the click_id value in the postback request, as well as the following required parameters (for the CPA model with a fixed payment):
request_id - unique ID on the Advertiser's side
action - the name of the action in the Rates section specified in the offer card
status - conversion status: hold, approved, rejected

Brief steps of integration on the Advertiser's website

Implementation of the algorithm for creating a cookie and recording the click_id value
Implementation of the algorithm for reading click_id from a cookie and writing to the Advertiser's database along with the targeted user action
Implementation of the mechanism for sending postback requests from the Advertiser's server to the HOQU server
Testing - by conducting test conversions (more on this below in the “Testing Procedure” section)

Postback request sending mechanism

The Advertiser can send requests in order to:

Inform the platform about a new conversion (the user took the target action, but it has not yet been confirmed / rejected by the Advertiser)
“Status” = “hold”, in case of an unconfirmed conversion
“Status” = “rejected”, in case of a conversion rejected by the Advertiser
Update the conversion status of a conversion on the platform

If the Advertiser wants to send an approved conversion, then it is necessary to write “approved” in the “status” parameter. Requests are individual for each offer. Depending on the different types of payments, the data that needs to be sent to postback requests is different.

Mandatory parameters for the CPA model with a fixed payment: click_id, request_id, action, status.
Mandatory parameters for CPA model with a percentage payout: click_id, request_id, action, status, price.
Mandatory parameters for the Recurring payments payment model (a model where the same customer makes regular / recurring payments):

To add a client, -
customer_id - unique customer identifier in the Advertiser's system
click_id - unique click ID that the Network sends to the Advertiser, only for S2S integration
price - required parameter only for payments with the percentage (revshare) payment type
status - activate or deactivate

To add a lead, -
click_id, request_id, action, status, customer_id

In order to pass additional parameters, you can customize the template. Postback request templates are configured in the "Offers" - "Templates" section:



Do not forget to select status “Active” to activate the template.
Then the created template can be added in the Rates section when creating and editing an offer. To do this, select the payment model, the template created earlier and fill in / edit other parameters.

Informing the platform about a new conversion

In order to inform the HOQU platform about a new conversion, you need to send a POST or GET request.

Sample POST request:

POST /api/v1/postback HTTP/1.1
Host: https://trackerdomain.com/advertiser_api_key
Content-Type: application/json
{
"click_id": "c7e2206f-03af-49fa-9046-dd6aeaa44e9b",
"request_id": "94583",
"action": "lead",
"price": 30,
"status": “hold”.
}

Sample GET request:
https://trackerdomain.com/advertiser_api_key/s2s?click_id=c7e2206f-03af-49fa-9046-dd6aeaa44e9b&request_id=12345&action=lead&price=30&status=hold

The examples above pass the following data:

click_id - the click_id GET parameter that the Advertiser writes to the database along with information about the user's request.
request_id - a unique identifier for the conversion in your database. Advertisers generate an identifier from themselves and substitute it in the postback request. On it, duplicates will be automatically excluded, and conversions will be confirmed / rejected, and it will also be possible to conduct manual reconciliation.
price - the amount that the client (Advertiser) paid for the conversion. The Advertiser must transfer the full amount of earnings from the conversion, without deducting any commissions, all calculation and distribution, taking into account commissions, is done on the platform side. This field is required only for rates in which the partner network receives a percentage of the order value of the customer brought by the user.



Update conversion status on the platform

In order to update the status of an application on the platform, you need to send a GET request by passing the status parameter with one of the values:

approved - approved
rejected - rejected

The Advertiser can immediately transfer the final conversion status in case of payment or refusal.

An example of a GET request to update the status to confirmed:

https://trackerdomain.com/advertiser_api_key/s2s?click_id=c7e2206f-03af-49fa-9046-dd6aeaa44e9b&request_id=12345&action=lead&price=30&status=approved

An example of a GET request to update the status to rejected:

https://trackerdomain.com/advertiser_api_key/s2s?click_id=c7e2206f-03af-49fa-9046-dd6aeaa44e9b&request_id=12345&action=lead&price=30&status=rejected

Where to find postback, pixel, iFrame

Go to the offer card and click on the Integrations section on the bottom of the page:



Testing procedure

After you configure the algorithm for sending postback requests from the server, you can create a test conversion in two ways:

You can independently create a test affiliate on hoqu.com, connect to your offer on behalf of this Affiiate, get an affiliate link and make a test.

In order to create a test Affiliate, use the invitation link: create a link and follow it in another browser (or in incognito mode). An invitation link is created in this section:

You can ask the HOQU manager to send you a test link.

Integration completed successfully if you saw the conversion in the Reports section. If you did not see the conversion, go to the Logs -> Incoming postbacks section and analyze the error when sending an incorrect request.

If the error analysis did not help you to conduct a successful test, contact your HOQU manager.
Was this article helpful?
Cancel
Thank you!