> 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/codapay/hou-duan-api-ji-cheng/direct-card-api-ji-cheng/huo-qu-kou-kuan-shu-ju.md).

# 获取扣款数据

## **前置条件**

在接入 Codapay 的 API 时，请确保遵循以下规范：

* 使用 HTTPS 协议
* 使用 TLS 1.2 或更高版本

## **参考信息**

<table><thead><tr><th width="250.06329345703125">环境</th><th>接口基本网址</th></tr></thead><tbody><tr><td>沙盒环境</td><td><a href="https://tc-api-card-sandbox.codapayments.com/v1/">https://tc-api-card-sandbox.codapayments.com/v1/</a></td></tr><tr><td>正式环境</td><td><a href="https://api-tc.codapayments.com/v1/">https://api-tc.codapayments.com/v1/</a></td></tr></tbody></table>

#### **接口：**

<mark style="color:green;">**GET**</mark>**&#x20;{基本网址}/direct/charges/{charge\_id}**

#### **当前环境可用性：**

| 环境   | 是否可用 |
| ---- | ---- |
| 沙盒环境 | 是    |
| 正式环境 | 是    |

> Codapay 的 API 支持 REST 网页服务。默认情况下，显示的端点均为 RESTful 格式。

## **请求参数说明**

| 参数名称       | 数据类型   | 描述       | 限制条件             | 必填 (?) |
| ---------- | ------ | -------- | ---------------- | ------ |
| charge\_id | String | 扣款的唯一标识符 | 必须为有效的 charge ID | 是      |

## **响应参数说明**

响应返回的是 **charge 对象**，包含扣款详情。

<table><thead><tr><th width="192.74566650390625">参数名称</th><th width="125.0772705078125">数据类型</th><th>描述</th></tr></thead><tbody><tr><td>id</td><td>String</td><td>Coda 为该笔扣款生成的唯一标识符</td></tr><tr><td>created_at</td><td>String</td><td>扣款创建时间戳</td></tr><tr><td>status_code</td><td>String</td><td>扣款状态，详见 <a data-mention href="/pages/k8NV4oKrszJRAQq4wSrY">/pages/k8NV4oKrszJRAQq4wSrY</a></td></tr><tr><td>error_code</td><td>String</td><td>扣款失败的错误码，详见 <a data-mention href="/pages/aXsbN2QLD1XPWPcxDIW8">/pages/aXsbN2QLD1XPWPcxDIW8</a></td></tr><tr><td>error_description</td><td>String</td><td>扣款失败的错误描述，详见 <a data-mention href="/pages/aXsbN2QLD1XPWPcxDIW8">/pages/aXsbN2QLD1XPWPcxDIW8</a></td></tr><tr><td>finalized_at</td><td>String</td><td>扣款完成时间戳</td></tr><tr><td>item_code</td><td>String</td><td>商品代码</td></tr><tr><td>item_name</td><td>String</td><td>商品名称</td></tr><tr><td>amount_value</td><td>String</td><td>扣款金额总值</td></tr><tr><td>amount_currency</td><td>String</td><td>扣款币种</td></tr><tr><td>partner_reference</td><td>String</td><td>商户自定义的扣款唯一标识符</td></tr><tr><td>shopper_agent</td><td>JSON 对象</td><td>包含用户浏览器详情的对象</td></tr><tr><td>setting</td><td>JSON 对象</td><td>包含设置信息的对象（例如：partner_webhook_url）</td></tr><tr><td>payment_method</td><td>JSON 对象</td><td>包含支付方式详情的对象</td></tr><tr><td>shopper_action</td><td>JSON 对象</td><td>包含用户下一步操作的对象（如需 3DS 验证时返回）</td></tr></tbody></table>

**shopper\_agent**

| 参数名称           | 数据类型   | 描述                |
| -------------- | ------ | ----------------- |
| ip\_address    | String | 用户的 IP 地址         |
| user\_agent    | String | 用户的浏览器 User-Agent |
| timezone       | String | 用户的时区             |
| screen\_height | String | 用户设备的屏幕高度         |
| screen\_width  | String | 用户设备的屏幕宽度         |
| colour\_depth  | String | 用户设备的颜色深度         |
| accept\_header | String | 用户发送的 Accept 请求头  |

