5. Integration API

5.1 Operator Provided API

5.1.1 API Formats

5.1.1.1 Request

The API uses HTTP form methods and a RESTful endpoint structure. PGSoft will send requests in the following content type: Content-Type: application/x-www-form-urlencoded

5.1.1.2 Response

API returns JSON-formatted responses. For successful and failed API request, operator is required to return an API response with HTTP status code 200. API uses global JSON response format for all API methods, with the following content type: Content-Type: application/json

Parameters:

Parameter name	Data Type	Description
data	JSON Object	Response information for API methods
error	JSON Object	Error information when an error or exception occur

Example:

Success Response

{
    "data": {
        [API method response. JSON object format may vary depending on API methods]
    },
    "error": null,
}

Failed/Error Response

{
    "data": null,
    "error": {
        "code": "[Error code]",
        "message": "[Error message]"
    }
}

5.1.1.3 Hash Authentication (Optional)

We highly recommend that operator integrate with hash authentication to secure every request. If operator choose to integrate with hash authentication, PGSoft system will validate the hash information provided in the header fields in every request.

5.1.1.3.1 Header Fields

The following table describes the various request headers in the preceding example:

Component	Description
Host	API domain Example: apiexample.pgsoft.com
x-date	Current date (UTC) in YYYYMMDD format Example: `20190902`
x-content-sha256	SHA256 hash of the request string body Example: `1700116101f424b9f6fc695b4dbaf2b7b0ee763ba1b3b53298e3069143ed46f1`
Authorization	Combination of various components for requesting authentication Example: `PWS-HMAC-SHA256<br/>Credential=20190902/OPERATORTOKENEXAMPLE/pws/v1,SignedHeaders=host;x-content-sha256;x-date,Signature=d78220cf06ae85f9d1db11dad9c3fd926799619eab3d28574aadb8cf328cd7aa`

Example

Host: apiexample.pgsoft.com
x-date: 20190902
x-content-sha256:
1700116101f424b9f6fc695b4dbaf2b7b0ee763ba1b3b53298e3069143ed46f1
Authorization: PWS-HMAC-SHA256
Credential=20190902/OPERATORTOKENEXAMPLE/pws/v1,SignedHeaders=host

;x-content-sha256;x-
date,Signature=d78220cf06ae85f9d1db11dad9c3fd926799619eab3d28574aa

db8cf328cd7aa

Header: x-content-sha256

Calculate a SHA256 hash of the request string body:

POST body:
operator_token=abc123&secret_key=a1b25cde5f3gh46ijkl&count=5000&be
t_type=1&row_version=1346592723000
x-content-sha256:
1700116101f424b9f6fc695b4dbaf2b7b0ee763ba1b3b53298e3069143ed46f1

Header: Authentication

The following table describes the various components of the Authorization header value in the preceding example:

5.1.1.3.2 Header Authentication

Component	Description
Credential	Your access key ID and the scope information, which includes the date, operator token, and service that were used to calculate the signature. This string has the following form: `{x-date}/{operator_token}/pws/v1` Example: `20190902/OPERATORTOKENEXAMPLE/pws/v1`
SignedHeaders	Current date (UTC) in YYYYMMDD format Example: 20190902
x-content-sha256	SHA256 hash of the request string body Example: 1700116101f424b9f6fc695b4dbaf2b7b0ee763ba1b3b53298e3069143ed46f1
Authorization	Combination of various components for requesting authentication Example: PWS-HMAC-SHA256 Credential=20190902/OPERATORTOKENEXAMPLE/pws/v1,SignedHeaders=host;x-content-sha256;x-date,Signature=d78220cf06ae85f9d1db11dad9c3fd926799619eab3d28574aadb8cf328cd7aa

To calculate a signature, you first need a string that includes {host}{x-content-sha256}{x-date}" to sign. You will then calculate a HMAC-SHA256 hash of the string to sign by using a signing key:

HMAC,"hmac-sha256(\{salt}, \{host}\{x-content-sha256}\{x-date})"

Calculate a HMAC-SHA256 hash of the string body:

Example

Salt : SALTEXAMPLE

Host : apiexample.pgsoft.com

x-date : 20190902

x-content-sha256 : 1700116101f424b9f6fc695b4dbaf2b7b0ee763ba1b3b53298e3069143ed46f1

Signature : d78220cf06ae85f9d1db11dad9c3fd926799619eab3d28574aadb8cf328cd7aa

5.1.2 Verify Session

PG SOFT game system will call this operator API to check the player session token generated when players login to game.

Note:

This API is required for URL scheme or web lobby authorization mode 14
New player will be created automatically

Request

API URL : {OperatorAPIDomain}/VerifySession HTTP method : POST

URL Parameters:

Parameter name	Data Type	Mandatory	Description
trace_id	String	Yes	Unique identity (GUID) of the request Note Please set the parameter value as GUID format

Body Parameters:

Parameter name	Data Type	Mandatory	Description
operator_token	String	Yes	Unique identity of operator
secret_key	String	Yes	Shared passphrase between PG SOFT and operator
operator_player_session	String	Yes	Token generated by operator's system when the game is launched (URL Scheme)
game_id	Integer	No	Unique identity of games
ip	String	No	Player IP address
custom_parameter	String	No	operator_param values in URL scheme
bet_type	Integer	Yes	Game launch mode

Example:

URL:

https://operator.api/VerifySession?trace_id=b3f37e57-2873-40b1-aa95-f126c25ed311

Body operator_token=abc123&secret_key=a1b25cde5f3gh46ijkl&operator_player_session=a2b3c 4d5e6f7g8&game_id=1&ip=1.1.1.1&custom_parameter=operatorparam123&bet_type=1

Validation

Operator is required to perform validations to the following parameters:

Here is the data converted into CSV format:

Parameter name	Description	Expected behavior
operator_token	Make sure the parameter value is the same as the one PG SOFT has provided.	Return error when not match
secret_key
operator_player_session	Make sure the operator_player_session matches with the token generated in URL scheme

Response

Body Parameters: JSON Object

Parameter name	Data type	Mandatory	Description
player_name	String	Yes	"Unique identity of players - player name is not case sensitive - Only alphabet, number, and "@", "-", "_" symbols are allowed Note: Max 50 characters"
nickname	String	No	Nickname of player Note: Max 50 characters"
currency	String	Yes	Currency of player"

