> 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/ti-jiao-kou-kuan-qing-qiu.md).

# 提交扣款请求

## 前置条件

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

* 使用 HTTPS 协议
* 使用 TLS 1.2 或更高版本
* 在请求中包含 Authorization 标头、API Key 和 Partner ID

## 参考信息

<table><thead><tr><th width="130.57989501953125">环境</th><th>端点基础 URL</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;">**POST**</mark>**&#x20;{基础 URL}/direct/charges**

#### 当前环境可用性

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

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

### 请求参数说明

<table><thead><tr><th>参数名称</th><th width="102.91497802734375">数据类型</th><th>描述</th><th>限制条件</th><th>必填 (?)</th></tr></thead><tbody><tr><td>item_code</td><td>String</td><td>扣款商品的代码</td><td>无</td><td>否</td></tr><tr><td>item_name</td><td>String</td><td>扣款商品的名称</td><td>无</td><td>否</td></tr><tr><td>amount_value</td><td>String</td><td>扣款金额值</td><td>必须为最小货币单位（如分、单位等）</td><td>是</td></tr><tr><td>amount_currency</td><td>String</td><td>扣款币种</td><td>必须为有效的 ISO-4217 货币代码，且为指定国家币种</td><td>是</td></tr><tr><td>partner_reference</td><td>String</td><td>商户提供的唯一扣款标识符</td><td>无</td><td>是</td></tr><tr><td>shopper_agent</td><td>JSON 对象</td><td>包含用户环境信息的 Shopper Agent 客户端对象</td><td>必须为合法的 JSON 格式</td><td>是</td></tr><tr><td>setting</td><td>JSON 对象</td><td>包含默认语言、webhook_url 等设置详情的对象</td><td>必须为合法的 JSON 格式</td><td>是</td></tr><tr><td>payment_method</td><td>JSON 对象</td><td>支付方式对象</td><td>必须为合法的 JSON 格式</td><td>是</td></tr><tr><td>partner_custom_data</td><td>JSON 对象</td><td>商户自定义数据，作为扣款对象的一部分存储并返回</td><td>必须为合法的 JSON 格式</td><td>否</td></tr><tr><td>tax</td><td>JSON 对象</td><td>包含本次支付请求税务信息的对象</td><td>必须为合法的 JSON 格式</td><td>是</td></tr></tbody></table>

以下是更多 JSON 对象的详细说明：

#### **shopper\_agent**

<table><thead><tr><th>参数名称</th><th width="107.21612548828125">数据类型</th><th>描述</th><th>限制条件</th><th>必填 (?)</th></tr></thead><tbody><tr><td>ip_address</td><td>String</td><td>用户的 IP 地址</td><td>必须为 IPV4 格式</td><td>是</td></tr><tr><td>user_agent</td><td>String</td><td>浏览器的 User-Agent 字符串</td><td>必须为有效的 User-Agent 格式</td><td>是</td></tr><tr><td>timezone</td><td>String</td><td>时区偏移，单位为分钟</td><td>必须为数字</td><td>是</td></tr><tr><td>screen_height</td><td>Integer</td><td>用户设备的屏幕高度</td><td>必须为数字</td><td>是</td></tr><tr><td>screen_width</td><td>Integer</td><td>用户设备的屏幕宽度</td><td>必须为数字</td><td>是</td></tr><tr><td>color_depth</td><td>Integer</td><td>用户设备的颜色深度</td><td>必须为数字</td><td>是</td></tr><tr><td>accept_header</td><td>String</td><td>用户发送的 Accept 请求头</td><td>必须为有效的 header 格式（如 text/html）</td><td>是</td></tr><tr><td>fraud_metadata</td><td>JSON 对象</td><td>通过 Coda Fraud Javascript 生成的反欺诈数据</td><td>必须为合法的 JSON 格式</td><td>否</td></tr></tbody></table>

#### shopper\_agent → fraud\_metadata&#x20;

<table><thead><tr><th width="117.43487548828125">参数名称</th><th width="105.6927490234375">数据类型</th><th>描述</th><th>限制条件</th><th>必填 (?)</th></tr></thead><tbody><tr><td>fraud_token</td><td>String</td><td>由 Coda Fraud JS 生成的反欺诈令牌 (Token)</td><td>字符串，最大长度为 128 字符</td><td>否</td></tr></tbody></table>

#### setting&#x20;

<table><thead><tr><th width="159.76214599609375">参数名称</th><th width="114.7943115234375">数据类型</th><th>描述</th><th>限制条件</th><th>必填 (?)</th></tr></thead><tbody><tr><td>default_language</td><td>String</td><td>默认语言设置</td><td>必须为两个字符的语言代码</td><td>是</td></tr><tr><td>partner_return_url</td><td>String</td><td>用户成功认证后重定向的 URL（商户回跳页面）</td><td>必须为有效的 URL</td><td>否</td></tr><tr><td>partner_webhook_url</td><td>String</td><td>用于接收扣款通知（授权与扣款）的 URL</td><td>必须为有效的 URL</td><td>是</td></tr><tr><td>card</td><td>JSON 对象</td><td>包含卡支付设置详情的对象（如 3DS、扣款确认等）</td><td>必须为合法的 JSON 格式</td><td>是</td></tr></tbody></table>

