跳转到主要内容
POST
Get credential
响应有两种模式,取决于平台是否已在 Clink 登记公钥:
  • 已登记公钥(matched: true):Clink 把卡字段密封到 key/payload 信封中,只有持有配对私钥的平台才能解密。
  • 未登记公钥(matched: false):当服务端启用明文模式且 gateway 响应脱敏已生效时,Clink 在响应中以明文返回 DPAN 和动态 CVV。卡可以直接使用,但这些字段会以明文到达平台后端。
在 Clink 登记公钥即可使用加密模式;生产环境建议登记。 响应不下发凭证截止时间:凭证有效期以 card(明文模式)或解密后 payload(密文模式)中的 dynamicDataExpiration 为准。

登记平台公钥

联系 Clink 在目标环境登记平台的 RSA 公钥;公钥按平台 client name 映射。是否登记公钥决定响应模式:已登记时凭证密封到该公钥;未登记时,只有在服务端启用明文模式且 gateway 响应脱敏已生效的情况下才返回明文卡字段(MCP 等价的回退行为);默认开关关闭时接口会 fail closed。生产使用前请先登记公钥。
未登记公钥时,在服务端启用明文模式的前提下,响应会以明文把 DPAN 和动态 CVV 返回给平台后端。不要把这些字段写入日志、模型输入或普通存储,也不要在结账后保留。请在 Clink 登记公钥(生产环境建议)以切换到密封的 key/payload 模式。该明文回退行为与 MCP get_credential 一致。在 gateway 响应脱敏尚未生效的环境中不要启用明文模式:该模式由服务端 portal-plaintext-enabled 配置开关控制(默认关闭),开关关闭时接口会 fail closed 并返回 71211012(credential_public_key_not_configured),而不是明文卡字段。

解密密封响应

当 matched 为 true 时,使用平台私钥解密 key 和 payload。解密后的 payload 包含 orderId、paymentExecutionDetailId、clientReferenceId、status、网络凭证(DPAN、动态 CVV 和有效期)以及持卡人和地址字段。信封格式和解密示例见解密。 不要把解密后的卡字段写入日志、模型输入或普通记录,并以解密后 payload 中的有效期信息(dynamicDataExpiration)为准判断凭证可用时间。保存 client_reference_id;回报支付结果会用到它。

幂等

client_reference_id 是幂等键。使用相同 client_reference_id 重试会返回同一凭证:matched 为 true 时返回同一密封信封,明文模式下从服务端加密缓存返回同一张卡,不会重复签发。携带不同参数复用时返回 409,code 为 71211011(portal_conflict)。

授权

Authorization
string
header
必填

Portal user token from POST /agent/cwallet/platform/portal/tokens. Reads require portal:read; writes require portal:write.

请求体

application/json
instruction_id
string
必填

ACTIVE instruction owned by the token's customer.

示例:

"inst_..."

mandate_id
string
必填

Mandate under that instruction that covers the purchase.

示例:

"mand_..."

client_reference_id
string
必填

Platform-side reference and idempotency key for this purchase. Store it; the result report uses the same value.

示例:

"platform-ref-001"

amount
string
必填

Transaction amount, decimal string in major currency units.

示例:

"12.50"

currency_code
string
必填

Three-letter currency code.

示例:

"USD"

merchant_url
string
必填

Merchant checkout URL. Must use HTTPS.

示例:

"https://shop.example.com/checkout"

merchant_name
string

Merchant display name. Defaults to the host of merchant_url.

示例:

"Example Store"

merchant_country_code
string
默认值:US

Merchant country, ISO 3166-1 alpha-2.

示例:

"US"

merchant_order_id
string

Merchant-side order ID, when available.

示例:

"shop-order-1"

products
object[]

Line items for the purchase.

shipping_address
object

Shipping address.

响应

Success

code
integer<int32>

200 on success.

示例:

200

msg
string

Result message.

示例:

"Success"

data
Sealed (matched: true) · object

Returned when your platform has a registered public key. Contains only matched, key, and payload; the IDs are inside the decrypted payload.