Example:

{
    "data": {
        "player_name": "player1",
        "nickname":"nickname",
        "currency": "USD"
    },
    "error": null
}

Error Response

Code	Message
1034	Invalid request
3005	Player wallet does not exist

5.1.3 Wallet Operation (For Seamless Mode only)

5.1.3.1 Get Player Wallet

Operator is required to provide the total balance of the wallets that can be used in all PG SOFT games. It includes total balance in the cash wallet.

Request

API URL : {OperatorAPIDomain}/Cash/Get HTTP method : POST

URL Parameters:

Parameter name	Data Type	Mandatory	Description
trace_id	String	Yes	Unique identity (GUID) of the request Note: This ID is for issue troubleshooting only. Please do not use this ID in duplicate request validation

Body Parameters:

Parameter name	Data Type	Mandatory	Description
operator_token	String	Yes	Unique identity of operator
secret_key	String	Yes	Shared passphrase between PG SOFT and operator
player_name	String	Yes	Unique identity of players
operator_player_session	String		Token generated by operator's system when the game is launched (URL Scheme)
game_id	Integer	No	Unique identity of games

Example:

URL:

https://operator.api/Cash/Get?trace_id=b3f37e57-2873-40b1-aa95-f126c25ed311

Body operator_token=abc123&secret_key=a1b25cde5f3gh46ijkl&player_name=player123&operato r_player_session=a2b3c4d5e6f7g8&game_id=1

Validation

Operator is required to perform validation to the following parameters:

Parameter_name	Description	Expected behaviour
operator_token	Make sure the parameter value is the same as the one PG SOFT has provided.
secret_key		Return error when not match
player_name	Make sure the parameter value matches the given player's name in Verify Session19

Response

Body Parameters: JSON Object

Parameter name	Data type	Mandatory	Description
currency_code	String	Yes	Currency of player
balance_amount	Decimal	Yes	Cash Balance of player Note: - Supports up to 2 decimal places - Extra decimal values will be truncated. Example: Game will show 11.12 if balance_amount value is 11.125
updated_time	Long	Yes	Updated time of player record (Unix time stamp in milliseconds)

Example

{
    "data": {
        "currency_code": "CNY",
        "balance_amount": 11.12,
        "updated_time": 1530879795000
    },
    "error": null
}

Error Response

Code	Message
1034	Invalid request
3005	Player wallet does not exist

5.1.3.2 Bet & Payout

PG SOFT system will expect idempotent operations for all API operations. Operator is required to perform duplicate request checking for all incoming transaction requests. PG SOFT may resend the transaction due to network difficulties or other unforeseen circumstances. Please refer to the following for the precautions and correct process flow to handle duplicated requests:

Operator is required to perform validation of operator_token and secret_key for every transaction request.
transaction_id is the only unique identifier for every transaction request, including bet and payout.
In the case where a request with the same transaction_id is found and operator has proceeded the previous request, please ignore the duplicated request, and return the previous successful response for the duplicated request.
In the case where a request with the same transaction_id is found and the previous request has failed, please retry, and return the corresponding results to PG SOFT.
In the case of a request with new transaction_id, operator may proceed to wallet addition or deduction accordingly, and return the successful response to PG SOFT.

Game Disconnected

In the case where players are encountering errors and have been disconnected from the game, PG SOFT system will automatically resume the game from its previous stage (including free spin, bonus, free game) without any alert on the next player login. Player will see the same screen before the error happened and will be able to continue the game from the previous stage.

Failed Transaction

PG SOFT games will stop and show errors when PG SOFT receives the following error codes during bet transactions:

3004 PlayerNotFoundException
3005 WalletNotFoundException
3008 BonusNotFoundException
3009 FreeGameNotFoundException
3019 NotEnoughFreeGameException
3021 BetNotFoundException
3055 SnapshotNotFoundException
3059 BetLimitExceededException
3062 TransactionRolledBackException
3073 BetFailedException
3200 NotEnoughBalanceException
3201 NotEnoughBonusBalanceException
3202 NotEnoughCashBalanceException
3094 MaximumBetLimitReachErrorCode
3095 BalanceDecreasesLimitReachErrorCode

Operator should not cancel the pay-out transaction for a successful bet. System will always retry for a pay-out transaction until it is successful. Please contact PG SOFT if you would like to cancel the pay-out transaction.

5.1.3.2.1 Bet Payout

This transaction request is the combination of both bet and payout within a single request. PG SOFT system will call operator API in real time while the player is betting to achieve either the addition or deduction of the player's balance. Operator is required to respond within 10 seconds or API timeout will happen.

Request

API URL : {OperatorAPIDomain}/Cash/TransferInOut

HTTP method : POST

URL Parameters:

Parameter name	Data Type	Mandatory	Description
trace_id	String	Yes	Unique identity (GUID) of the request Note: Please set the parameter value as GUID format

Body Parameters:

Category	Parameter name	Data Type	Mandatory	Description
Authentication Information	operator_token	String	Yes	Unique identity of operator
	secret_key	String	Yes	Shared passphrase between PG SOFT and operator
	operator_player_session	String	No	Token generated by operator system when game is launched (URL Scheme)
General Bet Information	player_name	String	Yes	Unique identity of players
	game_id	Integer	Yes	Unique identity of games
	parent_bet_id	String	Yes	Unique identity of parent bet
	bet_id	String	Yes	Unique identity of child bet Note: Unique key for bets
	currency_code	String	Yes	Currency of player
	bet_amount	Decimal	Yes	Bet amount. Note: PG SOFT will send a bet request with ZERO transfer amount for free spins
	win_amount	Decimal	Yes	Win amount. Note: PG SOFT will send a payout request with ZERO transfer amount for the following: - Every action (Example: split card) performed by player in card games - Special feature in some slot games
	transfer_amount	Decimal	Yes	Player Win Loss amount Note: The amount can be positive or negative Negative: Balance deduction Positive: Balance addition
	transcation_id	String	Yes	Unique identity of transaction. Format: `{BetId}-{ParentBetId}-{transactionType}-{balanceId}` Transaction type:106: BetPayout 400: BonusToCash 403: FreeGameToCash Note: - Max 50 characters
	wallet_type	String	No	To indicate the type of wallet for the current transaction. C: Cash B: Bonus G: FreeGame
	bet_type	Integer	Yes	Bet types of bet record: 1: Real game
	platform	String	No	Platform of player
	create_time	Long	Yes	Bet start time and bet last updated time (Unix time stamp in milliseconds) Note: updated_time is not equal to bet end time
	updated_time	Long	Yes