#### setting → card&#x20;

<table><thead><tr><th width="177.18145751953125">参数名称</th><th width="105.3984375">数据类型</th><th>描述</th><th width="157.7691650390625">限制条件</th><th>必填 (?)</th></tr></thead><tbody><tr><td>pre_capture_ack_url</td><td>String</td><td>用于预扣款确认的 URL</td><td>必须为有效的 URL</td><td>否</td></tr><tr><td>capture_grace_period</td><td>Integer</td><td>发起扣款请求的延迟时间（秒）。默认值为 0</td><td>必须为数字</td><td>否</td></tr><tr><td>3ds_challenge_window_size</td><td>String</td><td>3DS 验证挑战窗口的尺寸</td><td>格式必须为 "WIDTHxHEIGHT"</td><td>是</td></tr></tbody></table>

#### payment\_method

<table><thead><tr><th width="107.185791015625">参数名称</th><th width="112.17010498046875">数据类型</th><th>描述</th><th>限制条件</th><th>必填 (?)</th></tr></thead><tbody><tr><td>type</td><td>String</td><td>支付方式类型</td><td>必须为 <code>card</code></td><td>是</td></tr><tr><td>card</td><td>JSON 对象</td><td>卡片详细信息</td><td>必须为合法的 JSON 格式</td><td>是</td></tr><tr><td>shopper</td><td>JSON 对象</td><td>表示用户个人信息的 JSON 对象</td><td>必须为合法的 JSON 格式</td><td>是</td></tr></tbody></table>

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

<table><thead><tr><th width="155.545166015625">参数名称</th><th width="105.87322998046875">数据类型</th><th>描述</th><th>限制条件</th><th>必填 (?)</th></tr></thead><tbody><tr><td>country_code</td><td>String</td><td>国家代码<br><strong>备注：当前不支持美国，加拿大，台湾和印度的卡支付</strong></td><td>必须为有效的 ISO 3166-1 alpha-2 国家代码</td><td>是</td></tr><tr><td>number</td><td>String</td><td>卡号</td><td>长度必须在 15 至 19 位之间</td><td>是</td></tr><tr><td>holder_name</td><td>String</td><td>持卡人姓名</td><td>必须为完整姓名</td><td>是</td></tr><tr><td>expiration_month</td><td>String</td><td>卡片到期月份</td><td>必须为 1–12 之间的数字</td><td>是</td></tr><tr><td>expiration_year</td><td>String</td><td>卡片到期年份</td><td>必须为 00–99 之间的数字</td><td>是</td></tr><tr><td>security_code</td><td>String</td><td>卡片的 CSC/CVV/CVC 安全码</td><td>必须为 3 或 4 位数字</td><td>是</td></tr></tbody></table>

#### payment\_method → shopper&#x20;

<table><thead><tr><th width="156.81683349609375">参数名称</th><th width="105.39410400390625">数据类型</th><th>描述</th><th>限制条件</th><th>必填 (?)</th></tr></thead><tbody><tr><td>partner_shopper_id</td><td>String</td><td>商户自定义的用户 ID</td><td>必须为有效字符串</td><td>否</td></tr><tr><td>email</td><td>String</td><td>用户的电子邮件地址</td><td>必须为有效的邮箱格式</td><td>是</td></tr><tr><td>zip_code</td><td>String</td><td>用户的邮政编码</td><td>必须为有效邮政编码格式</td><td>条件必填（当 country_code 为 US 或 CA 时）</td></tr><tr><td>phone_number</td><td>String</td><td>用户的手机号码</td><td>必须为有效的手机号格式</td><td>否</td></tr><tr><td>billing_first_name</td><td>String</td><td>用户账单地址中的名字</td><td>必须为有效姓名</td><td>否</td></tr><tr><td>billing_last_name</td><td>String</td><td>用户账单地址中的姓氏</td><td>必须为有效姓名</td><td>否</td></tr><tr><td>billing_document_type</td><td>String</td><td>用户的证件类型（如 Passport, CPF 等）</td><td>必须为有效的证件类型格式</td><td>否</td></tr><tr><td>billing_document_id</td><td>String</td><td>用户的证件号码</td><td>必须为有效的证件编号格式</td><td>否</td></tr><tr><td>billing_country</td><td>String</td><td>用户账单地址所在国家</td><td>必须为有效的国家格式</td><td>否</td></tr><tr><td>billing_address</td><td>String</td><td>用户账单地址</td><td>必须为有效的地址格式</td><td>否</td></tr><tr><td>billing_region</td><td>String</td><td>用户账单所在地区</td><td>必须为有效的地区格式</td><td>否</td></tr><tr><td>billing_city</td><td>String</td><td>用户账单所在城市</td><td>必须为有效的城市格式</td><td>否</td></tr></tbody></table>

