Callbacks

The Callback is the basis by which you can reward your users. The Callback is a GET request that is sent to your processing script upon the conclusion of a transaction - either a complete COMPLETE, screenout TERMINATION, or overquota QUOATAFULL.

This request contains important information about which user needs to be rewarded, what offer was taken, and how much virtual currency they should be paid.

Setup Callback

RapidoReach supports secure hasing on system-to-system callbacks. Please reach out to a RapidoReach account manager to configure the Callback URL. Follow the steps below to complete your setup.

How to create a Processing Script

1. Create an endpoint that can receive a GET request to its location.
2. Reward your users for completes and screen-out rewards (if applicable).
3. Store information in your database
4. Respond with a 1 if callback received & processed correctly and 0 if you require us to repeat the callback (can be repeated three more times).

Add the Callback to your application

• Go to Apps section.
• Select your Application.
• Click on the Callback section.
• Click on the Setup Callback button.
• Enter your Callback URL.
• Click Save button.

Callback Responses

Sample processing script location (sometimes referring to a php, aspx, or another script depending on your webapp configuration)

xxxxxxxxxx

app-domain.com/callback

Parameters will be appended with their corresponding variables after the processing script location as follows:

xxxxxxxxxx

app-domain.com/callback?cmd=transactionComplete&userId=user123-9370-d163590aa9

&amt=100&offerInvitationId=1234&status=C&oiHash=2ef1130cca32cd030141d8935dec0992

&currencyAmt=20000&transactionId=4321&endUserId=user123&offerTitle=TestProject

&useragent=RapidoReach&profiler=&currencyName=Chachingz&offerType=survey

&txnHash=66a2b2987083666c76592d505240748e&program=&transactionSource=iframe&

xxxxxxxxxx

app-domain.com/callback 

'?cmd=' // QUOTAFULL, COMPLETE, TERMINATION

OfferStatus // 

'&userId=' 

RORuserId  // RapidoReach userId as generated earlier.

'&amt=' 

Dollar_AMT.toFixed(2) // Amount paid in dollars to you for this particular transaction.

'&offerInvitationId=' 

TransactionId  // Enables you to remember for which offer a user has been rewarded for.

'&status=' 

OfferStatus  // Compete - Disqualified - QuotaFull

'&offerHash=' 

offerHash  //32 character hex string = md5(concat(offerInvitationId, applicationKey))

'&currencyAmt=' 

VC_AMT.toFixed(2)  //Payout to user in your virtual currency. Important for screenout rewards.

'&transactionId=' 

TransactionId  //Unique ID representing a single user participating in a single survey/offer,

'&endUserId=' 

endUserId 

'&txnHash=' 

transHash  //md5(concat(transactionId, current TransactionKey))

'&useragent=' 

'Rapidoreach' 

'&currencyName=' 

app.vc_name 

'&offerType=' 

OfferType 

'&deviceType=' 

DeviceType 

'&intergrationMethod=' 

'IFRAME';

Callback Parameters

cmd

will always be transactionComplete

userId

RapidoReach userId as generated earlier.

amt

Amount paid in dollars to you for this particular transaction.

offerInvitationId

Enables you to remember for which offer a user has been rewarded for.

status

• QUOTAFULL - user screened out of survey, the required number of responses from this demographic has already been met.
• COMPLETE - user successfully completed the transaction.
• TERMINATION - user screened out of survey, does not have the relevant attributes needed.

oidHash

32 character hex string = md5(concat(offerInvitationId, applicationKey))

You should verify oidHash upon receipt of the callback by recomputing it with the callback offerInvitationId and your ApplicationKey. This will secure against users faking their own id and passing it in if by some chance they come across the script.

currencyAmt

Payout to user in your virtual currency. Important for screenout rewards.

integer (default) or float (on request)

Indicates how many points the user should get in your site’s virtual currency. Based on your configured conversion rate on the control panel. Negative values indicate chargebacks.

transactionId

Unique ID representing a single user participating in a single survey/offer, please include if requesting support for a particular transaction.

txnHash

32 character hex string = md5(concat(transactionId, current TransactionKey)) You can find your TransactionKey in your Application list.

Optional Parameters

sub_id

Optional alias identifier to track traffic on campaigns, can be used for testing and segmentation purposes. Please ask our team to enable sub_id for you.

IP Whitelist

We highly recommend whitelisting the following IPs to secure your system from fraudulent callbacks. If the following list is update, you will be notified via email prior to the change.

xxxxxxxxxx

161.97.78.55, 173.212.227.149

Setup callback IP whitelist

1. Go to Apps section.
2. Select your application.
3. Click on the Callback section.
4. Under the IP Whitelist section click the Copy IP Whitelist button to copy the IPs to your clipboard.

How to Test the Callback

First ensure that you have whitelisted the IPs listed in the above section.

Instructions

1. Go to Apps section.
2. Select your Application.
3. Click on the Callback section.
4. Click on the Test Callback button.
5. Fill out the form with the parameters you want and click the invoke Test Callback button.
6. Get your results.

Redirects

We support two separate links, one for successful completes, one for everything else

If you’d like to setup custom redirect URLs, contact your Rapidoreach account manager. We don’t support redirect hashing; we use secure hasing in our system-to-system Callbacks.

We return a handful of query parameters describing the session result in the URL:

transactionId

Transaction ID

userId

The three part RapidoReach user ID

endUserId

The user ID passed in the entry URL

status

The status of the transaction: C, P, or F.

sub_id

A custom tracker ID that you may pass with the user in the entry URL.

Example

xxxxxxxxxx

https://www.rapidoreach.com/success=true&status=#status#&transactionId=#transactionId#&userId=#userId#&tempId=#tempId#&sub_id=#sub_id#

Advanced Redirect Values

If you’d like to receive additional data about user sessions, add tcode to your Redirect URL:

tcode = #tcode# Below are the possible values you will receive the the tcode parameter.