Bet Indicator	is_validate_bet	Boolean	No	To indicate if the request is a transaction that has been resent for validation True: Resent transaction False: Normal transaction

	is_adjustment	Boolean	No	To indicate if the request is an adjustment or a normal transaction for a pending bet True: Adjustment False: Normal transaction
	is_parent_zero_stake	Boolean	No	To indicate if the request is having 0 bet amount for the first bet of the round. True: Having 0 bet amount for the first bet of the round (For Bacarrat Deluxe’s free hands action) False: Having amount larger than 0 in the first bet of the round
	is_feature	Boolean	No	To indicate the spin type True: Feature spin False: Normal spin
	is_feature_buy	Boolean	No	To indicate the feature buy Note: Only applicable for feature buy games
	is_wager	Boolean	No	To indicate if the transaction is wager True: bet_amount > 0 False: bet_amount = 0
	is_end_round	Boolean	No	To indicate if the current game hand has ended
Free Game Information	free_game _transaction_id	String	No	Unique identity of free game. It can only be seen when Free Game has been assigned to the player Note: Only available for free game created using External API
	free_game_name	String	No	Given name of free game. It can only be seen when Free Game has been assigned to the player
	free_game_id	Integer	No	Unique identity of free game. It can only be seen when Free Game has been assigned to the player
	is_minus_count	Boolean	No	To indicate the spin type in free game True: Normal spin (Free game count is deducted) False: Free spin
Bonus Game Information	bonus_transaction_id	String	No	Unique identity of bonus game. It can only be seen when Bonus Game has been assigned to the player Note: Only available for bonus game created using External API
	bonus_name	String	No	Given name of bonus game. It can only be seen when Bonus Game has been assigned to the player
	bonus_id	Integer	No	Unique identity of bonus game. It can only be seen when Bonus Game has been assigned to the player
	bonus_balance_amount	Decimal	No	Total number of bonus amount in bonus wallet. It can only be seen when the player chooses to complete the bonus with cash.
	bonus_ratio_amount	Decimal	No	Rollover amount the player needs to achieve in bonus game. It can only be seen when the player chooses to complete the bonus with cash.

Example

URL:

https://operator.api/Cash/TransferInOut?trace_id=b3f37e57-2873-40b1-aa95-f126c25ed311

Body:

operator_token=12345&secret_key=bfvcdbplayer_name=player123&operator_player_session=vcbcvbcvb&game_id=1&parent_bet_id=123456&bet_id=123456&bet_type=1&currency_code=EUR&create_time=1530879795000&updated_time=1530879795000&bet_amount=100&win_amount=40&transfer_amount=-60&transaction_id=123456-123456-106-0&wallet_type=C&is_feature=False&is_minus_count=False

Validation

Operator is required to perform validation to the following parameters:

Parameter name	Description	Expected behaviour
player_name	Make sure the parameter value matches the given player information in Verify Session	Return error when not match
currency_code
operator_token	Make sure the parameter value is the same as the one PG SOFT has provided.
secret_key
operator_player_session	Make sure the operator_player_session matches the token generated in URL scheme	Return successful response even with outdated operator_player_session
	Do not validate operator_player_session when is_validate_bet or is_adjustment parameter value is true Note: PG SOFT system may resend request for validation or pending bet
transfer_amount	Make sure there is an error response when there is insufficient balance	Return error response 3202
	Make sure zero bet amount is accepted for parent bet Note: PG SOFT system will send a bet request with ZERO transfer amount for Bacarrat Deluxe’s free hands action	Return successful response with the correct cash balance
	Make sure zero bet amount is accepted for child bet Note: PG SOFT system will send a bet request with ZERO transfer amount for free spin
transaction_id	Ignore wallet operation for duplicated requests (Requests with the same transaction_id)
parent_bet_id	Proceed wallet operation for request with the same game hand (Requests with the same parent_bet_id but different bet_id)
bet_id

Response

Body Parameters: JSON Object

Parameter name	Data type	Mandatory	Description
currency_code	String	Yes	Currency of player
balance_amount	Decimal	Yes	Cash Balance of player Note: - Support up to 2 decimal places - Extra decimal values will be truncated. Example: Game will show 11.12 if balance_amount value is 11.125
updated_time	Long	Yes	Updated time of transaction (Unix time stamp in milliseconds) Note: Response updated_time must be the same as the requested updated_time for transaction reference

Example:

{
    "data": {
            "currency_code": "CNY",
            "balance_amount": 11.12,
            "updated_time": 1530879795000
        },
    "error": null
}

Error Response

Code	Message
3004	Player does not exist
3005	Player wallet does not exist
3021	Bet does not exist
3033	Bet failed
3202	Insufficient player balance

5.1.3.3 Balance Adjustment

PG SOFT will use this API to perform player’s balance addition or deduction. This API can be used for certain events, such as Cash Tournament.

Request

API URL : {OperatorAPIDomain}/Cash/Adjustment

HTTPmethod : POST

Body parameters:

Category	Parameter name	Data Type	Mandatory	Description
Authentication Information	operator_token	String	Yes	Unique identity of operator
	secret_key	String	Yes	Shared passphrase between PG SOFT and operator
General Bet Information	player_name	String	Yes	Unique identity of players
	currency_code	String	Yes	Currency of player
	transfer_amount	Decimal	Yes	Adjustment Amount Negative amount: Balance deduction Positive amount: Balance addition
	adjustment_id	String	Yes	Reference ID for Adjustment
	adjustment_transaction_id	String	Yes	Unique identity of transaction Note: - Max 200 characters - Operator should use this parameter to check if the request is duplicated and implement idempotent operation
	adjustment_time	Long	Yes	Adjustment time (Unix time stamp in milliseconds)
	transaction_type	String	Yes	Adjustment source: 115: Promotion 900: External Adjustment 901: Tournament Adjustment
	bet_type	Integer	Yes	Game launch mode
	promotion_id	Integer	No	Reference ID for Promotion
	promotion_type	Integer	No	Promotion Type: 1: Money Rain 2: Money Rain Daily Bonus 3: Daily Cashpot
	remark	String	No	Remark for Balance Adjustment

