Lucky Mermaid Merchant API Integration Guide

This is the primary Lucky Mermaid (LM) merchant integration document for technical teams.

1. Integration Flow

Merchant provides onboarding data
  -> LM creates Merchant / Agent
  -> LM configures Agent currencies, games, wallet mode, and IP whitelist
  -> LM issues the Agent API key
  -> Merchant calls LM APIs using the documented signature rules
  -> Both sides verify player creation, transfer, game login, betting, balance, records, and reports
  -> Production switch uses production domains, IP whitelist, and API keys

Lucky Mermaid provides an independent merchant API. Merchants should integrate using the /api/v1 paths, the LM signature model, and the multi-currency player rules described below.

2. Merchant Inputs

If the merchant uses multiple servers or NAT, provide every possible outbound public IP. A single IP should normally be written as CIDR /32, for example 203.0.113.4/32.

3. Platform Configuration

4. Environments and Base URL

POST <base>/api/v1/...
Content-Type: application/json

5. Common Rules

5.1 Request Format

• All requests and responses use UTF-8 JSON.
• Unless explicitly stated, business APIs use POST.
• All business APIs require currency.
• currency must be an uppercase ISO-style currency code, such as CNY, USD, or THB.
• Amounts are decimals in the requested original currency.

5.2 Request Headers

5.3 Common Response

{ "code": 200, "data": {}, "msg": "success" }

• code=200 means success.
• code!=200 means business failure. Check msg and the error-code table.
• For signed business APIs, data is AES encrypted. Examples in this document show the decrypted structure for readability.
• Public catalog APIs return plain JSON and do not encrypt data.

5.4 Time Rules

• Request header timestamp is Unix seconds.
• Business time fields use yyyy-MM-dd HH:mm:ss.
• Business dates use yyyy-MM-dd.
• Merchant API business time is interpreted in GMT+8 unless otherwise agreed.

6. Authentication and Signature

6.1 Signature Flow

1. Prepare the JSON request body.
2. Sort business parameters by key in ascending ASCII order.
3. Serialize as compact JSON.
4. Encrypt the serialized string with the Agent secret using AES.
5. Concatenate the encrypted string with timestamp.
6. Calculate MD5 to produce sign.
7. Send KEY, timestamp, sign, and the encrypted request body.

currency is a business parameter and must participate in the signature.

6.2 AES Rules

• AES key and exact mode are assigned by LM with the Agent API key.
• The encrypted payload should be transmitted as the agreed encoded string.
• The same canonical JSON rules must be used on both sides.

6.3 Signature Example: Create Player

{
  "agentName": "agent01",
  "loginName": "player001",
  "currency": "USD"
}

canonical JSON -> AES encrypt -> encrypted + timestamp -> MD5 sign

6.4 Common Signature Errors

7. Multi-currency Player Model

• A player wallet is identified by agentName + loginName + currency.
• The same loginName can exist under multiple currencies, and balances are separated.
• Transfers, balances, reports, records, login, and test-play requests all use the requested currency.
• If a currency is disabled for the Agent, business APIs should return an unsupported-currency error.

8. Wallet Modes

8.1 Transfer Wallet

In transfer-wallet mode, the merchant transfers funds into or out of the LM player wallet. LM maintains the in-game balance.

• Transfer in before game entry.
• Game bets and settlements update the LM wallet.
• Transfer out after the player leaves the game or when allowed by business rules.
• orderNo must be idempotent under agentName + currency + orderNo.

8.2 Single Wallet

In single-wallet mode, the merchant owns the source of funds. LM calls merchant callbacks using action codes for balance, bet, settlement, cancel-bet, and combined bet-settle requests.

• Merchant callback must be public HTTPS.
• Merchant must provide callback AES Key and AES IV. Key length must be 16/24/32 characters; IV length must be 16 characters.
• Merchant must verify callback signatures against the encrypted outer envelope.
• Merchant must handle retry and idempotency by transferId.
• Balance must stay synchronized after betting and settlement.

Admin configuration:

• Select the wallet mode when creating or editing an Agent.
• Transfer wallet does not require wallet callback configuration.
• Single wallet shows structured fields for callback URL, AES Key, and AES IV.
• The admin UI generates the internal wallet JSON automatically; operators should not edit JSON by hand.

9. API Flows

9.1 Transfer Wallet Flow

createPlayer -> transfer(type=1) -> getBalance -> login -> game bet/settle -> gameRecord -> transferRecord -> transfer(type=2)

9.2 Demo Play Flow

testPlay -> open returned URL -> play with demo funds

9.3 Single Wallet Flow

createPlayer -> login/testPlay -> action=6 balance callback -> action=9 bet callback -> action=10/11/8 settlement callback -> gameRecord

10. API List

10.0 Public Catalog APIs

The currency and game list APIs are plain JSON APIs for documentation, configuration checks, and operational synchronization. Hot Game Top10 is merchant-only: it requires KEY, timestamp, and sign, and returns encrypted data. The live visual catalog is shown in the appendix.

10.1 Transfer Wallet APIs

10.2 Single Wallet APIs

11. API Details

11.1 Query Supported Currencies

GET /api/v1/public/currencyList

11.2 Query Game List

GET /api/v1/public/gameList

11.2.1 Query Hot Game Top10

POST /api/v1/public/hotGameTop10

This merchant-only API requires the same KEY, timestamp, and sign rules as business APIs, and returns encrypted data. It ranks real-account game turnover for the previous calendar month. For example, on 2026-07-03, the ranking period is 2026-06-01 to 2026-06-30.

Request example:

{
  "gameType": 2
}

Response example:

