交易
接口地址
测试环境基础地址
https://api.futurepay-develop.com/api/v1/issuing/transaction生产环境基础地址
https://api.futurepay.global/api/v1/issuing/transaction接口目录
| 功能 | 请求方式 | 接口路径 | 请求体 |
|---|---|---|---|
| 查询交易详情 | POST | /{id}/detail | {} |
| 查询交易分页列表 | POST | /paging | 分页及筛选参数,或 {} |
通用响应
| 字段 | 类型 | 说明 |
|---|---|---|
| code | string | 成功为0,失败返回错误码 |
| msg | string | 结果说明 |
| serverTime | string | 服务端毫秒时间戳 |
| success | boolean | 是否成功 |
| data | object | 业务数据 |
查询交易详情
接口
POST /{id}/detail请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| id | 路径 | string | 是 | 交易ID |
请求示例
请求体:
{}响应示例
{
"code": "0",
"msg": "succeeded",
"serverTime": "1794451375285",
"success": true,
"data": {
"id": "TXN_example",
"authorizationId": "AUTH_example",
"originalTransactionId": null,
"cardId": "ic_example",
"cardholderId": "ich_example",
"cardLast4": "4242",
"amount": "100.00",
"currency": "USD",
"merchantAmount": "90.00",
"merchantCurrency": "EUR",
"status": "CAPTURE",
"merchantData": {
"networkId": "merchant_network_example",
"name": "Example Store",
"categoryCode": "0742",
"category": "veterinary_services",
"country": "US",
"city": "San Francisco",
"state": "CA",
"postalCode": "94111"
},
"createdAt": "2026-11-06 11:00:00",
"updatedAt": "2026-11-06 11:00:00"
}
}响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 交易ID |
| authorizationId | string | 关联授权ID |
| originalTransactionId | string | 关联原交易ID |
| cardId | string | 卡片ID |
| cardholderId | string | 持卡人ID |
| cardLast4 | string | 卡号末四位 |
| amount | string | 结算金额 |
| currency | string | 结算币种,固定USD |
| merchantAmount | string | 原始消费金额 |
| merchantCurrency | string | 消费币种 |
| status | string | 交易状态,见状态表 |
| merchantData | object | 消费商家信息 |
| createdAt | string | 交易记录创建时间 |
| updatedAt | string | 更新时间 |
交易状态
| status | 中文说明 |
|---|---|
| CAPTURE | 消费结算 |
| REFUND | 退款 |
| REFUND_REVERSAL | 退款撤销 |
查询交易分页列表
接口
POST /paging请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | string | 否 | 交易ID,最多128字符 |
| cardId | string | 否 | 卡片ID,最多128字符 |
| cardholderId | string | 否 | 持卡人ID,最多128字符 |
| keyword | string | 否 | 关键词,最多256字符 |
| startDate | string | 否 | 开始时间,yyyy-MM-dd HH:mm:ss |
| endDate | string | 否 | 结束时间,yyyy-MM-dd HH:mm:ss,不早于startDate |
| pageNum | integer | 否 | 页码,默认1,最小1 |
| pageSize | integer | 否 | 每页条数,默认20,范围1–100 |
| status | string | 否 | CAPTURE、REFUND、REFUND_REVERSAL |
请求示例
{
"cardholderId": "ich_example",
"status": "CAPTURE",
"startDate": "2026-11-01 00:00:00",
"endDate": "2026-11-12 23:59:59",
"pageNum": 1,
"pageSize": 20
}响应示例
{
"code": "0",
"msg": "succeeded",
"serverTime": "1794451375285",
"success": true,
"data": {
"pageNum": "1",
"pageSize": "20",
"total": "1",
"totalPage": "1",
"list": [
{
"id": "TXN_example",
"authorizationId": "AUTH_example",
"originalTransactionId": null,
"cardId": "ic_example",
"cardholderId": "ich_example",
"cardLast4": "4242",
"amount": "100.00",
"currency": "USD",
"merchantAmount": "90.00",
"merchantCurrency": "EUR",
"status": "CAPTURE",
"merchantData": {
"networkId": "merchant_network_example",
"name": "Example Store",
"categoryCode": "0742",
"category": "veterinary_services",
"country": "US",
"city": "San Francisco",
"state": "CA",
"postalCode": "94111"
},
"createdAt": "2026-11-06 11:00:00",
"updatedAt": "2026-11-06 11:00:00"
}
]
}
}分页响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
| data.pageNum | string | 当前页码 |
| data.pageSize | string | 每页条数 |
| data.total | string | 总条数 |
| data.totalPage | string | 总页数 |
| data.list | array | 记录列表 |
消费商家字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
| merchantData.networkId | string | 商家网络编号 |
| merchantData.name | string | 商家名称 |
| merchantData.categoryCode | string | 商家行业代码(MCC) |
| merchantData.category | string | 商家行业类别 |
| merchantData.country | string | 国家或地区代码 |
| merchantData.city | string | 城市 |
| merchantData.state | string | 州或省 |
| merchantData.postalCode | string | 邮政编码 |
交易结果通知
通知类型:VCC_TRANSACTION_RESULT_NOTIFY。消费结算、退款、退款撤销入账后发送。
通知项的交易字段与交易详情一致,另包含 eventCode、eventDate。使用 status 区分 CAPTURE(消费)、REFUND(退款)、REFUND_REVERSAL(退款撤销),使用 originalTransactionId 关联原交易。
{
"merchantId": "1929723739654762496",
"appId": "1929723739684102144",
"notificationItems": [
{
"eventCode": "VCC_TRANSACTION_RESULT_NOTIFY",
"eventDate": 1794472514726,
"id": "TXN_example",
"authorizationId": "AUTH_example",
"originalTransactionId": null,
"cardId": "ic_example",
"cardholderId": "ich_example",
"cardLast4": "3470",
"amount": "5.00",
"currency": "USD",
"merchantAmount": "5.00",
"merchantCurrency": "USD",
"status": "CAPTURE",
"merchantData": {
"networkId": "merchant_network_example",
"name": "Example Store",
"categoryCode": "5541",
"category": "service_stations",
"country": "US",
"city": "NY",
"state": "NY",
"postalCode": "10001"
},
"createdAt": "2026-11-12 10:09:50",
"updatedAt": "2026-11-12 10:09:50"
}
]
}常见错误码
| 错误码 | 中文说明 |
|---|---|
| 400 | 请求参数错误 |
| API_QUERY_PARAMETER_INVALID | 查询参数错误 |
| TRANSACTION_NOT_FOUND | 交易记录不存在 |
| REQUEST_HEADER_MERCHANT_ID_INVALID | 商户身份无效 |
| VCC_PRODUCT_NOT_ENABLED | 未启用发卡功能 |
错误响应示例
{
"code": "TRANSACTION_NOT_FOUND",
"msg": "Transaction not found",
"serverTime": "1794451375285",
"success": false
}Updated about 11 hours ago
Did this page help you?