Example

operator_token=abc123&secret_key=a1b25cde5f3gh46ijkl&player_name=player123&bet_typ e=1&currency_code=CNY&transfer_amount=100.00&adjustment_time=1530879795000&adjustm ent_id=ABC1530879&adjustment_transactionid=ABC1530879-900&transaction_type=900

Validation

Operator is required to perform validation to the following parameters:

Parameter name	Description	Expected behaviour
player_name	Make sure the parameter value matches the given player information in Verify Session	Return error when not match
currency_code
operator_token	Make sure the parameter value is the same as the one PG SOFT has provided.
secret_key
transfer_amount	Make sure there is an error response when there is insufficient balance (negative transfer_amount)	Return error response 3202
	Make sure player balance after adjustment (amount with 2 decimal places) is correct	Return successful response with the correct balance
	Make sure negative amount is accepted
	Make sure the adjustment performs correctly and accordingly - Negative: Balance deduction - Positive: Balance addition
adjustment_transaction_id	Ignore wallet operation for duplicated requests (Request with same transaction_id)

Response

Body Parameters: JSON Object

Parameter name	Data type	Mandatory	Description
adjust_amount	Decimal	Yes	Adjusted Amount Note: - This amount is for reference purpose. PG SOFT will not validate it. - Response adjust_amount must be the same as the requested transfer_amount for transaction reference
balance_before	Decimal	Yes	Player balance before adjustment (balance_before) & Player balance after adjustment (balance_after) Note: - Only support up to 2 decimals - Extra decimal values will be truncated. Example: Game will show 11.12 if balance_amount value is 11.125
updated_time	Long	Yes	Updated time of transaction (Unix time stamp in milliseconds) Note: Response updated_time must be the same as the requested updated_time for transaction reference

Example

{
    "data": {
      "adjust_amount": 100.00,
      "balance_before": 0.00,
      "balance_after": 100.00,
      "updated_time": 1530879795000
    },
    "error": null
}

Error Response

Code	Message
3004	Player does not exist
3005	Player wallet does not exist

5.1.3.4 Update Bet Details

PG SOFT game system will call this operator API to update the operator’s latest bet end time when the bet is successful in PG SOFT system.

Request

API URL : {OperatorAPIDomain}/Cash/UpdateBetDetail

HTTP method : POST

Body Parameters:

Parameter name	Data Type	Mandatory	Description
operator_token	String	Yes	Unique identity of operator
secret_key	String	Yes	Shared passphrase between PG SOFT and operator
bet_details	Json Array	Yes	List of bet ID with bet end time
updated_time	Long	Yes	API request time (Unix time stamp in milliseconds)

Parameter: bet_details

Parameter name	Data Type	Mandatory	Description
bet_id	String	Yes	Unique identity of child bet Note: Unique key for bets
end_time	Long	Yes	Bet end time (Unix time stamp in milliseconds)

Example: operator_token=abc123&secret_key=a1b25cde5f3gh46ijkl&bet_details=[{"bet_id":"1456887894","e nd_time":"1644476958000"},{"bet_id":"1456887895","end_time":"1644476958000"}]&updated_ti me=1645414794000

Validation

Operator is required to perform validation to the following parameters

Parameter name	Description	Expected behavior
operator_token	Make sure the parameter value is the same as the one PG SOFT has provided.	Return error when not match
secret_key

Response

Body Parameters: JSON Object

Parameter name	Data Type	Mandatory	Description
is_success	Boolean	Yes	To indicate if the request is received True: Received False: Not Received

Example

{
    "data": {
        "is_success": true,
    },
    "error": null,
}

5.2 PG SOFT Provided API

5.2.1 API Formats

5.2.1.1 Request

The API uses HTTP form methods and a RESTful endpoint structure. Operator is required to send requests in the following content type:

Content-Type: application/x-www-form-urlencoded

5.2.1.2 Response

API returns JSON-formatted responses. For successful and failed API requests, PG SOFT system will return an API response with HTTP status code 200.

API uses global JSON response format for all API methods, with the following content type:

Content-Type: application/json

Parameters

Parameter name	Data Type	Description
data	JSON Object	Response information for API methods
error	JSON Object	Error information when an error or exception occur

Example

Successful Response

{
    "data": {
        [API method response. JSON object format may vary depending on API methods]
    },
    "error": null,
}

Failed/Error Response

{
    "data": null,
    "error": {
        "code": "[Error code]",
        "message": "[Error message]" 
    }
}

5.2.2 Check Player’s Balance (For Transfer Mode only)

To check a specific player's balance.
Request

API URL : {PgSoftAPIDomain}/Cash/v3/GetPlayerWallet
HTTP method : POST

URL Parameter:

Parameter name	Data Type	Mandatory	Description
trace_id	String	Yes	Unique identity (GUID) of the request Note: Please set the parameter value as GUID format

Body Parameter:

Parameter name	Data Type	Mandatory	Description
operator_token	String	Yes	Unique identity of operator
secret_key	String	Yes	Shared passphrase between PGSoft and operator
player_name	String	Yes	Unique identity of players

Example:

URL:
https://api.pg-bo.me/external/Cash/v3/GetPlayerWallet?trace_id=b3f37e57-2873-40b1-aa95-f126c25ed311

Body:
operator_token=abc123&secret_key=a1b25cde5f3gh46ijkl&player_name=player123

Response
Body Parameters:
JSON Object

