AG GAME以精立业 · 以质取胜
Русский
Связаться

Публичный API · V5.0.0

Техническая справка для B2B-интеграции Slots

Текущая публичная справка содержит 17 конечных точек, четыре схемы и восемь FAQ. Она помогает подготовить технический объём, но не раскрывает реальные URL, учётные данные и конфигурации производственной среды.

Публичная справка, а не полный производственный контракт

Здесь опубликованы каталог конечных точек, метод подписи, характерные поля и обезличенные примеры. Реальный базовый URL, учётные данные, окончательные обратные вызовы, все ограничения полей и производственная конфигурация передаются в контролируемом процессе интеграции. Операции возврата средств и конфигурации мерчанта раскрывают только назначение, не точные пути.

Аутентификация и подпись

Каждый запрос использует JSON и POST. Передавайте код мерчанта, метку времени, одноразовый идентификатор и HMAC-SHA256 подпись; подпись рассчитывается по окончательной JSON-строке. Ключи хранятся только в контролируемой серверной среде, отдельно для тестовой и производственной среды.

ЗаголовокТипОбязательноНазначение
X-MERCHANT-CODEstringДаMerchant code assigned to the platform
X-TIMESTAMPstringДаTimestamp at the time of the request
X-NONCEstringДаRandom string used for each request
X-SIGNstringДаRequest signature generated with HmacSHA256
X-CONTENT-PROCESSING-TYPEstringДаContent-processing type supplied according to the integration configuration

17 публично описанных возможностей

В каталоге ниже представлены все 17 возможностей V5.0.0: поставщики, категории, игры, сессии, принудительное завершение, обратные вызовы единого кошелька, операции переводного кошелька, записи игр и контролируемые запросы мерчанта.

Каталог игр и сессии

  • POST /game/v5/providers — List game providers
  • POST /game/v5/categories — List game categories
  • POST /game/v5/games — List games with pagination
  • POST /game/v5/game/url — Create a player game session and obtain a launch URL
  • POST /game/v5/player/force/logout — Force the end of a player game session

Callback единого кошелька

  • POST {MERCHANT-URL}/wallet/balance — Query a player wallet balance
  • POST {MERCHANT-URL}/player/info — Query player information
  • POST {MERCHANT-URL}/wallet/bet — Receive a bet notification
  • POST {MERCHANT-URL}/wallet/win — Receive a settlement or bet-settlement notification
  • POST {MERCHANT-URL}/wallet/cancel — Receive an order-cancellation notification

Переводной кошелёк

  • POST /game/v5/cash/deposit — Transfer funds into a player game wallet
  • POST /game/v5/cash/withdraw — Transfer funds out of a player game wallet
  • POST /game/v5/cash/balance — Query a player game-wallet balance
  • POST /game/v5/cash/transaction — List wallet transaction records with pagination
  • POST {CONTROLLED-PATH:FUND-RECOVERY} — Recover all funds from a player game wallet through a controlled operation

Записи и мерчант

  • POST /game/v5/game/record — List game records with pagination
  • POST {CONTROLLED-PATH:MERCHANT-CONFIGURATION} — Query merchant configuration and wallet information through a controlled operation

POST/game/v5/game/urlCreate game session

Creates a game session for a specified player and returns a URL that can launch the game.

Authentication: common request headersContent-Type: application/json

Request fields

ПолеТипОбязательноОписание
reqTraceIdstringRequiredUnique request identifier; must not be reused
gameCodestringRequiredGame code
playerIdstringRequiredUnique player identifier on the merchant side
currencyCodestringRequiredWallet currency code
languagestringRequiredGame-interface language
terminalTypestringOptionalTerminal type: PHONE or PC; PHONE by default
returnUrlstringOptionalReturn URL after the player leaves the game
ipAddressstringRequiredPlayer IPv4 or IPv6 address
subMerchantCodestringOptionalSub-merchant code; cannot contain an underscore
nickNamestringOptionalPlayer nickname
avatarUrlstringOptionalPlayer avatar URL
Request
{
  "reqTraceId": "trace-demo-001",
  "gameCode": "{game-code}",
  "playerId": "player-demo-001",
  "currencyCode": "{currency-code}",
  "language": "en",
  "terminalType": "PC",
  "returnUrl": "https://{merchant-host}/lobby",
  "ipAddress": "192.0.2.10"
}
Response
{
  "code": "C10000",
  "msg": "Request succeeded",
  "success": true,
  "data": {
    "gameCode": "{game-code}",
    "playerId": "player-demo-001",
    "gameUrl": "https://{game-launch-host}/session/{token}",
    "expireTime": "2026-08-08T10:30:00Z"
  }
}

