交易

接口地址

测试环境基础地址

https://api.futurepay-develop.com/api/v1/issuing/transaction

生产环境基础地址

https://api.futurepay.global/api/v1/issuing/transaction

接口目录

功能请求方式接口路径请求体
查询交易详情POST/{id}/detail{}
查询交易分页列表POST/paging分页及筛选参数,或 {}

通用响应

字段类型说明
codestring成功为0,失败返回错误码
msgstring结果说明
serverTimestring服务端毫秒时间戳
successboolean是否成功
dataobject业务数据

查询交易详情

接口

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"
  }
}

响应字段

字段类型说明
idstring交易ID
authorizationIdstring关联授权ID
originalTransactionIdstring关联原交易ID
cardIdstring卡片ID
cardholderIdstring持卡人ID
cardLast4string卡号末四位
amountstring结算金额
currencystring结算币种,固定USD
merchantAmountstring原始消费金额
merchantCurrencystring消费币种
statusstring交易状态,见状态表
merchantDataobject消费商家信息
createdAtstring交易记录创建时间
updatedAtstring更新时间

交易状态

status中文说明
CAPTURE消费结算
REFUND退款
REFUND_REVERSAL退款撤销

查询交易分页列表

接口

POST /paging

请求参数

参数类型必填说明
idstring否交易ID,最多128字符
cardIdstring否卡片ID,最多128字符
cardholderIdstring否持卡人ID,最多128字符
keywordstring否关键词,最多256字符
startDatestring否开始时间,yyyy-MM-dd HH:mm:ss
endDatestring否结束时间,yyyy-MM-dd HH:mm:ss,不早于startDate
pageNuminteger否页码,默认1,最小1
pageSizeinteger否每页条数,默认20,范围1–100
statusstring否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.pageNumstring当前页码
data.pageSizestring每页条数
data.totalstring总条数
data.totalPagestring总页数
data.listarray记录列表

消费商家字段说明

字段类型说明
merchantData.networkIdstring商家网络编号
merchantData.namestring商家名称
merchantData.categoryCodestring商家行业代码(MCC)
merchantData.categorystring商家行业类别
merchantData.countrystring国家或地区代码
merchantData.citystring城市
merchantData.statestring州或省
merchantData.postalCodestring邮政编码

交易结果通知

通知类型: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
}

Did this page help you?