Parameter name	Data type	Description
currencyCode	String	Currency of player Summation of all player wallet balance: - Cash balance - Bonus balance - Free game balance
totalBalance	Decimal	Summation of all player wallet balance: - Cash balance - Bonus balance - Free game balance
cashBalance	Decimal	Player's cash wallet balance Operator may refer to this value for player's balance
totalBonusBalance	Decimal	Player’s bonus wallet balance. This will show all the available bonus balance of a player. It cannot be transferred out.
freeGameBalance	Decimal	Player’s free game wallet balance. This will show all the available free game balance of a player. It cannot be transferred out.
bonuses	JSON Array	Player's bonus game details
freeGames	JSON Array	Player's free game details
cashWallet	JSON Object	Player's cash wallet details
key	String	Unique identity of cash wallet
cashId	Integer	Unique identity of player's cash wallet
cashBalance	Decimal	Player's balance of cash
bonusWallet	JSON Object	Player's bonus wallet details
totalBonusBalance	Decimal	Summation of player's bonus wallet balance
freeGameWallet	JSON Object	Player's free game wallet details
freeGameBalance	Decimal	Summation of player's free game wallet balance

JSON Array (Bonus Game)

Parameter name	Data type	Description
key	String	Unique identity of bonus wallet.
bonusId	Integer	Unique identity of bonus game. It can only be seen after Bonus Game has been assigned to the player.
bonusName	String	Given name of bonus game. It can only be seen after Bonus Game has been assigned to the player.
transactionId	String	Unique identity of transaction
bonusParentType	String	Type of bonus parent: Bonus: Bonus game that was created normally FreeGame: Bonus game that was converted from free game
gameIds	Integer Array	Unique identity of games
gameIdLock	Integer	An unfinished game's ID
balanceAmount	Decimal	Player's balance of bonus game
bonusRatioAmount	Decimal	Wagering requirement for bonus game. Refer to the total amount that needs to be completed after the amount won in bonus game has been transferred to the bonus wallet
minimumConversionAmount	Decimal	The minimum amount of bonus game to cash conversion
maximumConversionAmount	Decimal	The maximum amount of bonus game to cash conversion
status	Integer	Status of bonus wallet: 0: Inactive (Cancelled) 1: Active 2: Expired 3: Converted 4: Completed 5: New 6: User Cancelled 7: Locked 8: Pending
createdDate	Long	Created date of bonus game (Unix time stamp in milliseconds)
expiredDate	Long	Expiry date of bonus game (Unix time stamp in milliseconds)
createdBy	String	API or BackOffice user who created the bonus game
updatedBy	String	API or BackOffice user who updated the bonus game Allowing a player to cancel an offer:
isSuppressDiscard	Boolean	True: Does not allow a player to cancel offer False: Allows a player to cancel offer

JSON Array (Free Game)

Parameter name	Data type	Description
key	String	Unique identity of free game wallet
freeGameId	Integer	Unique identity of free game It can only be seen after Free Game has been assigned to the player.
freeGameName	String	Given name of free game It can only be seen after Free Game has been assigned to the player.
transactionId	String	Unique identity of transaction
gameIds	Integer Array	Unique identity of games
gameIdLock	Integer	An unfinished game's ID
gameCount	Integer	Total number of remaining free games
totalGame	Integer	Total number of given free games
balanceAmount	Decimal	Player's balance of free game
minimumConversionAmount	Decimal	The minimum amount of free game to cash conversion
maximumConversionAmount	Decimal	The maximum amount of free game to cash conversion
multiplier	Integer	Bet multiplier of free game
coinSize	Decimal	Coin size of free game
createdDate	Long	Created date of free game (Unix time stamp in milliseconds)
expiredDate	Long	Expiry date of free game (Unix time stamp in milliseconds)
status	Integer	Status of free game wallet: 0: Inactive (Cancelled) 1: Active 2: Expired 3: Converted 4: Completed 5: New 6: User Cancelled 7: Locked 8: Pending
conversionType	Char	Type of conversion after free game is completed: C: Cash B: Bonus
createdBy	String	API or BackOffice user who created the free game
updatedBy	String	API or BackOffice user who updated the free game
isSuppressDiscard	Boolean	Allowing a player to cancel an offer: True: Does not allow a player to cancel offer False: Allows a player to cancel offer

Example:

{
    "data": {
        "currencyCode": "CNY",
        "totalBalance": 50732.39,
        "cashBalance": 48853.39,
        "totalBonusBalance": 1815.00,
        "freeGameBalance": 64.00,
        "bonuses": [
            {
                "key": "11019-97090_B",
                "bonusId": 11019,
                "bonusName": "PG Bonus ",
                "transactionId": "",
                "bonusParentType": "Bonus",
                "gameIds": [
                    94,
                    69,
                    71
                ],
                "gameIdLock": 0,
                "balanceAmount": 1000.00,
                "bonusRatioAmount": 1000.00,
                "minimumConversionAmount": 0.00,
                "maximumConversionAmount": 0.00,
                "status": 5,
                "createdDate": 1615952183000,
                "expiredDate": 1640966399000,
                "createdBy": "operator1",
                "updatedBy": "operator1",
                "isSuppressDiscard": true
            }
        ],
        "freeGames": [
            {
            "key": "575-16084_G",
            "freeGameId": 575,
            "freeGameName": "FREE GAME",
            "transactionId": "",
            "gameIds": [
                33
            ],
            "gameIdLock": 0,
            "gameCount": 0,
            "totalGame": 100,
            "balanceAmount": 0.00,
            "minimumConversionAmount": 0.00,
            "maximumConversionAmount": 0.00,
            "multiplier": 6,
            "coinSize": 0.1,
            "createdDate": 1544582329000,
            "expiredDate": 1544630399000,
            "status": 3,
            "conversionType": "C",
            "createdBy": "operator2",
            "updatedBy": "operator2",
            "isSuppressDiscard": false
            }
        ],
        "cashWallet": {
            "key": "0_C",
            "cashId": 0,
            "cashBalance": 48853.39
        },
        "bonusWallet": {
            "totalBonusBalance": 1815.00,
            "bonuses": [
                {
                "key": "11019-97090_B",
                "bonusId": 11019,
                "bonusName": "PG Bonus ",
                "transactionId": "",
                "bonusParentType": "Bonus",
                "gameIds": [
                    94,
                    69,
                    71
                ],
                "gameIdLock": 0,
                "balanceAmount": 1000.00,
                "bonusRatioAmount": 1000.00,
                "minimumConversionAmount": 0.00,
                "maximumConversionAmount": 0.00,
                "status": 5,
                "createdDate": 1615952183000,
                "expiredDate": 1640966399000,
                "createdBy": "operator3",
                "updatedBy": "operator3",
                "isSuppressDiscard": true
                }
            ]
        },
        "freeGameWallet": {
        "freeGameBalance": 64.00,
        "freeGames": [
                {
                    "key": "575-16084_G",
                    "freeGameId": 575,
                    "freeGameName": "FREE GAME",
                    "transactionId": "",
                    "gameIds": [
                        33
                    ],
                    "gameIdLock": 0,
                    "gameCount": 0,
                    "totalGame": 100,
                    "balanceAmount": 0.00,
                    "minimumConversionAmount": 0.00,
                    "maximumConversionAmount": 0.00,
                    "multiplier": 6,
                    "coinSize": 0.1,
                    "createdDate": 1544582329000,
                    "expiredDate": 1544630399000,
                    "status": 3,
                    "conversionType": "B",
                    "createdBy": "operator4",
                    "updatedBy": "operator4",
                    "isSuppressDiscard": false
                }
            ]
        }
    },
    "error": null
}