Поля ответа

ПолеТипВозвращаетсяОписание
data.gameCodestringRequiredGame code
data.playerIdstringRequiredPlayer identifier
data.gameUrlstringRequiredGame launch URL
data.expireTimestringOptionalSession expiry time

POST{MERCHANT-URL}/wallet/winWallet settlement callback

In single-wallet mode, the platform sends a payout or bet-settlement notification to the merchant wallet. The merchant should process the transaction idempotently and return the resulting balance in the response.

Direction: platform → merchantType: win / bet_win

Request fields

ПолеТипОбязательноОписание
reqTraceIdstringRequiredUnique request identifier
playerIdstringRequiredUnique player identifier on the merchant side
currencyCodestringRequiredWallet currency code
gameCodestringRequiredGame code
transactionIdstringRequiredUnique platform transaction identifier
roundIdstringRequiredUnique game-round identifier
betIdstringRequiredRelated bet identifier
betAmountstringRequiredBet amount for this transaction
winAmountstringRequiredPayout amount for this transaction
isFreebooleanRequiredWhether the record was generated by a free game
isEndbooleanRequiredWhether the current game round has ended
betTimestringRequiredBet time
settledTimestringRequiredSettlement time
typestringRequiredNotification type: win or bet_win
Callback request
{
  "reqTraceId": "trace-demo-002",
  "playerId": "player-demo-001",
  "currencyCode": "{currency-code}",
  "gameCode": "{game-code}",
  "transactionId": "txn-demo-002",
  "roundId": "round-demo-001",
  "betId": "bet-demo-001",
  "betAmount": "10.00",
  "winAmount": "18.50",
  "isFree": false,
  "isEnd": true,
  "betTime": "2026-08-08T10:00:00Z",
  "settledTime": "2026-08-08T10:00:08Z",
  "type": "bet_win"
}
Merchant response
{
  "code": "C10000",
  "msg": "Request succeeded",
  "success": true,
  "data": {
    "merchantBetId": "merchant-bet-demo-001",
    "balance": "108.50"
  }
}

POST/game/v5/cash/depositTransfer funds into game wallet

In transfer-wallet mode, transfers the specified amount from the merchant side into a player game wallet.

Wallet model: transfer walletTransaction key: merchantTransactionId

Request fields

ПолеТипОбязательноОписание
reqTraceIdstringRequiredUnique request identifier used for request tracing
playerIdstringRequiredUnique player identifier on the merchant side
currencyCodestringRequiredWallet currency code
amountstringRequiredTransfer amount
merchantTransactionIdstringRequiredUnique merchant transaction identifier used for transaction reconciliation
Request
{
  "reqTraceId": "trace-demo-003",
  "playerId": "player-demo-001",
  "currencyCode": "{currency-code}",
  "amount": "100.00",
  "merchantTransactionId": "merchant-txn-demo-001"
}
Response
{
  "code": "C10000",
  "msg": "Request succeeded",
  "success": true,
  "data": {
    "balance": "100.00"
  }
}
Transaction reconciliation

Generate a unique merchantTransactionId for every transfer and retain the request and business result so that the final status can be reconciled through the transaction-query endpoint.

POST/game/v5/game/recordQuery game records

Queries a player's bet and payout records by time range with pagination.

Request fields

