Server-to-Server Payouts - Playback Direct

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

Parameter	Detail	Format	Type
`user_id`	This 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.	`String`	Required
`pd_user`	This is a unique user_id that Playback Direct assigns to a user. It can be helpful for troubleshooting	`String`	Required
`transaction_id`	The unique transaction ID.	`String`	Required
`virtual_currency`	The amount of virtual currency the user should get.	`Integer`	Required
`rev_usd`	This is the revenue that you will earn for the completion of the particular event. Presented in cents. Example: 498 = $4.98 USD	`Integer`	Required
`secure_hash`	The 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.	`String`	Recommended
`sub_source_id`	This is the unique ID we will assign to you to identify users coming from your app.	`String`	Optional
`app_name`	Human readable name of your app the user is from.	`String`	Optional
`adid`	For Android mobile devices, this would be the GAID (google advertising ID). For iOS, this would be the IDFA.	`String`	Optional
`task_name`	The name of the completed task within the offer	`String`	Optional
`network`	This is passed back if it was supplied by you in the orginial URL that the sent the user to Playback Direct.	`String`	Optional
`manual`	If this event was manually triggered by the support team due to an issue that was detected this will return as `true`, `false` otherwise.	`Boolean`	Optional

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:

Install apps from within the Playback Direct implementation in your app.
Engage in the offers and complete the tasks required to earn rewards.
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.

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

​Endpoint Structure

​S2S Parameters

​S2S Security: IP Whitelisting

​S2S Security: Secure Hash

​

​Retry Logic

​Testing Payouts

Set Up Server-to-Server (S2S) Payouts

Endpoint Structure

S2S Parameters

S2S Security: IP Whitelisting

S2S Security: Secure Hash

Retry Logic

Testing Payouts