Error Response:

Code	Message
3001	Value cannot be null
3005	Player wallet does not exist

5.2.3 Transfer In and Transfer Out (For Transfer Mode only)

PGSoft systems are implementing idempotent operations for all API operations. Operator is required to resend the request by using the same transfer_reference for the following scenarios:

Received incorrect response (incorrect response format) from PGSoft system.
Received response with error code other than 3001, 3005 or 3100.
Did not receive a response from PGSoft system.

5.2.3.1 Transfer In

To transfer cash into a specific player's cash wallet.
Note:

Transfer_reference is the unique identifier for every transaction. Operator is required to send new transfer_reference for every transfer request.
For duplicated requests, PGSoft will not update the player’s wallet balance, and will return a successful response for the duplicated request.

Request

API URL : {PgSoftAPIDomain}/Cash/v3/TransferIn
HTTP method : POST

URL Parameter:

Parameter name	Data Type	Mandatory	Description
trace_id	String	Yes	Unique identity (GUID) of the request Note: Please set the parameter value as GUID format

Body Parameter:

Parameter name	Data Type	Mandatory	Description
operator_token	String	Yes	Unique identity of operator
secret_key	String	Yes	Shared passphrase between PGSoft and operator
player_name	String	Yes	Unique identity of players
amount	Decimal	Yes	Transfer in amount (2 decimal place) Note: Min 0.01
currency	String	Yes	Currency of player
transfer_reference	String	Yes	Transfer reference, generated by operator to make sure the transfer is unique Note: Max 50 characters

Example:

URL:
https://api.pg-bo.me/external/Cash/v3/TransferIn?trace_id=b3f37e57-2873-40b1-aa95-f126c25ed311

Body:
operator_token=abc123&secret_key=a1b25cde5f3gh46ijkl&player_name=player123&amount=0.30&transfer_reference=ref1530879795000&currency=EUR

Response
Body Parameters:
JSON Object

Parameter name	Data type	Description
transactionId	String	Unique transaction identifier
balanceAmountBefore	Decimal	Player's balance before transaction
balanceAmount	Decimal	Player's balance after transaction
amount	Decimal	Transaction amount

Example:

{
    "data": {
        "transactionId": 35509540,
        "balanceAmountBefore": 1000.00,
        "balanceAmount": 1100.00,
        "amount": 100.00
    },
    "error": null
}

Error Response

Code	Message
3001	Value cannot be null
3005	Player wallet does not exist
3100	Wallet transaction failed
3101	Wallet transaction in progress, please retry again

5.2.3.2 Transfer Out

To transfer out cash from a specific player's cash wallet.
Note:

Transfer_reference is the unique identifier for every transaction. Operator is required to send new transfer_reference for every transfer request.
For duplicated requests, PGSoft will not update player’s wallet balance, and will return a successful response for the duplicated request.

Request

API URL : {PgSoftAPIDomain}/Cash/v3/TransferOut
HTTP method : POST

URL Parameter:

Parameter name	Data Type	Mandatory	Description
trace_id	String	Yes	Unique identity (GUID) of the request Note: Please set the parameter value as GUID format

Body Parameter:

Parameter name	Data Type	Mandatory	Description
operator_token	String	Yes	Unique identity of operator
secret_key	String	Yes	Shared passphrase between PGSoft and operator
player_name	String	Yes	Unique identity of players
amount	Decimal	Yes	Transfer in amount (2 decimal place) Note: Min 0.01
currency	String	Yes	Currency of player
transfer_reference	String	Yes	Transfer reference, generated by operator to make sure the transfer is unique Note: Max 50 characters

Example:

URL:
https://api.pg-bo.me/external/Cash/v3/TransferOut?trace_id=b3f37e57-2873-40b1-aa95-f126c25ed311

Body:
operator_token=abc123&secret_key=a1b25cde5f3gh46ijkl&player_name=player123&amount=0.30&transfer_reference=ref1530879795000&currency=EUR

Response
Body Parameters:
JSON Object

Parameter name	Data type	Description
transactionId	String	Unique transaction identifier
balanceAmountBefore	Decimal	Player's balance before transaction
balanceAmount	Decimal	Player's balance after transaction
amount	Decimal	Transaction amount

Example:

{
    "data": {
        "transactionId": 35509540,
        "balanceAmountBefore": 1000.00,
        "balanceAmount": 1100.00,
        "amount": 100.00
    },
    "error": null
}

Error Response

Code	Message
3001	Value cannot be null
3005	Player wallet does not exist
3100	Wallet transaction failed
3101	Wallet transaction in progress, please retry again

5.2.4 Wallet Operation Restriction and Handling (For Transfer Mode only)

Performing a wallet transaction and launching a game at the same time is prohibited to avoid errors in player’s balance. In such cases, PGSoft will restrict the player and return an error response for the wallet API request:

1305: Invalid player - Player is locked: [playername]

Error Handling
1305
Operator should resend the wallet transaction request if they receive this error. PGSoft systems are implementing idempotent operations for all API operations. Operator is required to resend the request by using the same transfer_reference to avoid multiple balance transfer.

3004
PGSoft will return this error if an unhandled error occurs while creating a player. Operator may recreate the player’s wallet by External API or relaunching the PGSoft game to create the player automatically.

