跳转到主要内容
GET
Retrieve Card

授权

x-auth-token
string
header
必填

由 UQPay 提供的登录 API Token。

请求头

x-on-behalf-of
string

指定代表哪个子账户发起请求。应设置为 account_id,该值可通过 List Connected Accounts 接口获取。若省略或为空,则请求以主账户身份执行。 更多信息参见 关联账户

路径参数

id
string<uuid>
必填

资源的全局唯一标识符(UUID v4)。

示例:

"71fdb0fe-9682-457a-9361-e8868694f12f"

响应

200 - application/json

成功获取卡片。

card_id
string
必填

卡片的唯一标识符。

示例:

"c0cef051-29c5-4796-b86a-cd5b684bfad7"

card_bin
string
必填

卡号前缀(BIN)。

示例:

"40963608"

card_scheme
string
必填

卡组织。

示例:

"VISA"

card_number
string
必填

脱敏卡号

示例:

"************5668"

form_factor
enum<string>
必填

卡片形态——VIRTUALPHYSICAL,目前仅支持虚拟卡。

可用选项:
VIRTUAL,
PHYSICAL
示例:

"VIRTUAL"

mode_type
enum<string>
必填

模式类型枚举 - SINGLE 或 SHARE。

  • SINGLE - 单卡仅支持预付模式。
  • SHARE - 共享卡可支持借记模式,即关联借记产品和账户。
可用选项:
SHARE,
SINGLE
示例:

"SHARE"

card_limit
number
必填

分配给该卡片的总信用额度,币种参见 card_currency。这不是累计余额,而是类似信用卡的固定信用额度。

各卡产品的字段行为:
  • Business MastercardPersonal Visa:创建卡片时 card_limit必填,且必须大于或等于 0.01
  • Business Visacard_limit可选
    • 若省略,系统默认 card_limit 为 0。
    • 若提供,取值必须大于或等于 0,最多两位小数。不允许负值。

完整能力矩阵参见 卡产品

必填范围: x >= 0
示例:

2100.02

available_balance
string
必填

可用余额,币种参见 card_currency

示例:

2000.05

cardholder
object
必填
no_pin_payment_amount
string
必填

无需 PIN 验证即可进行卡交易的允许金额,包含币种单位(如 2000USD)。此响应字段应与对应的请求参数区分开,后者指定的金额不含币种单位。

示例:

"2000USD"

card_status
enum<string>
必填

卡片状态枚举。更多信息参见卡生命周期与状态指南。

  • PENDING:创建卡片的请求已收到,正在审核中。
  • ACTIVE:创建卡片的请求成功,卡片可以使用。
  • FROZEN:所有进入的授权请求都将被拒绝。卡片可以重新激活以接受新的授权。
  • BLOCKED:因可疑活动,卡片被 UQPAY 锁定。
  • PRE_CANCEL:卡片已被安排注销,处于等待期,期间所有进入的授权请求都将被拒绝。等待期结束后转为 CANCELLED
  • CANCELLED:卡片无法再从此状态重新激活,所有进入的授权请求都将被永久拒绝。
  • LOST:卡片已向 UQPAY 报失。
  • STOLEN:卡片已向 UQPAY 报被盗。
  • FAILED:使用 创建卡片 创建卡片的请求失败。
可用选项:
PENDING,
ACTIVE,
FROZEN,
BLOCKED,
PRE_CANCEL,
CANCELLED,
LOST,
STOLEN,
FAILED
示例:

"ACTIVE"

card_currency
enum<string>

卡币种。

可用选项:
SGD,
USD,
XUSD
示例:

"USD"

card_product_id
string<uuid>

卡产品的唯一标识符。

示例:

"3bd1656b-e691-4aab-a76a-3ead39e7a6f6"

spending_controls
object[]

控制该卡片消费的规则。

risk_controls
object

用户自定义的风控设置。

支持的配置取决于卡产品。能力矩阵参见 卡产品

network_protection
object

嵌入在卡片响应对象中的 ASAF Network Protection 状态。仅 Visa 卡片返回。

metadata
object

任意键值对象。最大长度 = 3200 字节。必须是有效的 JSON 数据。

示例:
update_reason
string

更新卡片状态的原因。

Maximum string length: 100
consumed_amount
string

反映卡限额中已使用的累计金额。

示例:

"51.00"