#### partner\_custom\_data&#x20;

<table><thead><tr><th width="173.3446044921875">参数名称</th><th width="105.4913330078125">数据类型</th><th>描述</th><th>限制条件</th><th>必填 (?)</th></tr></thead><tbody><tr><td>dynamic_descriptor</td><td>String</td><td>显示在最终用户卡账单中的交易描述信息</td><td>最多 22 个字符</td><td>否</td></tr></tbody></table>

#### tax&#x20;

<table><thead><tr><th width="107.1397705078125">参数名称</th><th width="105.775146484375">数据类型</th><th width="115.3697509765625">描述</th><th>限制条件</th><th>必填 (?)</th></tr></thead><tbody><tr><td>tax_code</td><td>String</td><td>商品的税码</td><td>当前支持的税码：CD010001 - 数字商品：游戏/影音串流 或 电子下载</td><td>是</td></tr></tbody></table>

### 响应参数说明

返回的对象为 **charge 对象**，包含您发起的扣款请求的完整记录，以及在整个支付流程中的扣款状态等追踪信息。

<table><thead><tr><th width="196.9296875">参数名称</th><th width="128.85498046875">数据类型</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>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>partner_custom_data</td><td>键值对</td><td>商户提供的自定义数据，会存储并作为 charge 对象的一部分返回</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>

以下是更多 JSON 对象的详细说明：

#### **shopper\_agent**

| 参数名称           | 数据类型    | 描述                  |
| -------------- | ------- | ------------------- |
| ip\_address    | String  | 用户的 IP 地址           |
| user\_agent    | String  | 浏览器的 User-Agent 字符串 |
| timezone       | String  | 时区偏移（单位：分钟）         |
| screen\_height | Integer | 用户设备的屏幕高度           |
| screen\_width  | Integer | 用户设备的屏幕宽度           |
| color\_depth   | Integer | 用户设备的颜色深度           |
| accept\_header | String  | 用户发送的 Accept 请求头    |

**setting**

<table><thead><tr><th width="233.07208251953125">参数名称</th><th width="133.6136474609375">数据类型</th><th>描述</th></tr></thead><tbody><tr><td>default_language</td><td>String</td><td>默认语言设置</td></tr><tr><td>partner_return_url</td><td>String</td><td>用户完成 3DS 验证后跳转回商户页面的 URL</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="259.67364501953125">参数名称</th><th width="123.375">数据类型</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>3DS 验证挑战窗口的尺寸（格式为 <code>WIDTHxHEIGHT</code>）</td></tr></tbody></table>

**payment\_method**

| 参数名称    | 数据类型    | 描述       |
| ------- | ------- | -------- |
| card    | JSON 对象 | 卡片详细信息对象 |
| shopper | JSON 对象 | 用户个人信息对象 |

#### payment\_method → shopper

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

#### payment\_method → card

<table><thead><tr><th width="232.779541015625">参数名称</th><th width="145.7578125">数据类型</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 国家代码<br><strong>备注：当前不支持美国，加拿大，台湾和印度的卡支付</strong></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**

<table><thead><tr><th width="119.1068115234375">参数名称</th><th width="130.83154296875">数据类型</th><th>描述</th></tr></thead><tbody><tr><td>id</td><td>String</td><td>shopper action 的唯一标识符</td></tr><tr><td>type</td><td>String</td><td>始终为 <code>"form"</code>，表示用户需填写 3DS 表单。关于 3DS 表单详见 <a data-mention href="/pages/vI9z3zggo3TT2lMVo6r9">/pages/vI9z3zggo3TT2lMVo6r9</a></td></tr><tr><td>form</td><td>JSON 对象</td><td>包含表单详情的对象，用于构建 HTML 表单</td></tr></tbody></table>

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

<table><thead><tr><th width="132.83245849609375">参数名称</th><th width="112.1041259765625">数据类型</th><th>描述</th></tr></thead><tbody><tr><td>id</td><td>String</td><td>表单的唯一标识符</td></tr><tr><td>method</td><td>String</td><td>提交该表单所使用的 HTTP 方法</td></tr><tr><td>action</td><td>String</td><td>用户完成支付操作后将跳转的 URL</td></tr><tr><td>inputs</td><td>List</td><td>表单所需的输入字段列表</td></tr></tbody></table>

***

**shopper\_action → form → inputs item**

<table><thead><tr><th width="208.65447998046875">参数名称</th><th width="166.7603759765625">数据类型</th><th>描述</th></tr></thead><tbody><tr><td>name</td><td>String</td><td>HTML 表单中 input 的 name 属性值</td></tr><tr><td>value</td><td>String</td><td>HTML 表单中 input 的 value 属性值</td></tr><tr><td>type</td><td>String</td><td>HTML 表单中 input 的 type 属性值</td></tr></tbody></table>


---

# 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/ti-jiao-kou-kuan-qing-qiu.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.