> For the complete documentation index, see [llms.txt](https://docs.coda.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coda.co/https-coda-payments.gitbook.io-zhong-wen-coda-private-technical-documentation/codashop-yu-distrubution/ji-cheng-zhi-nan/topup-api-qing-qiu/topup-api-qing-qiu-shi-li-yu-xiang-ying.md).

# Top-Up API 请求示例与响应

#### 示例

格式：JSON-RPC

```javascript
// 
{
  "id": "6164699909785264260",
  "jsonrpc": "2.0",
  "method": "topup",
  "params": [
    {
      "isForTest": 1,
      "price": {
        "amount": "50000",
        "currency": "IDR"
      },
      "serviceProvider": "Coda",
      "quantity": 1,
      "paymentChannelId": 227,
      "sku": "Diamonds_10",
      "purchaseOrigin": "TH",
      "user": {
        "userId": "111111",
        "zoneId": "101",
        "roleId": "111"
      },
      "signature": "73d173363f6706d59c35bcea785f543488389b68d582a9b2339e9450db177695",
      "txnId": "6164699909785264260",
      "orderId": "6164699909782101750",
      "merchantTransactionId": "816176257914769"
    }
  ]
}
```

<table><thead><tr><th width="235.37762451171875">参数名称</th><th width="116.6302490234375">类型</th><th>描述</th></tr></thead><tbody><tr><td>id</td><td>字符串</td><td>唯一标识此次 API 调用的 ID。</td></tr><tr><td>jsonrpc</td><td>字符串</td><td>固定为 "2.0"，符合 json-rpc 标准。</td></tr><tr><td>method</td><td>字符串</td><td>固定为 "validate"。</td></tr><tr><td>params.serviceProvider</td><td>字符串</td><td>支付服务提供商名称，默认值为 "Coda"，合作伙伴可自定义。</td></tr><tr><td>params.isForTest</td><td>整数</td><td>是否为测试订单的标志：1 表示沙盒测试订单，0 表示真实订单。</td></tr><tr><td>params.signature</td><td>字符串</td><td>根据消息内容生成的签名，详见签名生成部分。</td></tr><tr><td>params.user.userId</td><td>字符串</td><td>用户在合作伙伴系统中的用户 ID 或玩家 ID。</td></tr><tr><td>params.user.zoneId</td><td>字符串</td><td>用户在合作伙伴系统中的区服 ID，若不需要则为 ""（空字符串）。</td></tr><tr><td>params.price.currency</td><td>字符串</td><td>货币代码，采用 ISO 4217 标准，例如 "USD"、"CNY"。</td></tr><tr><td>params.price.amount</td><td>字符串</td><td>用户支付的金额，单位为所指定货币。</td></tr><tr><td>params.sku</td><td>字符串</td><td>商品 ID，例如 "Diamonds_123"，用于标识虚拟商品。</td></tr><tr><td>params.purchaseOrigin</td><td>字符串</td><td>用户购买时所在国家/地区，使用 ISO 两位国家代码（如 "SG"、"US"）。</td></tr><tr><td>params.quantity</td><td>整数</td><td>所购买的商品数量，通常为 1。</td></tr><tr><td>params.paymentChannelId</td><td>整数</td><td>支付渠道的 ID，详见文档第 6 节。</td></tr><tr><td>params.txnId</td><td>字符串</td><td>支付交易的唯一标识符。</td></tr><tr><td>params.orderId</td><td>字符串</td><td>Codashop 生成的订单 ID。</td></tr></tbody></table>

## 充值请求响应

Codashop 的充值请求响应用于描述发行商对一次充值请求的响应情况。

以下是[有效](#you-xiao-de-chong-zhi-jiao-yi-xiang-ying)和[无效](#wu-xiao-chong-zhi-jiao-yi-xiang-ying-shuo-ming)充值响应的示例说明。

***

### 有效的充值交易响应

**格式**：JSON-RPC

```javascript
{
  "id": "6164699909785264260",
  "jsonrpc": "2.0",
  "result": 0
```

| 参数名称    | 描述                        |
| ------- | ------------------------- |
| id      | 与该响应关联的消息 ID。             |
| jsonrpc | 固定为 "2.0"，符合 json-rpc 标准。 |
| result  | 一个对象，表示操作成功。              |

### 无效充值交易响应说明

该响应表示充值<mark style="color:red;">失败</mark>的情况。

虽然验证过程中的失败是预期内的，但在此方法中返回失败通常属于**异常事件**，因为在调用充值接口前，所有参数应已通过验证。

#### 示例

**格式**：JSON-RPC

```javascript
{
  "id": "6164699909785264260",
  "jsonrpc": "2.0",
  "error": {
    "code": -103,
    "message": "Server is under maintenance"
  }
}
```

| 参数名称          | 描述                        |
| ------------- | ------------------------- |
| id            | 与该响应关联的消息 ID。             |
| jsonrpc       | 固定为 "2.0"，符合 JSON-RPC 标准。 |
| error.code    | 表示错误原因的代码。                |
| error.message | 描述错误情况的消息。                |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.coda.co/https-coda-payments.gitbook.io-zhong-wen-coda-private-technical-documentation/codashop-yu-distrubution/ji-cheng-zhi-nan/topup-api-qing-qiu/topup-api-qing-qiu-shi-li-yu-xiang-ying.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.