> ## 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. # Create a refund > 为已完成的付款创建退款 ## OpenAPI ````yaml /zh/global-acquiring/v1.6/payment.yaml post /v2/payment/refunds 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/refunds: post: tags: - Payment Refunds summary: Create a refund description: 为已完成的付款创建退款 operationId: create-refund parameters: - $ref: '#/components/parameters/XClientID' - $ref: '#/components/parameters/XOnBehalfOf' - $ref: '#/components/parameters/XIdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PaymentRefundRequest' responses: '200': description: 成功创建退款 content: application/json: schema: $ref: '#/components/schemas/PaymentRefundResponse' components: parameters: XClientID: in: header name: x-client-id schema: type: string required: true description: UQPAY 生成的 API 客户端 ID example: Up1HIsjiETgON9PMGPXLy7 XOnBehalfOf: in: header name: x-on-behalf-of schema: type: string required: false description: > 指定代表哪个子账户发起该请求。应设置为 `account_id`，可通过 [List Connected Accounts](/zh/account-center/v1.6/api-reference/list-connected-accounts) 获取。若省略或为空，则使用主账户执行请求。 更多信息见 [Connected Accounts](/zh/account-center/v1.6/guide/connected-accounts)。 example: 18523f72-f4de-4f9c-bb8e-ec7d1c4f32be XIdempotencyKey: in: header name: x-idempotency-key schema: type: string format: uuid required: true description: 用于保持操作幂等性的唯一标识符（UUID），确保同一操作重复执行不会产生意外影响或重复结果。它有助于在网络错误、重试或故障时保持数据一致性。 example: 2adesf8e-9d63-44bc-b975-9b6ae3440dde schemas: PaymentRefundRequest: type: object required: - payment_intent_id - amount - reason properties: payment_intent_id: type: string description: 要退款的 PaymentIntent 的 ID example: PI1234567890123456789 maxLength: 36 payment_attempt_id: type: string description: 要退款的 PaymentAttempt 的 ID example: PA1234567890123456789 amount: type: string description: 要退款的金额 example: '10.01' reason: type: string description: 退款原因 maxLength: 100 example: Return good metadata: type: object description: 退款的附加元数据 additionalProperties: type: string example: customer_id: cust_12345 order_id: order_6789 maximum: 3200 PaymentRefundResponse: type: object properties: payment_refund_id: type: string description: 退款的唯一标识 example: RF123456789 payment_attempt_id: type: string description: 已退款的 PaymentAttempt 的 ID example: PA123456789 amount: type: string description: 已退款的金额 example: '10.01' currency: type: string description: 三字母币种代码（ISO 4217） example: USD format: iso-4217 refund_status: type: string description: | 退款的当前状态。 - `INITIATED`：退款已发起。 - `PROCESSING`：退款正在处理中。 - `SUCCEEDED`：退款已成功完成。 - `FAILED`：退款尝试失败。 - `REVERSAL_INITIATED`：退款的冲正已发起。 - `REVERSAL_PROCESSING`：退款的冲正正在处理中。 - `REVERSAL_SUCCEEDED`：退款的冲正已成功完成。 example: SUCCEEDED enum: - INITIATED - PROCESSING - SUCCEEDED - FAILED - REVERSAL_INITIATED - REVERSAL_PROCESSING - REVERSAL_SUCCEEDED create_time: $ref: '#/components/schemas/DateTime' description: 该退款的创建时间。 update_time: $ref: '#/components/schemas/DateTime' description: 该退款最近一次更新或操作的时间。 reason: type: string description: 退款原因 example: Order 1234 has been returned maxLength: 100 metadata: type: object description: 与退款关联的附加元数据。用户自定义的键值对。 additionalProperties: type: string example: customer_id: cust_12345 order_id: order_6789 maximum: 3200 DateTime: type: string format: date/time example: '2024-03-01T00:00:00+08:00' securitySchemes: XAuthToken: type: apiKey in: header name: x-auth-token description: UQPay 提供的登录 API Token。 ````