To reward users, it’s necessary to integrate the Reward Request Postback API. Postback requests are conducted in a Server-to-Server for security purposes.

Summary of Procedures

1. Establish a server endpoint capable of receiving reward requests from Buzzvil (we refer to this endpoint's URL as the postback URL).

2. Perform Server-to-Server integration as instructed in this guide.

3. Provide the postback URL to Buzzvil's Technical Support Manager.

Index

1 Index
2 Introduction
- 2.1 HTTP Request Parameters
- 2.2 HTTP Request Parameter Postback Example
- 2.3 IP Whitelist
- 2.4 Request Parameter Verification OPTIONAL
  - 2.4.1 1. HTTP Request Parameter Encryption/Decryption
  - 2.4.2 2. Add Checksum Parameter

Introduction

Reward Request API is designed to 1. inform publishers when users participate in an ad (event), 2. request publishers to reward users, and 3. inform Buzzvil whether the reward accrual was successful.

	항목	내용

	항목	내용
1	Request Direction	Buzzvil → Publisher
2	HTTP Request method	POST - application/x-www-form-urlencoded
3	HTTP Request URL	Endpoint on the publisher’s server
4	HTTP Request Parameters	Refer to the below “HTTP Request Parameters” table
5	HTTP Response Code	The Buzzvil server determines whether the result of the reward request was successful based on the response code received from the publisher’s server. 200 (OK), 204 (No Content), 409 (Duplicate Request): successful Response codes when the publisher server successfully processes the request (points accrued to the user) Resond with 409 when the server’s already accrued points to the user but duplicate requests were received Response codes other than 200, 204, 409: failed Retry postback request up to 5 times Retry intervals are roughly 1 minute, 10 minutes, 1 hour, 3 hours, and 24 hours from initial failure Response codes other than 200: Refer to standard HTTP response codes Even if the body contains error content, no retry postback will be attempted if the response code is 200

HTTP Request Parameters

Field	Type	Description

Field	Type	Description
`user_id` REQUIRED	String (max 255)	User identifier defined by the publisher
`transaction_id` REQUIRED	String (max 32)	ID issued for the reward. Used to identify each reward and prevent duplicate point issuance.
`point` REQUIRED	Integer	Amount of reward that should given to the user
`unit_id` REQUIRED	Long	Identifier for the specific area where ads are placed. For instance, if ads are placed on the lower banner area on an app’s “Home” tab, an ID will be issued for the ad placement area (view). This ID will be issued by Buzzvil.
`title` REQUIRED	String (max 255 in Korean)	Ad title i.e `출시 임박! 해당 CPS 상품을 먼저 만나보세요! 😁 #Buzzvil #환상적` Reward requests could occur for non-ad products. In this case, the value is empty.
`action_type` REQUIRED	String (max 32)	Refers to the action type of the reward request `opened`: opened Feed `u`: unlocked `l`: landed `a`: action (when the user performed the required missions for an ad) `won`: won Potto `manual`: manual postback requested `spinned` : spinned roulette `daily` : Feed daily reward event
`event_at` REQUIRED	Long (timestamp)	Timestamp of point issuance (UNIX Timestamp in seconds) Check the timestamp at https://www.epochconverter.com/
`extra` REQUIRED	String (max 1024)	If additional parameters need to be added, use this parameter (JSON serialized string value) 매체사가 지정한 캠페인 데이터 (대시보드에서 캠페인을 생성할 때 지정할 수 있습니다) e.g `{"sub_type": "A", "source":"external"}`
`data` OPTIONAL	String	Parameter used if encrypting HTTP request parameters
`c` OPTIONAL	String	Parameter used when sending a Checksum to the HTTP request parameters
`custom2` OPTIONAL	String (max 255)	Custom Parameter specified by the publisher when integrating S2S APIs Value will be included in the reward request postabck `value up to custom 4 can be transmitted`
`custom3` OPTIONAL	String (max 255)	Custom Parameter specified by the publisher when integrating S2S APIs Value will be included in the reward request postabck `value up to custom 4 can be transmitted`
`custom4` OPTIONAL	String (max 255)	Custom Parameter specified by the publisher when integrating S2S APIs Value will be included in the reward request postabck `value up to custom 4 can be transmitted`

HTTP Request Parameter Postback Example

{
  "user_id": "12345",
  "point": 1,
  "transaction_id": "126905422_10000001",
  "event_at": 1641452397,
  "unit_id": 5539189976900000,
  "action_type": "l",
  "title": "\uad11\uace0\u0020\ud2b9\uac00",
  "extra": "{}"
}

IP Whitelist

To receive reward request postbacks from Buzzvil servers, please whitelist the following IPs on your firewall.

54.64.39.245
52.68.114.43
13.113.136.11
52.194.132.196
13.114.88.146

Request Parameter Verification OPTIONAL

It is possible to encrypt or add verifications for reward request postbacks sent from the Buzzvil server. This process is not mandatory but provides two methods if needed.

1. HTTP Request Parameter Encryption/Decryption

If you want to encrypt the HTTP request parameters sent from the Buzzvil server to the media, use this method. The encryption method provided is the Advanced Encryption Standard (AES), with AES-256 as the block encryption and using Cipher Block Chaining (CBC) mode and PKCS7 padding.

Prerequisites

Obtain the following values for AES-256 encryption through Buzzvil Manager:
- AES Key (length: 32)
- AES IV (length: 16)
Before providing the AES Key and IV to the publisher, the publisher must generate private and public keys using RSA-1024, and provide the public key to the Buzzvil Manager.
The Buzzvil Manager will encrypt the AES Key and IV, and provide the values to the publisher. The publisher should use the private key to decrypt the values.

Steps for Encryption/Decryption

Buzzvil server encrypts HTTP request parameters.
1. Apply UTF-8 encoding to the JSON-serialized parameters (string).
2. Apply PKCS7 padding and proceed with AES encryption on the string.
3. Perform base64 encoding on the encrypted value
Add the encrypted value to the HTTP POST request as data.
1. e.g
  { "data": "cg087LiIp30jCWpc3MVLfxPL4F05OFGGCkQwwpS6pRVMZhkumzfTFxc8iBoZ8unI15uk0cmY+CbSeOaLHsd7PaxsbyKISiJ31WJJ1OwfaYttoMwFysKNfL7pSz2HB9ULWZicG8MSPxCPKr9RDqgOXpuEoVm9YR3I4yNE5M0LNltpCTdXRBjTrOcjp+RtEZ1VENtHqTICK18nDqO+91BUt3AJsf4VmzogJ8UpA0izEbY=" }
The publisher performs the following decryption steps:
- Base64 decoding
- Decrypt the string after PKCS7 padding removal
- Decode the string in UTF-8

Example

AES decryption Key and IV: buzzvil123456789

{
  "unit_id":"12345",
  "transaction_id":"10000000_1",
  "user_id":"buzzvil",
  "point": 1,
  "action_type":"won",
  "event_at": 1599622182,
  "title":"title",
  "extra": "{}"
}

Encrypted data from JSON (UTF-8encoding) → AES encryption → base64 encoding

When decrypted:
- base64 decoding
- AES decryption) Key, IV: buzzvil123456789
- UTF-8 decoding
  (memo) Since there is no Korean in the above example, there is no need for UTF-8 decoding

Sample Code

Python 2.7+

Python 3.6+

2. Add Checksum Parameter

Use this method if you want to add a checksum parameter to Request Parameters for postback data verification. The provided verification method is HMAC authentication using the SHA-256 algorithm.