跳转到主要内容
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

三位币种代码

示例:

"SGD"

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
示例:

"Updated contract test"

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 已失败。
  • PARTIALLY_CAPTURED: 部分请款的授权仍有待处理余额;不要再次提交请款。
  • EXPIRED: 预授权已过期并释放。
可用选项:
PARTIALLY_CAPTURED,
EXPIRED,
REQUIRES_PAYMENT_METHOD,
REQUIRES_CUSTOMER_ACTION,
REQUIRES_CAPTURE,
PENDING,
SUCCEEDED,
CANCELLED,
FAILED
示例:

"SUCCEEDED"

current_funds_action
object

查询PaymentIntent详情或列表时,若存在则返回退款或授权释放详情。

capture_records
object[]

查询PaymentIntent详情和列表时返回的请款记录。

authorization_type
enum<string>

本次支付的授权模式。

可用选项:
authorization,
pre_authorization
authorization_expires_at
string<date-time> | null

预授权到期时间。未记录时为null。请使用返回的时间,不要假定固定冻结期限。

available_to_capture
string

剩余可请款预授权额度。最终请款会消耗可用授权额度;渠道处理结果请查看capture_records。

available_to_void
string

剩余预授权额度,与available_to_capture相同。值大于零不代表一定允许撤销。

description
string

创建 PaymentIntent 时的描述符。

Maximum string length: 255
available_payment_method_types
string[] | null

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

captured_amount
string

PaymentIntent记录的聚合请款金额。请款受理时可能早于渠道完成更新此值;处理结果请查看capture_records。

示例:

"10.12"

customer
object

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

customer_id
string

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

Maximum string length: 36
示例:

"cus_asyknf3wlfxhs1s6plamk80i8v"

cancel_time

取消时间未记录时为空字符串。

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 | null

支付关联的元数据。未设置元数据时返回 null。

next_action
object | null

无可用的下一步操作时为 null;否则按返回的操作信息继续处理支付。

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

完成时间未记录时为空字符串。

update_time
string<date/time>

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

示例:

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

latest_payment_attempt
Latest payment attempt · object

最新 PaymentAttempt;没有可用的支付尝试时为 null。