# midas.getBalance
Call this API at the server side. For more information, see Server API.
Gets the game currency balance. For Mini Games that have activated virtual currency, you can use this API to view the currency balance of a user.
# Official Environment
POST https://api.weixin.qq.com/cgi-bin/midas/getbalance?access_token=ACCESS_TOKEN
# Sandbox Environment
POST https://api.weixin.qq.com/cgi-bin/midas/sandbox/getbalance?access_token=ACCESS_TOKEN
# Request Parameters
| Attribute | Type | Default | Required | Description |
|---|---|---|---|---|
| openid | string | Yes | The unique identifier of the user. | |
| appid | string | Yes | The appId of the Mini Program. | |
| offer_id | string | Yes | The offer_id assigned by Midas. | |
| ts | number | Yes | The UNIX timestamp, in seconds. | |
| zone_id | string | Yes | The region ID of the game server, as a string-type value. If the game does not have regions, the default value is zoneId ="1". If the application supports roles, the role ID is placed after the region ID connected by "_". | |
| pf | string | Yes | The platform, e.g. android. | |
| user_ip | string | No | The user’s public network IP address. | |
| sig | string | Yes | A signature calculated from all the above parameters (up to 7 with optional parameters) + uri + Midas key using the HMAC-SHA256 algorithm. For details, see Signature Calculation Algorithm. | |
| access_token | string | Yes | The credentials used to call the API. | |
| mp_sig | string | Yes | A signature calculated from all the above parameters (up to 9 with optional parameters) + uri + session_key using the HMAC-SHA256 algorithm. For details, see Signature Calculation Algorithm. |
# Return Value
# Object
JSON data package that is returned
| Property | Type | Description |
|---|---|---|
| errcode | number | Error code |
| errmsg | string | Error message |
| balance | number | The game currency balance (including gifts). |
| gen_balance | number | The amount of gifted game currency. |
| first_save | boolean | Whether or not this is the first top-up. |
| save_amt | number | Cumulative amount of total game currency a user topped up. |
| save_sum | number | Historical amount of game currency. |
| cost_sum | number | Historical amount of consumed game currency. |
| present_sum | number | Cumulative amount of gift game currency received. |
Valid values of errcode
| Value | Description | Minimum Version |
|---|---|---|
| 0 | Request successful | |
| -1 | System is busy. Try again later. | |
| 90009 | Incorrect mp_sig signature | |
| 90010 | The user is not logged in or the session has expired. | |
| 90011 | Incorrect sig signature | |
| 90017 | You do not have permission to call this API. | |
| 90018 | Parameter error |
Valid values of first_save
| Value | Description | Minimum Version |
|---|---|---|
| 1 | Satisfies conditions | |
| 2 | Does not satisfy conditions |
# POST data format: JSON
{
"openid":"odkx20ENSNa2w5y3g_qOkOvBNM1g",
"appid":"wx1234567",
"offer_id":"12345678",
"ts":1507530737,
"zone_id":"1",
"pf":"android",
"sig":"d1f0a41272f9b85618361323e1b19cd8cb0213f21b935aeaa39c160892031e97",
"mp_sig":"ff4c5bb39dea1002a8f03be0438724e1a8bcea5ebce8f221f9b9fea3bcf3bf76"
}