**setting**

<table><thead><tr><th width="203.9505615234375">参数名称</th><th width="111.9600830078125">数据类型</th><th>描述</th></tr></thead><tbody><tr><td>default_language</td><td>String</td><td>首选语言</td></tr><tr><td>partner_webhook_url</td><td>String</td><td>用于接收扣款通知（授权与扣款）的 URL</td></tr><tr><td>card</td><td>JSON 对象</td><td>包含卡片设置详情的对象（例如 3DS 验证、扣款确认等）</td></tr></tbody></table>

**setting → card**

<table><thead><tr><th width="251.09552001953125">参数名称</th><th width="125.5277099609375">数据类型</th><th>描述</th></tr></thead><tbody><tr><td>pre_capture_ack_url</td><td>String</td><td>用于发送扣款确认请求的 URL</td></tr><tr><td>capture_grace_period</td><td>Integer</td><td>扣款请求的延迟时间（秒），默认值为 0</td></tr><tr><td>3ds_challenge_window_size</td><td>String</td><td>3D Secure 验证挑战窗口的尺寸</td></tr></tbody></table>

**payment\_method**

| 参数名称        | 数据类型    | 描述         |
| ----------- | ------- | ---------- |
| id          | String  | 支付方式的 ID   |
| created\_at | String  | 支付方式创建的时间戳 |
| type        | String  | 支付方式类型     |
| card        | JSON 对象 | 卡片详细信息     |
| shopper     | JSON 对象 | 包含用户信息的对象  |

**payment\_method → shopper**

| 参数名称         | 数据类型    | 描述        |
| ------------ | ------- | --------- |
| id           | String  | 用户的唯一标识符  |
| created\_at  | String  | 用户创建的时间戳  |
| status\_code | JSON 对象 | 用户的状态     |
| email        | String  | 用户的电子邮件地址 |
| zip\_code    | String  | 用户的邮政编码   |

**payment\_method → card**&#x20;

<table><thead><tr><th width="217.353271484375">参数名称</th><th width="130.9400634765625">数据类型</th><th>描述</th></tr></thead><tbody><tr><td>id</td><td>String</td><td>卡片的唯一标识符</td></tr><tr><td>created_at</td><td>String</td><td>卡片创建的时间戳</td></tr><tr><td>country_code</td><td>String</td><td>必须为有效的 ISO 3166-1 alpha-2 国家代码</td></tr><tr><td>holder_name</td><td>String</td><td>持卡人姓名</td></tr><tr><td>last_four</td><td>String</td><td>卡号的最后 4 位数字</td></tr><tr><td>expiration_month</td><td>String</td><td>卡片的到期月份</td></tr><tr><td>expiration_year</td><td>String</td><td>卡片的到期年份</td></tr></tbody></table>

**shopper\_action**

| 参数名称 | 数据类型    | 描述                    |
| ---- | ------- | --------------------- |
| id   | String  | shopper action 的唯一标识符 |
| type | String  | 用户需执行的操作类型            |
| form | JSON 对象 | 包含表单详情的对象             |

**shopper\_action → form**&#x20;

| 参数名称   | 数据类型          | 描述            |
| ------ | ------------- | ------------- |
| id     | String        | 表单的唯一标识符      |
| method | String        | 提交所需的 HTTP 方法 |
| action | String        | 商户需要提交的 URL   |
| inputs | List of Input | 表单所需填写的字段详情   |

**shopper\_action → form → inputs → item**&#x20;

| 参数名称  | 数据类型   | 描述      |
| ----- | ------ | ------- |
| name  | String | 表单字段的名称 |
| value | String | 字段的值    |
| type  | String | 字段的类型   |


---

# 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/codapay/hou-duan-api-ji-cheng/direct-card-api-ji-cheng/huo-qu-kou-kuan-shu-ju.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.