> ## Documentation Index > Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt > Use this file to discover all available pages before exploring further. # List all PaymentAttempts > 查询 PaymentAttempt 列表，支持可选的筛选条件 ## OpenAPI ````yaml /zh/global-acquiring/v1.6/payment.yaml get /v2/payment/payment_attempts openapi: 3.0.2 info: title: Payment API version: 0.0.1 x-source-en-commit: 821171b x-source-en-path: global-acquiring/v1.6/payment.yaml description: > UQPAY Payment API 让你接受付款、管理交易，并处理退款与出款。 ## 功能概览 - 使用卡、数字钱包和本地支付方式创建并确认 PaymentIntent - 处理全额和部分退款 - 管理客户与已保存的支付方式 - 创建出款与银行账户记录 - 查询 PaymentAttempt、余额与交易历史 ## 身份认证 所有请求都需要携带有效的鉴权 Token，Token 通过 [Access Token](/zh/account-center/v1.6/api-reference/access-token) 接口获取。请在 `x-auth-token` 请求头中携带该 Token。 ## 幂等性 POST 请求支持 `x-idempotency-key` 请求头，可在不重复创建资源的前提下安全重试。 contact: name: UQPAY Support Team url: https://www.uqpay.com/support email: support@uqpay.com license: name: Proprietary url: https://www.uqpay.com/legal/api-terms termsOfService: https://www.uqpay.com/legal/terms servers: - url: https://api-sandbox.uqpaytech.com/api description: 沙盒环境基础 URL。 - url: https://api.uqpay.com/api description: 生产环境基础 URL。 security: - XAuthToken: [] tags: - name: Customers description: 创建和管理客户档案。客户对象保存支付方式和账单信息，可在多笔支付中复用。 - name: Payment Intents description: >- PaymentIntent 引导你完成向客户收款的整个流程。建议你的系统中每个订单或客户会话只创建一个 PaymentIntent。之后可以引用该 PaymentIntent，查看某次会话的 PaymentAttempt 历史。 - name: Payment Attempts description: >- 每当客户使用所选 PaymentMethod 付款时，都会创建一个 PaymentAttempt 对象。通过该 API 可以了解客户是如何为订单付款的。 - name: Payment Refunds description: > 你可以创建多笔部分退款，直至累计达到原交易金额。每笔退款都会生成唯一记录，并自动校验可用余额。 PaymentIntent 引导你完成向客户收款的整个流程。建议你的系统中每个订单或客户会话只创建一个 PaymentIntent。之后可以引用该 PaymentIntent，查看某次会话的 PaymentAttempt 历史。 - name: Payment Balances description: | 支付余额管理让你查询不同币种的账户余额。你可以查询单个币种的余额，也可以分页查询所有币种的余额。 - name: Payment Payouts description: | 出款管理让你创建和管理用于资金划转的出款单。你可以创建出款、查询单笔出款，也可以分页并按条件筛选列出所有出款。 - name: Terminal Management description: 用于 POS 设备注册和密钥管理的终端管理 API。 - name: Bank Accounts description: | 用于结算账户的银行账户管理 API。可创建、更新、查询和列出用于接收结算款项的银行账户。 paths: /v2/payment/payment_attempts: get: tags: - Payment Attempts summary: List all PaymentAttempts description: 查询 PaymentAttempt 列表，支持可选的筛选条件 operationId: list-payment-attempts parameters: - $ref: '#/components/parameters/XClientID' - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/PageNumber' - name: payment_intent_id in: query description: 按 PaymentIntent ID 筛选 PaymentAttempt required: false schema: type: string example: PI1234567890123456789 - name: attempt_status in: query description: | 按状态筛选 PaymentAttempt。 - `INITIATED`：根据初始请求创建。 - `AUTHENTICATION_REDIRECTED`：等待客户身份验证。 - `PENDING_AUTHORIZATION`：等待支付渠道的最终决定。 - `AUTHORIZED`：授权成功完成。 - `CAPTURE_REQUESTED`：已提交请款，支付视为完成。 - `SETTLED`：资金已由支付渠道结算并由 UQPAY 收到。 - `SUCCEEDED`：UQPAY 已将资金结算到你的钱包。 - `CANCELLED`：PaymentAttempt 已取消。 - `EXPIRED`：未在允许的时间窗口内完成。 - `FAILED`：PaymentAttempt 失败。 required: false schema: type: string enum: - INITIATED - AUTHENTICATION_REDIRECTED - PENDING_AUTHORIZATION - AUTHORIZED - CAPTURE_REQUESTED - SETTLED - SUCCEEDED - CANCELLED - EXPIRED - FAILED example: INITIATED responses: '200': description: 成功获取 PaymentAttempt 列表 content: application/json: schema: type: object properties: total_pages: $ref: '#/components/schemas/TotalPages' total_items: $ref: '#/components/schemas/TotalItems' data: type: array items: $ref: '#/components/schemas/PaymentAttemptResponse' components: parameters: XClientID: in: header name: x-client-id schema: type: string required: true description: UQPAY 生成的 API 客户端 ID example: Up1HIsjiETgON9PMGPXLy7 PageSize: name: page_size description: 每页返回的最大条目数，取值范围 1 - 100。 in: query required: true schema: type: integer minimum: 1 example: 10 maximum: 100 PageNumber: name: page_number description: 用于获取下一批条目的页码，取值必须大于 1。 in: query required: true schema: type: integer minimum: 1 example: 1 schemas: TotalPages: type: integer example: 10 description: 可用条目的总页数。 TotalItems: type: integer example: 105 description: 可用条目的总数。 PaymentAttemptResponse: type: object required: - attempt_id - amount - currency properties: attempt_id: type: string description: 该 PaymentAttempt 的唯一标识。 example: 24fc62b4-90d1-42e3-96ab-dd54ccc648b3 amount: $ref: '#/components/schemas/Amount' example: '9.98' description: 该 PaymentAttempt 的金额。 currency: $ref: '#/components/schemas/Currency' example: SGD captured_amount: $ref: '#/components/schemas/Amount' description: 已请款金额。 example: '0.00' refunded_amount: $ref: '#/components/schemas/Amount' description: 已退款金额。 example: '0.00' create_time: $ref: '#/components/schemas/DateTime' description: 该 PaymentAttempt 的创建时间。 example: '2025-03-21T17:17:32+08:00' update_time: $ref: '#/components/schemas/DateTime' description: 该 PaymentAttempt 最近一次更新或操作的时间。 example: '2025-03-21T17:17:32+08:00' complete_time: $ref: '#/components/schemas/DateTime' description: 该 PaymentAttempt 的完成时间。 cancellation_reason: type: string description: 取消该 PaymentIntent 的原因。 example: Order cancelled auth_code: type: string description: 授权成功后由发卡行返回的授权码。 example: A12B3C arn: type: string description: 收单参考号（ARN）。一个 23 位标识，用于跨机构对账和拒付追踪。 example: '74537604221222132710572' rrn: type: string description: 检索参考号（RRN）。一个 12 位标识，用于交易查询和客服查询。 example: '123456789012' advice_code: type: string description: | 发卡行建议码，指示拒绝后的推荐操作。帮助商户实施智能重试策略。 - `01`：新的尝试可能成功。建议重试。 - `02`：请勿重试。请尝试其他支付方式。 - `03`：请勿重试。持卡人应联系其发卡行。 - `21`：取消所有待处理的授权。卡片可能已泄露。 - `85`：请勿重试。发卡行不会批准此类交易。 enum: - '01' - '02' - '03' - '21' - '85' example: '01' authentication_data: type: object description: 该 PaymentAttempt 的认证与验证数据。 properties: cvv_result: type: string description: | 由发卡行返回的 CVV/CVC 验证结果。 - `M`：匹配。 - `N`：不匹配。 - `P`：未处理。 - `U`：不支持。 enum: - M - 'N' - P - U avs_result: type: string description: 地址验证系统（AVS）结果。指示所提供的账单地址是否与发卡行的记录匹配。 example: 'Y' three_ds: $ref: '#/components/schemas/CardThreeDSResponse' payment_method: $ref: '#/components/schemas/PaymentMethodResponse' description: 该 PaymentAttempt 所使用的支付方式详情。 failure_code: $ref: '#/components/schemas/FailureCode' attempt_status: type: string description: | 该 PaymentAttempt 的状态。 - `INITIATED`：已根据初始请求创建 PaymentAttempt。 - `AUTHENTICATION_REDIRECTED`：等待客户完成身份验证，例如 3D Secure 或扫描二维码。 - `PENDING_AUTHORIZATION`：已收到授权请求，正在等待支付渠道的最终决定。 - `AUTHORIZED`：授权已成功完成。将根据配置自动或手动请款。 - `CAPTURE_REQUESTED`：请款请求已成功提交，支付视为完成。 - `SETTLED`：资金已从支付渠道结算并由 UQPAY 收到。 - `SUCCEEDED`：UQPAY 已将资金结算至你的钱包。 - `CANCELLED`：PaymentAttempt 已取消。若有已授权资金，将退回给客户。 - `EXPIRED`：PaymentAttempt 未在允许的时间窗口内完成，已过期。 - `FAILED`：PaymentAttempt 已失败。请创建新的 PaymentAttempt 重试。 example: INITIATED enum: - INITIATED - AUTHENTICATION_REDIRECTED - PENDING_AUTHORIZATION - AUTHORIZED - CAPTURE_REQUESTED - SETTLED - SUCCEEDED - CANCELLED - EXPIRED - FAILED Amount: type: string Currency: type: string description: 三位币种代码 DateTime: type: string format: date/time example: '2024-03-01T00:00:00+08:00' CardThreeDSResponse: type: object properties: three_ds_version: type: string description: 用于认证的 3D Secure 协议版本。 example: 2.2.0 eci: type: string description: 电子商务指示符（ECI）。一个两位数代码，表示交易的安全级别及责任转移结果。 example: '05' cavv: type: string description: 持卡人认证验证值（CAVV）。由发卡行的访问控制服务器（ACS）生成的加密值，用于确认认证成功。 example: AAABCZIhcQAAAABZlyFxAAAAAAA= three_ds_authentication_status: type: string description: | 3DS 认证的结果。 - `Y`：认证成功。 - `A`：已尝试认证。责任转移已授予，但未完成完整认证。 - `N`：认证失败或被拒绝。 - `U`：因技术或其他问题无法执行认证。 - `R`：认证被发卡行拒绝。 - `C`：需要质询。需进行额外的验证步骤。 example: 'Y' enum: - 'Y' - A - 'N' - U - R - C three_ds_cancellation_reason: type: string description: 3DS 认证流程被取消的原因（如适用）。 example: '01' PaymentMethodResponse: type: object properties: type: type: string description: 用于确认 PaymentIntent 的支付方式详情。设置 `payment_method` 后，PaymentIntent 将自动确认。 discriminator: propertyName: type mapping: card: $ref: '#/components/schemas/CardPaymentMethodResponse' applepay: $ref: '#/components/schemas/ApplePayPaymentMethodResponse' googlepay: $ref: '#/components/schemas/GooglePayPaymentMethodResponse' alipaycn: $ref: '#/components/schemas/AlipayCNPaymentMethodResponse' alipayhk: $ref: '#/components/schemas/AlipayHkPaymentMethodResponse' unionpay: $ref: '#/components/schemas/UnionPayPaymentMethodResponse' wechatpay: $ref: '#/components/schemas/WeChatPayPaymentMethodResponse' grabpay: $ref: '#/components/schemas/GrabPayPaymentMethodResponse' crypto: $ref: '#/components/schemas/CryptoPaymentMethodResponse' paynow: $ref: '#/components/schemas/PayNowPaymentMethodResponse' truemoney: $ref: '#/components/schemas/TruemoneyPaymentMethodResponse' tng: $ref: '#/components/schemas/TngPaymentMethodResponse' gcash: $ref: '#/components/schemas/GCashPaymentMethodResponse' dana: $ref: '#/components/schemas/DanaPaymentMethodResponse' kakaopay: $ref: '#/components/schemas/KakaopayPaymentMethodResponse' toss: $ref: '#/components/schemas/TossPaymentMethodResponse' naverpay: $ref: '#/components/schemas/NaverpayPaymentMethodResponse' oneOf: - $ref: '#/components/schemas/CardPaymentMethodResponse' - $ref: '#/components/schemas/ApplePayPaymentMethodResponse' - $ref: '#/components/schemas/GooglePayPaymentMethodResponse' - $ref: '#/components/schemas/AlipayCNPaymentMethodResponse' - $ref: '#/components/schemas/AlipayHkPaymentMethodResponse' - $ref: '#/components/schemas/UnionPayPaymentMethodResponse' - $ref: '#/components/schemas/WeChatPayPaymentMethodResponse' - $ref: '#/components/schemas/GrabPayPaymentMethodResponse' - $ref: '#/components/schemas/CryptoPaymentMethodResponse' - $ref: '#/components/schemas/PayNowPaymentMethodResponse' - $ref: '#/components/schemas/TruemoneyPaymentMethodResponse' - $ref: '#/components/schemas/TngPaymentMethodResponse' - $ref: '#/components/schemas/GCashPaymentMethodResponse' - $ref: '#/components/schemas/DanaPaymentMethodResponse' - $ref: '#/components/schemas/KakaopayPaymentMethodResponse' - $ref: '#/components/schemas/TossPaymentMethodResponse' - $ref: '#/components/schemas/NaverpayPaymentMethodResponse' FailureCode: type: string description: >- PaymentAttempt 失败码。可能的取值见 [Error Code Reference.payment_error](/zh/global-acquiring/v1.6/guide/error-codes) 部分。 example: '' CardPaymentMethodResponse: title: card type: object required: - type - card properties: type: type: string enum: - card card: type: object required: - card_name - card_number - network - authorization_type properties: card_name: type: string description: 持卡人姓名。最大长度为 128。 example: john doe card_number: type: string description: 脱敏后的卡号。前 6 位（BIN）和后 4 位可见。 example: 541333******4047 network: type: string description: 卡组织。例如 `visa`、`mastercard`、`unionpay`。 enum: - visa - mastercard - unionpay brand: type: string description: 卡品牌。 example: visa bin: type: string description: 银行识别码（BIN）。卡号前 6–8 位，用于标识发卡机构。 example: '541333' last4: type: string description: 卡号的后四位。 example: '4047' card_type: type: string description: 卡的资金类型。 enum: - credit - debit - prepaid expiry_month: type: string description: 卡片的两位到期月份。 example: '12' expiry_year: type: string description: 卡片的四位到期年份。 example: '2027' billing: $ref: '#/components/schemas/CardBilling' auto_capture: type: boolean default: true description: 指定支付授权后是否自动请款。默认为 `true`。如果你希望稍后再请款，请设为 `false`。 authorization_type: type: string description: >- 卡支付的授权类型。可选 `authorization`（默认）和 `pre_authorization`。使用 `pre_authorization` 可冻结资金超过 7 天，仅 Visa 和 Mastercard 支持。预授权时 `auto_capture` 必须为 `false`。 enum: - authorization - pre_authorization ApplePayPaymentMethodResponse: title: applepay type: object required: - type - applepay properties: type: type: string enum: - applepay applepay: type: object description: 响应中返回的 Apple Pay 支付信息。 properties: flow: type: string description: 本次支付所使用的收银流程。 enum: - redirect - mobile_web - mobile_app - contactless os_type: type: string description: 客户设备的操作系统类型。 enum: - ios is_present: type: boolean description: 是否为线下（offline）支付。 network: type: string enum: - visa - mastercard - amex - discover - jcb card_type: type: string description: 所用卡的类型（例如 credit、debit）。 enum: - debit - credit token_type: type: string enum: - decrypted - encrypted auth_method: type: string enum: - cryptogram_3ds - pan_only GooglePayPaymentMethodResponse: title: googlepay type: object required: - type - googlepay properties: type: type: string enum: - googlepay googlepay: type: object description: 响应中返回的 Google Pay 支付信息。 properties: flow: type: string description: 本次支付所使用的收银流程。 enum: - redirect - mobile_web - mobile_app - contactless os_type: type: string description: 客户设备的操作系统类型。 enum: - ios - android is_present: type: boolean description: 是否为线下（offline）支付。 network: type: string enum: - visa - mastercard - amex - discover - jcb card_type: type: string description: 所用卡的类型（例如 credit、debit）。 enum: - debit - credit token_type: type: string enum: - decrypted - encrypted auth_method: type: string enum: - cryptogram_3ds - pan_only AlipayCNPaymentMethodResponse: title: alipaycn type: object required: - type - alipaycn properties: type: type: string enum: - alipaycn alipaycn: type: object description: 响应中返回的 AlipayCN 支付信息。 properties: flow: type: string description: 本次支付所使用的收银流程。 enum: - qrcode os_type: type: string description: 客户设备的操作系统类型。 enum: - ios - android is_present: type: boolean description: 是否为线下（offline）支付。 AlipayHkPaymentMethodResponse: title: alipayhk type: object required: - type - alipayhk properties: type: type: string enum: - alipayhk alipayhk: type: object description: 响应中返回的 AlipayHK 支付信息。 properties: flow: type: string description: 本次支付所使用的收银流程。 enum: - qrcode os_type: type: string description: 客户设备的操作系统类型。 enum: - ios - android is_present: type: boolean description: 是否为线下（offline）支付。 UnionPayPaymentMethodResponse: title: unionpay type: object required: - type - unionpay properties: type: type: string enum: - unionpay unionpay: type: object description: 响应中返回的 UnionPay 支付信息。 properties: flow: type: string description: 本次支付所使用的收银流程。 enum: - qrcode - securepay os_type: type: string description: 客户设备的操作系统类型。 enum: - ios - android is_present: type: boolean description: 是否为线下（offline）支付。 WeChatPayPaymentMethodResponse: title: wechatpay type: object required: - type - wechatpay properties: type: type: string enum: - wechatpay wechatpay: type: object description: 响应中返回的 WeChat Pay 支付信息。 properties: flow: type: string description: 本次支付所使用的收银流程。 enum: - qrcode - mini_program - mobile_app - mobile_web - official_account os_type: type: string description: 客户设备的操作系统类型。 enum: - ios - android is_present: type: boolean description: 是否为线下（offline）支付。 GrabPayPaymentMethodResponse: title: grabpay type: object required: - type - grabpay properties: type: type: string enum: - grabpay grabpay: type: object description: 响应中返回的 GrabPay 支付信息。 properties: flow: type: string description: 本次支付所使用的收银流程。 enum: - qrcode os_type: type: string description: 客户设备的操作系统类型。 enum: - ios - android is_present: type: boolean description: 是否为线下（offline）支付。 shopper_name: type: string description: 购物者的姓名。 CryptoPaymentMethodResponse: title: crypto type: object required: - type - crypto properties: type: type: string enum: - crypto crypto: type: object description: 响应中返回的加密货币支付信息。 properties: flow: type: string description: 本次支付所使用的收银流程。 enum: - redirect - qrcode network: type: string enum: - ETH - TRON is_present: type: boolean description: 是否为线下（offline）支付。 PayNowPaymentMethodResponse: title: paynow type: object required: - type - paynow properties: type: type: string enum: - paynow paynow: type: object description: 响应中返回的 PayNow 支付信息。 properties: flow: type: string description: 本次支付所使用的收银流程。 enum: - qrcode is_present: type: boolean description: 是否为线下（offline）支付。 TruemoneyPaymentMethodResponse: title: truemoney type: object required: - type - truemoney properties: type: type: string enum: - truemoney truemoney: type: object description: 响应中返回的 Truemoney 支付信息。 properties: flow: type: string description: 本次支付所使用的收银流程。 enum: - qrcode os_type: type: string description: 客户设备的操作系统类型。 enum: - ios - android is_present: type: boolean description: 是否为线下（offline）支付。 TngPaymentMethodResponse: title: tng type: object required: - type - tng properties: type: type: string enum: - tng tng: type: object description: 响应中返回的 Touch'n Go 支付信息。 properties: flow: type: string description: 本次支付所使用的收银流程。 enum: - qrcode os_type: type: string description: 客户设备的操作系统类型。 enum: - ios - android is_present: type: boolean description: 是否为线下（offline）支付。 GCashPaymentMethodResponse: title: gcash type: object required: - type - gcash properties: type: type: string enum: - gcash gcash: type: object description: 响应中返回的 GCash 支付信息。 properties: flow: type: string description: 本次支付所使用的收银流程。 enum: - qrcode os_type: type: string description: 客户设备的操作系统类型。 enum: - ios - android is_present: type: boolean description: 是否为线下（offline）支付。 DanaPaymentMethodResponse: title: dana type: object required: - type - dana properties: type: type: string enum: - dana dana: type: object description: 响应中返回的 Dana 支付信息。 properties: flow: type: string description: 本次支付所使用的收银流程。 enum: - qrcode os_type: type: string description: 客户设备的操作系统类型。 enum: - ios - android is_present: type: boolean description: 是否为线下（offline）支付。 KakaopayPaymentMethodResponse: title: kakaopay type: object required: - type - kakaopay properties: type: type: string enum: - kakaopay kakaopay: type: object description: 响应中返回的 KakaoPay 支付信息。 properties: flow: type: string description: 本次支付所使用的收银流程。 enum: - qrcode os_type: type: string description: 客户设备的操作系统类型。 enum: - ios - android is_present: type: boolean description: 是否为线下（offline）支付。 TossPaymentMethodResponse: title: toss type: object required: - type - toss properties: type: type: string enum: - toss toss: type: object description: 响应中返回的 Toss Pay 支付信息。 properties: flow: type: string description: 本次支付所使用的收银流程。 enum: - qrcode os_type: type: string description: 客户设备的操作系统类型。 enum: - ios - android is_present: type: boolean description: 是否为线下（offline）支付。 NaverpayPaymentMethodResponse: title: naverpay type: object required: - type - naverpay properties: type: type: string enum: - naverpay naverpay: type: object description: 响应中返回的 Naver Pay 支付信息。 properties: flow: type: string description: 本次支付所使用的收银流程。 enum: - qrcode os_type: type: string description: 客户设备的操作系统类型。 enum: - ios - android is_present: type: boolean description: 是否为线下（offline）支付。 CardBilling: description: 客户的账单信息。 type: object required: - first_name - last_name - email - address properties: first_name: type: string description: 客户的名字。最大长度为 128。 maxLength: 128 example: John last_name: type: string description: 客户的姓氏。最大长度为 128。 maxLength: 128 example: Doe email: type: string description: 客户的电子邮箱地址。 maxLength: 225 example: john.doe@example.com format: email phone_number: type: string description: 客户的电话号码。 maxLength: 36 example: '12025550123' address: $ref: '#/components/schemas/Address' Address: type: object required: - country_code - city - street - postcode properties: country_code: type: string description: 两位国家/地区代码，ISO 3166-1 alpha-2 格式。 minLength: 2 maxLength: 2 example: SG state: type: string description: | 地址所在的州或省，最多 100 个字符。 - 当 `country_code` 为 "US" 或 "CA" 时必填。 maxLength: 100 example: '' city: type: string description: 地址所在的城市，最多 100 个字符。 maxLength: 100 example: Singapore street: type: string description: 地址所在的街道，最多 100 个字符。 maxLength: 100 example: '444 Orchard Rd, Midpoint Orchard, Singapore ' postcode: type: string description: 地址的邮政编码，最多 10 个字符。 maxLength: 10 example: '924011' securitySchemes: XAuthToken: type: apiKey in: header name: x-auth-token description: UQPay 提供的登录 API Token。 ````