1315
PGSoft will return this error when encountering the following scenarios:

Concurrent actions (For example: The player launched the game with two different browsers at the same time, etc.).
Player launched the game or a spin in the game while doing a transaction at the same time.
Player wallet not found.
Encountering errors during the wallet transfer.

Operator should retry the wallet transaction request after 5 minutes if they receive this error.

5.2.5 Transfer All Out (Optional - For Transfer Mode only)

To transfer out all cash wallet amount from a specific player's cash wallet.

Note:

Transfer_reference is the unique identifier for every transaction. Operator is required to send new transfer_reference for every transfer request.
For duplicated requests, PGSoft will not update player’s wallet balance, and will return a successful response for the duplicated request.
This API is to clean up a player’s wallet balance. The system will NOT return any error if the player has no balance. Operator is required to check the player’s before and current balance amount in the API response to confirm the actual withdrawal amount to avoid missing balance.

Request

API URL : {PgSoftAPIDomain}/Cash/v3/TransferAllOut
HTTP method : POST

URL Parameter:

Parameter name	Data Type	Mandatory	Description
trace_id	String	Yes	Unique identity (GUID) of the request Note: Please set the parameter value as GUID format

Body Parameter:

Parameter name	Data Type	Mandatory	Description
operator_token	String	Yes	Unique identity of operator
secret_key	String	Yes	Shared passphrase between PGSoft and operator
player_name	String	Yes	Unique identity of players
transfer_reference	String	Yes	Transfer reference, generated by operator to make sure the transfer is unique Note: Max 50 characters
currency	String	Yes	Currency of player

Example:

URL:
https://api.pg-bo.me/external/Cash/v3/TransferAllOut?trace_id=b3f37e57-2873-40b1-aa95-f126c25ed311

Body:
operator_token=abc123@secret_key=a1b25cde5f3gh46ijkl&player_name=player123&transfer_reference=ref153087975000&currency=EUR

Response:

Parameter name	Data Type	Description
transactionId	String	Unique transaction identifier
balanceAmountBefore	Decimal	Player’s balance before transaction
balanceAmount	Decimal	Player’s balance after transaction
amount	Decimal	Transaction amount

Example:

{
    "data": {
            "transactionId":12458888,
            "balanceAmountBefore": 47238.07,
            "balanceAmount": 0,
            "amount": 47238.07,
        },
    "error": null
}

Error Response:

Code	Message
3001	Value cannot be null
3005	Player wallet does not exist

5.2.6 Get Single Transaction History (Optional - For Transfer Mode only)

To get a single transaction history of a specific player by searching the transfer reference and player’s username.

Note:

This API can be only called after 5 minutes of the last transaction.

Request

API URL : {PgSoftAPIDomain}/Cash/v3/GetSingleTransaction
HTTP method : POST

URL Parameters:

Parameter name	Data Type	Mandatory	Description
trace_id	String	Yes	Unique identity (GUID) of the request Note: Please set the parameter value as GUID format

Body Parameter:

Parameter name	Data Type	Mandatory	Description
operator_token	String	Yes	Unique identity of operator
secret_key	String	Yes	Shared passphrase between PGSoft and operator
player_name	String	Yes	Unique identity of players
transfer_reference	String	Yes	Transfer reference, generated by operator to make sure the transfer is unique Note: Max 50 characters

Example:

URL:
https://api.pg-bo.me/external/Cash/v3/GetSingleTransaction?trace_id=b3f37e57-2873-
40b1-aa95-f126c25ed311

Body:
operator_token=abc123&secret_key=a1b25cde5f3gh46ijkl&player_name=player123&transfe
r_reference=ref1530879795000

Response
Body Parameters:
JSON Object

Parameter name	Data Type	Description
transactionId	String	Unique transaction identifier
playerName	String	Unique identity of players
currencyCode	String	Currency of player
transactionType	Integer	Transaction type: 100: TransferInCash 200: TransferOutCash
transactionAmount	Decimal	Transaction amount
transactionFrom	Decimal	Wallet balance before transaction
transactionTo	Decimal	Wallet balance after transaction
transactionDateTime	Long	Transaction date & time (Unix time stamp in milliseconds)

Example:

{
    "data": {
        "transactionId": 35595943,
        "playerName": "player123",
        "currencyCode": "EUR",
        "transactionType": 100,
        "transactionAmount": 1000000.00000,
        "transactionFrom": 0.00,
        "transactionTo": 1000000.00,
        "transactionDateTime": 1522984865000

        },
    "error": null
}

Error Response:

Code	Message
3040	Transaction does not exist

5.2.7 Bet History Interpreter (Optional)

To reveal a player’s bet results and details for specific bet.

Step 1

Before getting the bet detail, operator is required to call this API to get operator's session (Session timeout: 30 minutes).

Request

API URL : {PgSoftAPIDomain}/Login/v1/LoginProxy

HTTP method : POST URL Parameters:

URL Parameters:

Parameter name	Data Type	Mandatory	Description
trace_id	String	Yes	Unique identity (GUID) of the request Note Please set the parameter value as GUID format

Body Parameters:

Parameter name	Data Type	Mandatory	Description
operator_token	String	Yes	Unique identity of operator
secret_key	String	Yes	Shared passphrase between PG SOFT and operator

Example: URL: https://api.pg-bo.me/external/Login/v1/LoginProxy?trace_id=b3f37e57-2873-40b1-aa95-f126c25ed311

Body:

operator_token=abc123&secret_key=a1b25cde5f3gh46ijkl

Response

Body Parameters: JSON Object

Parameter name	Data Type	Description
operator_session	String	Operator session

Example:

{
    "data": {
        "operator_session":"E4ECB5CF-0BC6-4DA8-8551-8526F48AB9CD"
    },
    "error": null
}

Step 2

Get bet detail by:

API URL : {PgSoftPublicDomain}/history/redirect.html HTTP method : Get

URL Parameters:

Parameter name	Data Type	Description
trace_id	String	Unique identity (GUID) of the request Note Please set the parameter value as GUID format
t	String	Operator session from Step 1
psid	String	Parent Bet ID
sid	String	Bet ID
lang	String	Language: - en(default) - zh
type	String	Fixed value: operator

Example:

