Skip to main content

​
Set Up Server-to-Server (S2S) Payouts

To enable S2S payouts, set up an endpoint on your server to receive notifications about user rewards from Playback Direct. When a request is made to your endpoint, you then must manage the distribution of these rewards to the users.

​
Endpoint Structure

The key names can be customized, or you can use the default names. Please ensure that no special characters should be included in the values, otherwise our backend may transform the request, which could cause issues with the payout. Default GET / https://example.com/example?user_id={user_id}&pd_user={pd_user}&transaction_id={transaction_id}&virtual_currency={virtual_currency}&rev_usd={rev_usd}&secure_hash={secure_hash} Customized (Example) GET / https://example.com/example?user_id={user_id}&trans={transaction_id}&playback_id={pd_user}&gems={virtual_currency}&revenue={rev_usd}&app={app_name}&event={task_name}&secure_hash={secure_hash}

​
S2S Parameters

ParameterDetailFormatType
user_idThis is the unique user identifier that you append in the URL when sending players to Playback Direct. This will be what you use to identify which player to send the rewards to.StringRequired
pd_userThis is a unique user_id that Playback Direct assigns to a user. It can be helpful for troubleshootingStringRequired
transaction_idThe unique transaction ID.StringRequired
virtual_currencyThe amount of virtual currency the user should get.IntegerRequired
rev_usdThis is the revenue that you will earn for the completion of the particular event. Presented in cents. Example: 498 = $4.98 USDIntegerRequired
secure_hashThe secure hash, used to verify request authenticity. Requires a token, which will be shared with you by your Playback Direct rep. Detailed setup instructions below.StringRecommended
sub_source_idThis is the unique ID we will assign to you to identify users coming from your app.StringOptional
app_nameHuman readable name of your app the user is from.StringOptional
adidFor Android mobile devices, this would be the GAID (google advertising ID). For iOS, this would be the IDFA.StringOptional
task_nameThe name of the completed task within the offerStringOptional
networkThis is passed back if it was supplied by you in the orginial URL that the sent the user to Playback Direct.StringOptional
manualIf this event was manually triggered by the support team due to an issue that was detected this will return as true, false otherwise.BooleanOptional
Example Response URL: https://example.com/example?user_id=f3069c9ef82c4579&trans=e8525f9b-3dd3-4319-bdda-c1e1f375f5bf&playback_id=cvLEJINc5hJzI4R9w0nA&gems=1200&revenue=120&app=MyAppName&event=CompleteTutorial&secure_hash=db951fdd56e3de10894c132108f25b54016a739db67ef3cc630dc56c8332cce5

​
S2S Security: IP Whitelisting

When we make payout request to publishers, we send an HTTP request from the following set of IPs. 
34.19.25.125
34.168.97.45
To enhance security, use these IP addresses for IP-level blocking on endpoints receiving Playback’s S2S payout requests. Allow only these specific IPs access.

​
S2S Security: Secure Hash

A secure hash can be sent for you to verify the authenticity of these requests. This is an additional measure that is recommended to be used to prevent fraudulent requests. The secure_hash is generated as a SHA-256 hash of the required query parameters of the request along with the s2s_tokenand encoded into a hexadecimal string. The s2s_token is used as the secret key which your Playback Direct rep will provide to you. 
secure_hash = sha256(concatenate(user_id, pd_user, transaction_id, virtual_currency, rev_usd, s2s_token))
Below is an example script that shows how to calculate the secure_hash from the URL query params. The resulting value can be compared against the secure_hash sent in the the URL. You would implement some version of this in your backend. Typescript 
export async function createSecureHash(
  user_id: string,
  pd_user: string,
  transaction_id: string,
  virtual_currency: string,
  rev_usd: string,
  s2sToken: string,
): Promise<string> {
  const params = [user_id, pd_user, transaction_id, virtual_currency, rev_usd, s2sToken];
  const canonicalString = params.join(',');

  // Encode into UTF-8 and create SHA-256 hash
  const encoder = new TextEncoder();
  const messageData = encoder.encode(canonicalString);
  const hashBuffer = await crypto.subtle.digest('SHA-256', messageData);

  // Convert the hash ArrayBuffer to a hex string
  return Buffer.from(hashBuffer).toString('hex');
}

​

​
Retry Logic

If we receive a 4xx / 5xx from your endpoint, we have an established retry logic for the failed S2S requests. If a request fails, we retry after 10 minutes. A second failure prompts a retry in another 10 minutes. Subsequent failures lead to retries every 2 hours from the initial failed attempt. After 12 hours we stop retrying the request.
If you observe an extended period of unsuccessful requests, contact your Playback Direct rep for further investigation into the issue.
We also have alerts and logging placed on our side. If certain thresholds are met where consistenst retries are necessary, we may temporarily pause offers and follow up with you to resolve the underlying issues.

​
Testing Payouts

Follow these steps to verify the correct functioning of payouts:
  1. Install apps from within the Playback Direct implementation in your app.
  2. Engage in the offers and complete the tasks required to earn rewards.
  3. One a task has been completed. Verify the following:
    1. The completed task is reflected within the offer details page within Playback Direct
    2. Check to make sure you received a reward notification to your API endpoint.
    3. Make sure that your user’s currency balance was updated according to what was sent to the API endpoint within your app.
Your Playback Direct rep can help in testing and troubleshooting the integration as well.