ChizPay Wallet & Transactions

BASE API: https://api.chizmis.com

ChizPay is a centralized wallet and ledger service. Wallet balances are stored by ChizPay, and every balance movement is recorded as an internal ledger transaction. Game integrations should use stable referenceNumber values for idempotency and debitTransactionId to link credits back to the debit they settle.

Security Model

Protected endpoints require authorization: Bearer <token>.

Write endpoints that move funds require replay-protected request fields:

Name	Type	Required	Description
`nonce`	string	Yes	Unique one-time request ID. Never reuse a nonce.
`timestamp`	number	Yes	Epoch milliseconds. Requests outside the allowed time window are rejected.
`signature`	string	Yes	HMAC or server-issued request signature used to validate request integrity.

The signature proves request integrity for the API call. It is not derived from player credentials and does not authorize external settlement.

Wallet Model

{
  id: number
  accountId: number
  balance: number
  isActive: boolean
  account?: {
    id: number
    firstName?: string | null
    lastName?: string | null
    email?: string | null
    avatar?: string | null
  }
  createdAt: string
  updatedAt: string
}

Wallet APIs

Get Wallet by Account ID

Retrieves the centralized wallet state for a player.

Method & URL

GET /chizpay/v1.0/wallets/by-account/:accountId

Headers

Name	Type	Required	Description
`authorization`	string	Yes	Bearer access token. Example: `Bearer <token>`.

Response Example

{
  "success": true,
  "response": {
    "id": 9123,
    "accountId": 67890,
    "balance": 2500,
    "isActive": true,
    "account": {
      "id": 67890,
      "firstName": "Juan",
      "lastName": "Dela Cruz",
      "email": "juan@example.com",
      "avatar": "https://cdn.example.com/avatar.png"
    },
    "createdAt": "2026-05-06T10:00:00.000Z",
    "updatedAt": "2026-05-06T10:15:00.000Z"
  }
}

Error Responses

Status	Meaning	Example Message
`400`	Invalid `accountId` format	`Account ID is required`
`401`	Unauthorized	`Unauthorized`
`404`	Wallet not found	`Wallet not found for the provided account ID`

Wallet Transaction APIs

Transfer Wallet Balance

Transfers balance from one user wallet to another through paired internal ledger rows.

Method & URL

POST /chizpay/v1.0/wallet-transactions

Headers

Name	Type	Required	Description
`authorization`	string	Yes	Bearer access token.

Request Body

Name	Type	Required	Description
`senderAccountId`	number	Yes	Account ID of the sender.
`receiverAccountId`	number	Yes	Account ID of the recipient.
`amount`	number	Yes	Amount to transfer. Must be greater than `0`.
`referenceNumber`	string	No	Idempotency or business reference. If omitted, ChizPay generates one.
`nonce`	string	Yes	Unique one-time nonce.
`timestamp`	number	Yes	Request timestamp in epoch milliseconds.
`signature`	string	Yes	Request integrity signature.

{
  "senderAccountId": 1001,
  "receiverAccountId": 2002,
  "amount": 50,
  "referenceNumber": "transfer_20260506_0001",
  "nonce": "b3d9a8f2-7fb2-4f45-a22a-2c52b602ef74",
  "timestamp": 1778062500000,
  "signature": "hmac-sha256:5a7f..."
}

Response Example

{
  "success": true,
  "response": {
    "senderTx": {
      "id": 50101,
      "accountId": 1001,
      "walletId": 9123,
      "type": "SEND",
      "bound": "OUT",
      "amount": 50,
      "status": "COMPLETED",
      "referenceNumber": "transfer_20260506_0001"
    },
    "receiverTx": {
      "id": 50102,
      "accountId": 2002,
      "walletId": 8450,
      "type": "RECEIVE",
      "bound": "IN",
      "amount": 50,
      "status": "COMPLETED",
      "referenceNumber": "transfer_20260506_0001"
    }
  }
}

Get Wallet Transaction History

Returns paginated wallet transactions for a user.

Method & URL

GET /chizpay/v1.0/wallet-transactions/history/:accountId

Query Parameters

Name	Type	Required	Description
`page`	number	No	Page number starting at `1`.
`limit`	number	No	Rows per page.
`type`	string	No	Filter by transaction type.
`bound`	string	No	Filter by `IN` or `OUT`.
`status`	string	No	Filter by transaction status.

Response Example

{
  "success": true,
  "response": {
    "rows": [
      {
        "id": 50102,
        "accountId": 2002,
        "senderAccountId": 1001,
        "receiverAccountId": 2002,
        "walletId": 8450,
        "type": "RECEIVE",
        "bound": "IN",
        "amount": 50,
        "status": "COMPLETED",
        "referenceNumber": "transfer_20260506_0001",
        "createdAt": "2026-05-06T10:15:00.000Z"
      }
    ],
    "count": 1,
    "filters": {
      "bound": "IN",
      "type": "RECEIVE",
      "status": "COMPLETED"
    }
  }
}

Game Transaction API

Debit Wallet

Debits a user's wallet for a game stake, entry fee, purchase, or round cost.

Method & URL

POST /chizpay/v1.0/wallet-transactions/debit

Request Body

Name	Type	Required	Description
`gameId`	string	Yes	Game identifier.
`gameSession`	string	Yes	Game Manager session or round identifier.
`accountId`	number	Yes	Account whose wallet will be debited.
`amount`	number	Yes	Amount to debit.
`referenceNumber`	string	Yes	Idempotency key for this debit.
`description`	string	No	Human-readable ledger description.
`metadata`	object	No	Game context stored with the ledger row.
`nonce`	string	Yes	Unique one-time nonce.
`timestamp`	number	Yes	Request timestamp in epoch milliseconds.
`signature`	string	Yes	Request integrity signature.