ПолеТипОбязательноОписание
reqTraceIdstringRequiredUnique request identifier
pageNumintegerRequiredPage number
pageSizeintegerRequiredRecords per page
reqData.startTimestringRequiredQuery start time
reqData.endTimestringRequiredQuery end time
sortstringOptionalSort order
Request
{
  "reqTraceId": "trace-demo-004",
  "pageNum": 1,
  "pageSize": 50,
  "reqData": {
    "startTime": "2026-08-08T00:00:00Z",
    "endTime": "2026-08-08T23:59:59Z"
  },
  "sort": "DESC"
}
Response
{
  "code": "C10000",
  "msg": "Request succeeded",
  "success": true,
  "data": {
    "gameRecordList": [{
      "orderNo": "order-demo-001",
      "playerId": "player-demo-001",
      "betAmount": "10.00",
      "winAmount": "18.50",
      "betTime": "2026-08-08T10:00:00Z",
      "winTime": "2026-08-08T10:00:08Z",
      "gameCode": "{game-code}",
      "currencyCode": "{currency-code}",
      "roundId": "round-demo-001"
    }]
  }
}

Коды ошибок

КодСообщениеДействие
C10000Request succeededRequest succeeded
C10001Base service exceptionBase service exception
C10002Request parameter errorCheck request fields and data types
C10003Invalid request headerCheck the five common request headers
C10004Signature errorCheck signing order, key and original request body
C20001Merchant code absentCheck the merchant code
G10001Game service exceptionGame service exception
G20001Player ID emptyProvide playerId
G20002Game ID absentCheck the game code
G20003Game offlineThe game is offline or unavailable
G30001Game user session expiredCreate a new game session
G30002Merchant balance insufficientMerchant balance is insufficient
G30003Player balance insufficientPlayer balance is insufficient
G40001Third-party service exceptionThird-party service exception

Технические FAQ

How does AG API generate a request signature?

Serialize the final request body as body, then concatenate merchantCode + timestamp + nonce + signType + body in that order without separators. signType is fixed as HmacSHA256. Compute HMAC-SHA256 with the signing key and place the result in X-SIGN. The body used for signing must be exactly the same as the body sent.

Why is C10004 returned?

C10004 indicates signature verification failure. First check the merchant code, timestamp, nonce, signing key and fixed HmacSHA256 type. Then confirm that middleware has not reserialized the signed JSON string, changed field order or changed whitespace. Keep reqTraceId and the request time for diagnosis, but never record the signing key.

What is the difference between single wallet and transfer wallet?

In single-wallet mode, the merchant maintains the player balance and the platform collaborates with the merchant wallet through balance, bet and settlement callbacks. In transfer-wallet mode, the merchant calls endpoints such as /game/v5/cash/deposit and /game/v5/cash/withdraw to transfer funds between the merchant system and the player game wallet. The model used depends on the merchant integration configuration and should not be mixed within the same transaction flow.

How should repeated wallet callbacks be handled?

The merchant should use transactionId as the idempotency basis for callback transactions. When the same transaction arrives again, return the previously confirmed processing result and balance; do not debit or credit it again. Retain the request, business result and final balance for reconciliation. Whether /wallet/bet and /wallet/cancel are required remains subject to the merchant's final callback list.

Can a transfer request be retried directly after a timeout?

Do not create a new transaction and repeat the transfer while the result is unknown. First use the original merchantTransactionId to call /game/v5/cash/transaction and query the result, then decide whether to resend according to the final technical agreement. This avoids duplicate accounting when the first request succeeded but its response was lost on the network.

What are reqTraceId and merchantTransactionId used for?

reqTraceId is the unique tracking identifier for each request. It is used to associate call logs and diagnose one request; it should be generated and recorded per request even when retrying. merchantTransactionId is the merchant-side unique transaction identifier, used for transfer reconciliation, result queries and preventing the same business transaction from being processed repeatedly. They have different purposes and cannot replace one another.

How is a player game session created?

Obtain an available gameCode from the game catalog, prepare the player identifier, currency, language and IP address, then call /game/v5/game/url with the common request headers. A successful response returns gameUrl and may return expireTime; the client should open the URL while the session is valid.

How are player game records queried?

Call /game/v5/game/record with pageNum, pageSize, and the reqData.startTime and reqData.endTime range; sort can be supplied when needed. Read order, player, bet amount, payout, game code and round records from gameRecordList in the response, and continue querying by page.

Запланировать интеграцию

AG GAME

Обсудим ваш проект