跳转到主要内容
POST
Update a PaymentIntent

授权

x-auth-token
string
header
必填

UQPay 提供的登录 API Token。

请求头

x-on-behalf-of
string

指定代表哪个子账户发起该请求。应设置为 account_id,可通过 List Connected Accounts 获取。若省略或为空,则使用主账户执行请求。 更多信息见 Connected Accounts

x-idempotency-key
string<uuid>
必填

用于保持操作幂等性的唯一标识符(UUID),确保同一操作重复执行不会产生意外影响或重复结果。它有助于在网络错误、重试或故障时保持数据一致性。

x-client-id
string
必填

UQPAY 生成的 API 客户端 ID

路径参数

id
string
必填

PaymentIntent 的唯一 ID。

示例:

"PI1925112193204883441"

请求体

application/json
amount
string
currency
string

三位币种代码

customer
object

与执行该 Payment Intent 支付的主体相关的客户详情;当请求中指定了 customer_id 参数时应省略此项。

customer_id
string

当该 Payment Intent 用于循环支付时,必须提供客户的唯一标识。若客户身份未知(访客结账)或客户信息通过 customer 对象提供,则此字段应留空。

payment_orders
object

与该 PaymentIntent 关联的采购订单

merchant_order_id
string

商户系统中为该 PaymentIntent 创建的商户参考 ID

Maximum string length: 36
description
string

将向客户展示的描述符。最大长度为 32。

Maximum string length: 32
metadata
object

任意键值对象。最大长度 = 512 字节。必须是合法的 JSON 数据。

示例:
return_url
string

支付认证完成后用于跳转客户的网页 URL 或应用 scheme URI。

Maximum string length: 1024

响应

200 - application/json

成功更新 PaymentIntent

payment_intent_id
string
必填

PaymentIntent 的唯一标识

Maximum string length: 36
示例:

"b1c2d3e4-f5a6-b7c8-d9e0-f1a2b3c4d5e6"

amount
string
必填

支付金额。即你希望向客户收取的订单金额。

示例:

"10.12"

currency
string
必填

三位币种代码

示例:

"SGD"

intent_status
enum<string>
必填

该 PaymentIntent 的状态。

  • REQUIRES_PAYMENT_METHOD:PaymentIntent 正在等待确认请求。
  • REQUIRES_CUSTOMER_ACTION:PaymentIntent 正在等待客户进一步的认证操作,例如 3DS 验证和扫描二维码。请查看 next_action
  • REQUIRES_CAPTURE:PaymentIntent 正在等待你请款以完成支付。
  • PENDING:PaymentIntent 正在等待支付渠道返回最终结果,无需进一步操作。
  • SUCCEEDED:PaymentIntent 已成功,支付完成。
  • CANCELLED:PaymentIntent 已按你的请求取消,支付已关闭。
  • FAILED:PaymentIntent 已失败。
可用选项:
REQUIRES_PAYMENT_METHOD,
REQUIRES_CUSTOMER_ACTION,
REQUIRES_CAPTURE,
PENDING,
SUCCEEDED,
CANCELLED,
FAILED
description
string

创建 PaymentIntent 时的描述符。

Maximum string length: 255
available_payment_method_types
string[] | null

该 PaymentIntent 可用的支付方式类型。

captured_amount
string

从该 PaymentIntent 已请款的金额。

示例:

"10.12"

customer
object

与该 PaymentIntent 关联的客户快照。在创建时提供了 customercustomer_id 时返回。客户的唯一标识在顶层以 customer_id 暴露;该对象内部不包含 id 字段。

customer_id
string

与该 PaymentIntent 关联的客户 ID。访客结账时为空。

Maximum string length: 36
示例:

"cus_asyknf3wlfxhs1s6plamk80i8v"

cancel_time
string<date/time>

该 PaymentIntent 最近一次被取消的时间。仅当 PaymentIntent 成功取消(即状态为 CANCELLED)时存在。

示例:

"2024-03-01T00:00:00+08:00"

cancellation_reason
string

取消该 PaymentIntent 的原因。

示例:

"Order cancelled"

client_secret
string

用于浏览器或 App 的 PaymentIntent client secret。由 PaymentIntent 创建接口或查询接口返回。返回的 client_secret 有效期为 60 分钟。

示例:

"eyJhbGciOiJI***********ujNdZ1DF9CqWEfF1jphxI"

merchant_order_id
string

商户系统中为该 PaymentIntent 创建的商户参考 ID

Maximum string length: 36
示例:

"1bf70d90-9ed0-48ce-9370-9bd7ef6ab9ee"

metadata
object

任意键值对象。最大长度 = 512 字节。必须是合法的 JSON 数据。

示例:
next_action
object

若存在,该属性会告诉你:为了让客户使用所提供的来源完成支付,你需要采取哪些操作。

return_url
string

支付认证完成后用于跳转客户的网页 URL 或应用 scheme URI。

示例:

"https://127.0.0.1:8080/api/v1/callback"

create_time
string<date/time>

该 PaymentIntent 的创建时间。

示例:

"2024-03-01T00:00:00+08:00"

complete_time
string<date/time>

该 PaymentIntent 达到最终状态的时间。

示例:

"2024-03-01T00:00:00+08:00"

update_time
string<date/time>

该 PaymentIntent 最近一次更新或操作的时间。

示例:

"2024-03-01T00:00:00+08:00"

latest_payment_attempt
object

该 PaymentIntent 下创建的最新 PaymentAttempt。