提交扣款请求

前置条件

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

• 使用 HTTPS 协议

• 使用 TLS 1.2 或更高版本

• 在请求中包含 Authorization 标头、API Key 和 Partner ID

参考信息

环境	端点基础 URL
沙盒环境	https://tc-api-card-sandbox.codapayments.com/v1/
正式环境	https://api-tc.codapayments.com/v1/

接口

POST {基础 URL}/direct/charges

当前环境可用性

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

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

请求参数说明

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

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

shopper_agent

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

shopper_agent → fraud_metadata

参数名称	数据类型	描述	限制条件	必填 (?)
fraud_token	String	由 Coda Fraud JS 生成的反欺诈令牌 (Token)	字符串，最大长度为 128 字符	否

setting

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

setting → card

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

payment_method

参数名称	数据类型	描述	限制条件	必填 (?)
type	String	支付方式类型	必须为 card	是
card	JSON 对象	卡片详细信息	必须为合法的 JSON 格式	是
shopper	JSON 对象	表示用户个人信息的 JSON 对象	必须为合法的 JSON 格式	是

payment_method → card

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

payment_method → shopper

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

partner_custom_data

参数名称	数据类型	描述	限制条件	必填 (?)
dynamic_descriptor	String	显示在最终用户卡账单中的交易描述信息	最多 22 个字符	否

tax

参数名称	数据类型	描述	限制条件	必填 (?)
tax_code	String	商品的税码	当前支持的税码：CD010001 - 数字商品：游戏/影音串流 或 电子下载	是

响应参数说明

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

参数名称	数据类型	描述
id	String	Coda 为本次扣款生成的唯一标识符
created_at	String	扣款请求的创建时间戳
status_code	String	扣款状态码。可查看 Direct Card API 扣款状态说明
error_code	String	扣款失败时的错误码。可查看 Direct Card API 扣款错误码
error_description	String	扣款失败时的错误描述。可查看 Direct Card API 扣款错误码
item_code	String	扣款商品的代码
item_name	String	扣款商品的名称
amount_value	String	扣款金额
amount_currency	String	扣款币种
partner_reference	String	商户自定义的唯一扣款标识符
partner_custom_data	键值对	商户提供的自定义数据，会存储并作为 charge 对象的一部分返回
shopper_agent	JSON 对象	包含用户浏览器信息的对象
setting	JSON 对象	包含设置信息（例如：partner_webhook_url）的对象
payment_method	JSON 对象	支付方式对象
shopper_action	JSON 对象	包含用户需执行下一步操作的信息的对象：– 若此字段存在，表示用户需完成额外操作（通常为 3DS 验证）– 若不存在，表示用户无需额外操作

以下是更多 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

参数名称	数据类型	描述
default_language	String	默认语言设置
partner_return_url	String	用户完成 3DS 验证后跳转回商户页面的 URL
partner_webhook_url	String	用于接收交易通知（授权与扣款）的 URL
card	JSON 对象	包含卡片设置详情的对象（例如 3DS 验证、扣款确认等）

setting → card

参数名称	数据类型	描述
pre_capture_ack_url	String	用于确认预扣款的 URL
capture_grace_period	Integer	发起扣款请求的延迟时间（秒），默认值为 0
3ds_challenge_window_size	String	3DS 验证挑战窗口的尺寸（格式为 WIDTHxHEIGHT）

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

参数名称	数据类型	描述
id	String	卡片的唯一标识符
created_at	String	卡片创建的时间戳
country_code	String	必须为有效的 ISO 3166-1 alpha-2 国家代码 备注：当前不支持美国，加拿大，台湾和印度的卡支付
holder_name	String	持卡人姓名
last_four	String	卡号的最后 4 位数字
expiration_month	String	卡片的到期月份
expiration_year	String	卡片的到期年份

shopper_action

参数名称	数据类型	描述
id	String	shopper action 的唯一标识符
type	String	始终为 "form"，表示用户需填写 3DS 表单。关于 3DS 表单详见 处理 3DS 验证
form	JSON 对象	包含表单详情的对象，用于构建 HTML 表单

shopper_action → form

参数名称	数据类型	描述
id	String	表单的唯一标识符
method	String	提交该表单所使用的 HTTP 方法
action	String	用户完成支付操作后将跳转的 URL
inputs	List	表单所需的输入字段列表

---

shopper_action → form → inputs item

参数名称	数据类型	描述
name	String	HTML 表单中 input 的 name 属性值
value	String	HTML 表单中 input 的 value 属性值
type	String	HTML 表单中 input 的 type 属性值