https://public.pg-redirect.net/history/redirect.html?trace_id=b3f37e57-2873-40b1-aa95-f126c25ed311&t=E4ECB5CF-0BC6-4DA8-8551-8526F48AB9CD&psid=12345&sid=12345&lang=en&type=operator

5.2.8 Get Multiple Players’ Wallet Balance (Optional - For Transfer Mode only)

To get the wallet balance of multiple players (max 10 players).
Note:

The maximum amount of players’ wallet balance that can be obtained is 10.

Request

API URL : {PgSoftAPIDomain}/Cash/v3/GetPlayersWallet
HTTP method : POST

URL Parameters:

Parameter name	Data Type	Mandatory	Description
trace_id	String	Yes	Unique identity (GUID) of the request Note: Please set the parameter value as GUID format

Body Parameter:

Parameter name	Data Type	Mandatory	Description
operator_token	String	Yes	Unique identity of operator
secret_key	String	Yes	Shared passphrase between PGSoft and operator
player_names	String Array	Yes	Unique identity of players

Example:

URL:
https://api.pg-bo.me/external/Cash/v3/GetPlayersWallet?trace_id=b3f37e57-2873-40b1-aa95-f126c25ed311

Body:
operator_token=abc123&secret_key=a1b25cde5f3gh46ijkl&player_names=player1&player_names=player2

Response
Body Parameters:
JSON Object

Parameter name	Data Type	Description
totalCount	Integer	Total number of records
totalPage	Integer	Total number of available batches
result	JSON Array	List of details of a player’s wallet

JSON Array

Parameter name	Data Type	Description
playerName	String	Name of player
currencyCode	String	Currency of player
totalBalance	Decimal	Player’s wallet balance

Example:

{
    "data": {
        "totalCount": 2,
        "totalPage": 1,
        "result": [
            {
                "playerName": "player1",
                "currencyCode": "CNY",
                "totalBalance": 33.59
            },
            {
                "playerName": "player2",
                "currencyCode": "CNY",
                "totalBalance": 2000061103.84
            }
        ]
    },
    "error": null
}

Error Response:

Code	Message
3001	Value cannot be null
3005	Player wallet does not exist

5.2.9 Others (Optional)

PG SOFT provides several APIs for different modules that are optional for integration. Operator may choose to integrate based on their requirements:

Bet History: To get a player’s bet history
Game List: To get the latest game list and available bet sizes
Free Game: To perform several actions (For example: Create free game, assign player into free game, cancel free game, etc.) through API.
Bonus Game: To perform several actions (For example: Create bonus game, assign player into bonus game, cancel bonus game, etc.) through API.
Tournament: To get tournament list, add player into tournament and get tournament ranking through API.

5.3 Integrate PG SOFT Game into Operator’s iOS Application

Operator’s application needs to meet the following requirements to launch PG SOFT games in the application client:

iOS 8.0 or above
WKWebView

PG SOFT game will prompt a “Poor Visit Experience” message if it does not meet the minimum requirements. Players are allowed to continue launching the game but it may not guarantee a stable, and high performance experience of the PG SOFT game.

To ensure the application client passes the PG SOFT game requirement check, operator is required to include the following codes when initializing WKWebView component in application:

This is to construct a WKUserContentController object and set its userContentController property on the configuration. Please take note that the userContentController must have at least one scriptMessageHandler (assign through addScriptMessageHandler)

For more details regarding WKWebView, please refer to Apple Developer Documentation

5. Integration API

5.1 Operator Provided API​

5.1.1 API Formats​

5.1.1.1 Request​

5.1.1.2 Response​

5.1.1.3 Hash Authentication (Optional)​

5.1.1.3.1 Header Fields​

5.1.1.3.2 Header Authentication​

5.1.2 Verify Session​

5.1.3 Wallet Operation (For Seamless Mode only)​

5.1.3.1 Get Player Wallet​

5.1.3.2 Bet & Payout​

5.1.3.2.1 Bet Payout​

5.1.3.3 Balance Adjustment​

5.1.3.4 Update Bet Details​

5.2 PG SOFT Provided API​

5.2.1 API Formats​

5.2.1.1 Request​

5.2.1.2 Response​

5.2.2 Check Player’s Balance (For Transfer Mode only)​

5.2.3 Transfer In and Transfer Out (For Transfer Mode only)​

5.2.3.1 Transfer In​

5.2.3.2 Transfer Out​

5.2.4 Wallet Operation Restriction and Handling (For Transfer Mode only)​

5.2.5 Transfer All Out (Optional - For Transfer Mode only)​

5.2.6 Get Single Transaction History (Optional - For Transfer Mode only)​

5.2.7 Bet History Interpreter (Optional)​

5.2.8 Get Multiple Players’ Wallet Balance (Optional - For Transfer Mode only)​

5.2.9 Others (Optional)​

5.3 Integrate PG SOFT Game into Operator’s iOS Application​

5.1 Operator Provided API

5.1.1 API Formats

5.1.1.1 Request

5.1.1.2 Response

5.1.1.3 Hash Authentication (Optional)

5.1.1.3.1 Header Fields

5.1.1.3.2 Header Authentication

5.1.2 Verify Session

5.1.3 Wallet Operation (For Seamless Mode only)

5.1.3.1 Get Player Wallet

5.1.3.2 Bet & Payout

5.1.3.2.1 Bet Payout

5.1.3.3 Balance Adjustment

5.1.3.4 Update Bet Details

5.2 PG SOFT Provided API

5.2.1 API Formats

5.2.1.1 Request

5.2.1.2 Response

5.2.2 Check Player’s Balance (For Transfer Mode only)

5.2.3 Transfer In and Transfer Out (For Transfer Mode only)

5.2.3.1 Transfer In

5.2.3.2 Transfer Out

5.2.4 Wallet Operation Restriction and Handling (For Transfer Mode only)

5.2.5 Transfer All Out (Optional - For Transfer Mode only)

5.2.6 Get Single Transaction History (Optional - For Transfer Mode only)

5.2.7 Bet History Interpreter (Optional)

5.2.8 Get Multiple Players’ Wallet Balance (Optional - For Transfer Mode only)

5.2.9 Others (Optional)

5.3 Integrate PG SOFT Game into Operator’s iOS Application