{
  "gameId": "game-slots-01",
  "gameSession": "sess_123",
  "accountId": 1001,
  "amount": 50,
  "referenceNumber": "debit_sess_123_round_12",
  "description": "Round stake",
  "metadata": {
    "round": 12,
    "betType": "STANDARD"
  },
  "nonce": "2993f3b0-84aa-4dc3-9599-4f277631f9e8",
  "timestamp": 1778063100000,
  "signature": "hmac-sha256:03ac..."
}

Response Example

{
  "success": true,
  "response": {
    "transactionId": "debit_sess_123_round_12",
    "debitTx": {
      "id": 80101,
      "walletId": 9123,
      "gameId": "game-slots-01",
      "gameSession": "sess_123",
      "accountId": 1001,
      "type": "DEBIT",
      "bound": "OUT",
      "amount": 50,
      "referenceNumber": "debit_sess_123_round_12",
      "status": "COMPLETED"
    }
  }
}

Credit Wallet

Credits a user's wallet for a win, refund, reward, or rollback and links the credit to the debit being settled.

Method & URL

POST /chizpay/v1.0/wallet-transactions/credit

Request Body

Name	Type	Required	Description
`gameId`	string	Yes	Game identifier.
`gameSession`	string	Yes	Game Manager session or round identifier.
`accountId`	number	Yes	Account whose wallet will be credited.
`amount`	number	Yes	Amount to credit.
`debitTransactionId`	number	Yes	Existing `DEBIT` ledger row ID.
`referenceNumber`	string	Yes	Idempotency key for this credit.
`description`	string	No	Human-readable ledger description.
`metadata`	object	No	Game context stored with the ledger row.
`nonce`	string	Yes	Unique one-time nonce.
`timestamp`	number	Yes	Request timestamp in epoch milliseconds.
`signature`	string	Yes	Request integrity signature.

{
  "gameId": "game-slots-01",
  "gameSession": "sess_123",
  "accountId": 1001,
  "amount": 95,
  "debitTransactionId": 80101,
  "referenceNumber": "credit_sess_123_round_12",
  "description": "Round payout",
  "metadata": {
    "round": 12,
    "result": "WIN"
  },
  "nonce": "52663c0d-6f42-4baf-8a45-3951d2ff89f5",
  "timestamp": 1778063220000,
  "signature": "hmac-sha256:85df..."
}

Response Example

{
  "success": true,
  "response": {
    "transactionId": "credit_sess_123_round_12",
    "creditTx": {
      "id": 80102,
      "walletId": 9123,
      "gameId": "game-slots-01",
      "gameSession": "sess_123",
      "accountId": 1001,
      "type": "CREDIT",
      "bound": "IN",
      "amount": 95,
      "debitTransactionId": 80101,
      "referenceNumber": "credit_sess_123_round_12",
      "status": "COMPLETED"
    }
  }
}

Get Game Ledger

Returns paginated debit and credit ledger entries for a game.

Method & URL

GET /chizpay/v1.0/wallet-transactions/ledger/:gameId

Query Parameters

Name	Type	Required	Description
`gameSession`	string	No	Filter by tracked session or round.
`accountId`	number	No	Filter by player.
`type`	enum(`DEBIT`, `CREDIT`)	No	Filter by ledger type.
`status`	string	No	Filter by status.
`page`	number	No	Page number.
`limit`	number	No	Rows per page.

Response Example

{
  "success": true,
  "response": {
    "rows": [
      {
        "id": 80101,
        "walletId": 9123,
        "gameId": "game-slots-01",
        "gameSession": "sess_123",
        "accountId": 1001,
        "type": "DEBIT",
        "bound": "OUT",
        "amount": 50,
        "status": "COMPLETED",
        "referenceNumber": "debit_sess_123_round_12",
        "debitTransactionId": null
      },
      {
        "id": 80102,
        "walletId": 9123,
        "gameId": "game-slots-01",
        "gameSession": "sess_123",
        "accountId": 1001,
        "type": "CREDIT",
        "bound": "IN",
        "amount": 95,
        "status": "COMPLETED",
        "referenceNumber": "credit_sess_123_round_12",
        "debitTransactionId": 80101
      }
    ],
    "count": 2,
    "filters": {
      "gameSession": "sess_123",
      "accountId": 1001,
      "type": null,
      "status": null
    }
  }
}

ChizPay Wallet & Transactions API

Security Model#

Wallet Model#

Wallet APIs#

Get Wallet by Account ID#

Method & URL#

Headers#

Response Example#

Error Responses#

Wallet Transaction APIs#

Transfer Wallet Balance#

Method & URL#

Headers#

Request Body#

Response Example#

Get Wallet Transaction History#

Method & URL#

Query Parameters#

Response Example#

Game Transaction API#

Debit Wallet#

Method & URL#

Request Body#

Response Example#

Credit Wallet#

Method & URL#

Request Body#

Response Example#

Get Game Ledger#

Method & URL#

Query Parameters#

Response Example#

Security Model

Wallet Model

Wallet APIs

Get Wallet by Account ID

Method & URL

Headers

Response Example

Error Responses

Wallet Transaction APIs

Transfer Wallet Balance

Method & URL

Headers

Request Body

Response Example

Get Wallet Transaction History

Method & URL

Query Parameters

Response Example

Game Transaction API

Debit Wallet

Method & URL

Request Body

Response Example

Credit Wallet

Method & URL

Request Body

Response Example

Get Game Ledger

Method & URL

Query Parameters

Response Example