{
  "code": 200,
  "data": "AES_ENCRYPTED_DATA",
  "msg": "Success"
}

Decrypted data example:

[
  {
    "rank": 1,
    "gameId": 1000,
    "gameName": "Flying Dragon Fishing+",
    "gameType": 2,
    "gameTypeName": "Fishing"
  }
]

11.3 Create Player

POST /api/v1/createPlayer

11.4 Login Game

POST /api/v1/login

11.5 Get Demo URL

POST /api/v1/testPlay returns a demo-game URL. Parameters are similar to login, but use demo funds.

11.6 Wallet Transfer

POST /api/v1/transfer is used in transfer-wallet mode. type=1 transfers in, type=2 transfers out. orderNo is idempotent by agentName + currency + orderNo.

11.7 Query Transfer Order

POST /api/v1/transferRecord queries an existing transfer by orderNo and currency. Use it after timeout before retrying with a new order.

11.8 Query Balance

POST /api/v1/getBalance returns the player balance in the requested currency.

11.9 Query Game Records

POST /api/v1/gameRecord returns game records by time range, page, and currency. Amounts are original-currency amounts.

11.10 Get Record Detail Link

POST /api/v1/gameRecordLink returns a URL for viewing a specific game record when supported by the game.

11.11 Daily Detail Report

POST /api/v1/dayReport returns daily detail metrics for the requested currency.

11.12 Multi-day Summary Report

POST /api/v1/summaryReport returns aggregated metrics over a date range.

11.13 Query Player Info

POST /api/v1/playerInfo returns player information for agentName + loginName + currency.

11.14 Force Player Offline

POST /api/v1/kickPlayer requests LM to disconnect a player session.

12. Single Wallet Callback Requirements

For single-wallet mode, merchants must provide a public callback URL. LM sends POST JSON requests using the Lucky Mermaid single-wallet wire format. The HTTP body is an encrypted envelope with dc, x, and parent. The x field contains the encrypted business payload; merchants should verify the outer envelope signature first, then decrypt x, then dispatch by the decrypted action.

The platform admin configuration requires the following fields:

The admin UI uses these fields to generate the internal wallet configuration automatically. Do not require operators to edit JSON directly. For troubleshooting, the internal shape is {"type":"default","data":{"url":"...","key":"...","iv":"..."}}.

12.1 HTTP Body Envelope

The outer HTTP body format is fixed:

{
  "dc": "",
  "x": "ENCRYPTED_PAYLOAD",
  "parent": ""
}

The decrypted x payload contains the business fields. Balance query example:

{
  "action": 6,
  "ts": 1783080000000,
  "uid": "player001",
  "currency": "HKD",
  "gType": 3,
  "mType": 3006,
  "transferId": 1522700686997852160
}

12.2 Callback Actions

12.3 Callback Headers

LM calls merchant callbacks using KEY, timestamp, and sign. The sign is calculated from the outer envelope, not from decrypted business fields: sort dc, x, and parent; serialize compact JSON; encrypt that string with AES/ECB/PKCS5 and standard Base64; append timestamp; then MD5 the result.

Fields such as currency, uid, and action are inside the decrypted x payload. They are protected indirectly because the encrypted x value is part of the signed envelope.

12.4 Decrypted Business Fields

12.5 Callback Response

Merchant responses use the single-wallet callback response format, not the LM merchant API code/data/msg format:

{ "status": "0", "balance": 99.00, "err_text": "", "transferId": 1522700686997852160 }

• Return status="0" or status=0 on success.
• Successful responses must return the current balance.
• Return transferId unchanged when possible for reconciliation.
• Insufficient balance must not deduct funds and should return a non-zero status with clear err_text.
• Repeated transferId must return an equivalent result.

13. Error Codes

14. IP Whitelist and Security

• Merchant server outbound IPs should be added to the LM whitelist.
• Do not submit player IPs as merchant server IPs.
• Agent API keys must be stored server-side only.
• Production and test keys should be separated.
• After a network timeout, use /api/v1/transferRecord to query the original order before deciding whether to retry.
• Single-wallet callback secrets must be stored server-side and must not be mixed with merchant-to-LM API keys.

15. Integration Checklist

15.1 Basic Checks

• Agent has been created.
• Agent API key has been delivered.
• Agent has at least one enabled currency.
• Agent has at least one authorized game.
• Merchant outbound IP is whitelisted.
• Merchant can generate KEY, timestamp, and sign correctly.

15.2 Multi-currency Checks

• Create agent01 + player001 + CNY successfully.
• Create agent01 + player001 + USD successfully.
• Balances in different currencies are independent.
• A USD player cannot use a CNY wallet to enter a game.
• Transfers, balances, records, and reports return original-currency amounts according to request currency.

15.3 Transfer Wallet Checks

• type=1 transfer-in succeeds.
• Balance query is correct.
• Game login succeeds.
• In-game betting updates the balance correctly.
• Game records can be queried by currency.
• type=2 transfer-out succeeds.
• Timeout scenarios can be resolved with transferRecord.
• Repeated orderNo does not duplicate fund changes.

15.4 Single Wallet Checks

• Merchant callback URL is publicly reachable over HTTPS.
• Merchant verifies LM callback signatures against the encrypted outer envelope.
• action=6 returns the correct balance.
• action=9 deducts once and is idempotent by transferId.
• Insufficient balance fails without deduction.
• action=10 adds payout once and is idempotent by transferId.
• action=11 reverses referenced transactions idempotently by refTransferIds.
• Game entry, bet, settlement, and game-record query pass end to end.

16. Appendix: Currency and Game Catalog

The catalog below is loaded live from public APIs. It helps integration teams look up the current currency codes and gameId values.