卡片管理接口
获取卡片配置
URL: GET /card/get_config
Query: 无
输出:
| 字段 | 类型 | 说明 |
|---|---|---|
| prepaid_initial_card_count | number | 储值卡初始可开卡数 |
| credit_initial_card_count | number | 额度卡初始可开卡数 |
| staff_initial_card_count | number | 员工卡初始可开卡数 |
更新卡片配置
URL: POST /card/update_config
输入:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| prepaid_initial_card_count | number | 是 | 储值卡初始可开卡数 |
| credit_initial_card_count | number | 是 | 额度卡初始可开卡数 |
| staff_initial_card_count | number | 是 | 员工卡初始可开卡数 |
输出: 无
获取卡段列表
URL: GET /card_segment/list
Query:
| 字段 | 必填 | 说明 |
|---|---|---|
| page | 否 | 页码，从1开始 |
| size | 否 | 每页大小 |
| search | 否 | 搜索关键词 |
| brand | 否 | 品牌, VISA |
| status | 否 | 状态, NORMAL正常, SUSPENDED已停用 |
输出: list<CardSegment>
CardSegment
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 卡段id |
| segment | string | 卡段 |
| card_types | list<string> | 支持的卡片类型, ['PREPAID', 'CREDIT', 'STAFF'] |
| currencies | list<string> | 支持货币列表, ['USD', 'HKD'] |
| brand | string | 品牌, VISA |
| fee | number | 办卡手续费, 单位元 |
| is_recommended | bool | 是否推荐 |
| is_avs_supported | bool | 是否支持avs |
| is_apple_pay_supported | bool | 是否支持apple pay |
| is_google_wallet_supported | bool | 是否支持google pay |
| purpose | list<string> | 使用场景, TIKTOK, FACEBOOK, GOOGLE |
| status | string | 状态, NORMAL正常, SUSPENDED已停用 |
| airwallex_client_id | string | Airwallex Client ID |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |
新增卡段
URL: POST /card_segment/create
输入:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| segment | string | 是 | 卡段 |
| card_types | list<string> | 是 | 支持的卡片类型, ['PREPAID', 'CREDIT', 'STAFF'] |
| currencies | list<string> | 是 | 支持货币列表, ['USD', 'HKD'] |
| brand | string | 是 | 品牌, VISA |
| fee | number | 是 | 办卡手续费, 所有金额都是整数且精确到分，如100，表示1元 |
| is_recommended | bool | 是 | 是否推荐 |
| is_avs_supported | bool | 是 | 是否支持avs |
| is_apple_pay_supported | bool | 是 | 是否支持apple pay |
| is_google_wallet_supported | bool | 是 | 是否支持google pay |
| purpose | list<string> | 是 | 使用场景, TIKTOK, FACEBOOK, GOOGLE |
| status | string | 是 | 状态, NORMAL正常, SUSPENDED已停用 |
| airwallex_client_id | string | 是 | Airwallex Client ID |
| airwallex_api_key | string | 是 | Airwallex API KEY |
输出:
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | id |
更新卡段
URL: POST /card_segment/{card_segment_id}/update
输入:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| segment | string | 是 | 卡段 |
| card_types | list<string> | 是 | 支持的卡片类型, ['PREPAID', 'CREDIT', 'STAFF'] |
| currencies | list<string> | 是 | 支持货币列表, ['USD', 'HKD'] |
| brand | string | 是 | 品牌, VISA |
| fee | number | 是 | 办卡手续费, 所有金额都是整数且精确到分，如100，表示1元 |
| is_recommended | bool | 是 | 是否推荐 |
| is_avs_supported | bool | 是 | 是否支持avs |
| is_apple_pay_supported | bool | 是 | 是否支持apple pay |
| is_google_wallet_supported | bool | 是 | 是否支持google pay |
| purpose | list<string> | 是 | 使用场景, TIKTOK, FACEBOOK, GOOGLE |
| status | string | 是 | 状态, NORMAL正常, SUSPENDED已停用 |
| airwallex_client_id | string | 是 | Airwallex Client ID |
| airwallex_api_key | string | 是 | Airwallex API KEY |
输出: 无
获取持卡人列表
URL: GET /cardholder/list?page=1
Query:
| 字段 | 必填 | 说明 |
|---|---|---|
| page | 否 | 页码，从1开始 |
| size | 否 | 每页大小 |
| search | 否 | 搜索关键词 |
| segment_id | 否 | 卡段id |
输出:
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 持卡人id |
| user_id | string | 用户id |
| username | string | 用户名 |
| company_name | string | 公司名称 |
| person_name | string | 个人名称 |
| string | 邮箱 | |
| area_code | string | 手机区号 |
| mobile | string | 手机号 |
| first_name | string | 名 |
| last_name | string | 姓 |
| date_of_birth | string | 出生日期, 格式1990-01-01 |
| country | string | 两位国家代码，如CN, US, AU |
| state | string | 州/省，有些国家，如US，AU不填会报错 |
| city | string | 城市 |
| address_line1 | string | 详细地址1 |
| postcode | string | 邮编 |
| remark | string | 备注 |
| created_at | string | 创建时间, 格式2025-04-26T06:46:20+0000, 需要格式化成本地时间 |
创建持卡人
URL: POST /cardholder/create
输入:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| user_id | string | 是 | 用户id |
| string | 是 | 邮箱 | |
| area_code | string | 是 | 手机区号 |
| mobile | string | 是 | 手机号 |
| first_name | string | 是 | 名 |
| last_name | string | 是 | 姓 |
| date_of_birth | string | 是 | 出生日期, 格式1990-01-01 |
| country | string | 是 | 两位国家代码，如CN, US, AU |
| state | string | 否 | 州/省，有些国家，如US，AU不填会报错 |
| city | string | 是 | 城市 |
| address_line1 | string | 是 | 详细地址1 |
| postcode | string | 是 | 邮编 |
| remark | string | 否 | 备注 |
| segment_id | string | 是 | 卡段id |
输出:
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 持卡人id |
更新持卡人
注意: 用户id和邮箱不能更新
URL: POST /cardholder/{cardholder_id}/update
输入:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| area_code | string | 是 | 手机区号 |
| mobile | string | 是 | 手机号 |
| first_name | string | 是 | 名 |
| last_name | string | 是 | 姓 |
| date_of_birth | string | 是 | 出生日期, 格式1990-01-01 |
| country | string | 是 | 两位国家代码，如CN, US, AU |
| state | string | 否 | 州/省，有些国家，如US，AU不填会报错 |
| city | string | 是 | 城市 |
| address_line1 | string | 是 | 详细地址1 |
| postcode | string | 是 | 邮编 |
| remark | string | 否 | 备注 |
输出: 无
获取卡片列表
URL: GET /card/list?page=1
Query:
| 字段 | 必填 | 说明 |
|---|---|---|
| page | 否 | 页码，从1开始 |
| size | 否 | 每页大小 |
| search | 否 | 搜索关键词 |
| status | 否 | 状态, NOPENDING未处理, PENDING待处理, ACTIVE已激活, INACTIVE已失效, BLOCKED已锁定, LOST已丢失, STOLEN已被盗, CLOSED已关闭, FAILED创建失败, EXPIRED已过期 |
| brand | 否 | 品牌, VISA, |
| card_type | 否 | 卡片类型, PREPAID储值卡, CREDIT额度卡, STAFF员工卡 |
| user_id | 否 | 用户ID |
输出: list<Card>
Card
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 卡id |
| user_id | string | 用户id |
| username | string | 用户名 |
| company_name | string | 公司名称 |
| person_name | string | 个人名称 |
| card_type | string | 卡片类型, PREPAID储值卡, CREDIT额度卡, STAFF员工卡 |
| cardholder_id | string | 持卡人ID |
| cardholder | CardHolder | 持卡人 |
| segment_id | string | 卡段ID |
| segment | CardSegment | 卡段 |
| card_number | string | 卡号 |
| name_on_card | string | 卡名 |
| brand | string | 品牌，如VISA |
| expiry_year | string | 过期年份 |
| expiry_month | string | 过期月份 |
| cvv | string | cvv |
| balance | number | 余额, 单位元 |
| total_consume | number | 累计消费, 单位元 |
| total_recharge | number | 累计充值, 单位元 |
| total_transfer_out | number | 累计转出, 单位元 |
| actual_recharge | number | 实际充值, 单位元 |
| total_refund | number | 累计退款, 单位元 |
| currency | string | 币种, 如USD |
| tag | string | 标签 |
| purpose | list<string> | 使用场景, TIKTOK, FACEBOOK, GOOGLE |
| status | string | 状态, NOPENDING未处理, PENDING待处理, ACTIVE已激活, INACTIVE已失效, BLOCKED已锁定, LOST已丢失, STOLEN已被盗, CLOSED已关闭, FAILED创建失败, EXPIRED已过期 |
| budget_id | string | 预算ID |
| limit_type | string | 额度类型, UNLIMITED无限制, CYCLE循环额度, ACCUMULATE累计额度 |
| cycle_limit_type | string | 循环额度类型, DAILY每日, WEEKLY每周, MONTHLY每月 |
| limit_amount | string | 额度金额, 单位元 |
新增卡片
URL: POST /card/create
输入:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| card_type | string | 是 | 卡片类型, PREPAID储值卡, CREDIT额度卡, STAFF员工卡 |
| user_id | string | 是 | 用户id |
| segment_id | string | 是 | 卡段ID |
| cardholder_id | string | 是 | 持卡人ID |
| currency | string | 是 | 币种 |
| recharge_amount | number | 是 | 充值金额， 所有金额都是整数且精确到分，如1850，表示18.5元 |
| tag | string | 否 | 标签 |
| purpose | list<string> | 是 | 使用场景, TIKTOK, FACEBOOK, GOOGLE |
| budget_id | string | 否 | 额度预算ID, 类型是额度卡时必填 |
| employee_id | string | 否 | 员工ID, 类型是员工卡是必填 |
| staff_budget_id | string | 否 | 员工预算ID, 类型是员工卡是必填 |
输出:
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 卡id |
更新卡片
URL: POST /card/{card_id}/update
输入:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| status | string | 是 | 状态, ACTIVE已激活, INACTIVE已失效, BLOCKED已锁定, LOST已丢失, STOLEN已被盗 |
| tag | string | 否 | 标签 |
输出: 无
卡片充值
注意: 当前仅支持从钱包充值
URL: POST /card/{card_id}/recharge
输入:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| amount | number | 是 | 充值金额， 所有金额都是整数且精确到分，如1850，表示18.5元 |
输出:
| 字段 | 类型 | 说明 |
|---|---|---|
| card_balance | number | 卡片新余额, 单位元 |
| wallet_balance | number | 钱包新余额, 单位元 |
卡片转出
注意: 当前仅支持转出到钱包
URL: POST /card/{card_id}/transfer_out
输入:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| amount | number | 是 | 充值金额， 所有金额都是整数且精确到分，如1850，表示18.5元 |
输出:
| 字段 | 类型 | 说明 |
|---|---|---|
| card_balance | number | 卡片新余额, 单位元 |
| wallet_balance | number | 钱包新余额, 单位元 |
修改卡片额度
只有额度卡和员工卡可以修改额度
URL: POST /card/{card_id}/change_limit
输入:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| limit_type | string | 是 | 额度类型, UNLIMITED无限制, CYCLE循环额度, ACCUMULATE累计额度 |
| cycle_limit_type | string | 否 | 循环额度类型, DAILY每日, WEEKLY每周, MONTHLY每月类型是 CYCLE时必填 |
| limit_amount | string | 否 | 额度金额 所有金额都是整数且精确到分，如1850，表示18.5元 类型不是 UNLIMITED时必填 |
输出: 无
删除卡片
URL: POST /card/{card_id}/delete
输入: 无
输出: 无
获取卡片交易记录列表
URL: GET /card/{card_id}/transaction/list?page=1
Query:
| 字段 | 必填 | 说明 |
|---|---|---|
| page | 否 | 页码，从1开始 |
| size | 否 | 每页大小 |
| search | 否 | 搜索关键词 |
| status | 否 | 交易状态, APPROVED交易成功, CLEARED已结算, EXPIRED已过期, FAILED交易失败, PENDING待确认, REVERSED已撤销 |
| transaction_type | 否 | 交易类型, TRANSFER_IN收入, TRANSFER_OUT转出, CONSUME消费, REFUND退款 |
输出: list<TransactionRecord>
TransactionRecord
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | id |
| posted_date | string | 交易时间 |
| serial_number | string | 流水编号 |
| transaction_type | string | 交易类型, TRANSFER_IN收入, TRANSFER_OUT转出, CONSUME消费, REFUND退款 |
| payer | string | 支出方 |
| receiver | string | 收入方 |
| detail | string | 交易详情 |
| amount | string | 交易金额, 单位元 |
| currency | string | 交易币种 |
| fee | string | 手续费, 单位元 |
| status | string | 交易状态, APPROVED交易成功, CLEARED已结算, EXPIRED已过期, FAILED交易失败, PENDING待确认, REVERSED已撤销 |
| operator | string | 操作人 |