> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payin 退款

此接口允许您全额退款之前已授权的 Payin 交易。

**退款要求**：

* 退款金额必须与原支付金额一致。
* 退款必须发送至与原付款时相同的收款人和账户。


## OpenAPI

````yaml openapi/zh/localpayment.json PATCH /api/payin/{externalId}/refund
openapi: 3.1.0
info:
  version: '1.0'
  title: Localpayment
  contact:
    name: Support
    url: mailto:support@localpayment.com
servers:
  - url: https://api.stage.localpayment.com
    description: Stage
security:
  - token: []
paths:
  /api/payin/{externalId}/refund:
    patch:
      summary: 收款退款
      operationId: refund-a-payin
      parameters:
        - name: Authorization
          in: header
          description: >-
            用于身份验证的 Bearer
            访问令牌。该令牌可从[获取访问令牌](/zh/reference/get-token)或[刷新访问令牌](/zh/reference/refresh-token)endpoint
            获取。
          required: true
          schema:
            type: string
        - name: externalId
          in: path
          description: 您这边会生成一个用于交易追溯的ID。该ID必须是唯一的，并且只接受字母数字字符和连字符（例如UUID4）。
          required: true
          schema:
            type: string
            pattern: '[a-zA-Z0-9\- ]+'
            examples:
              - 53025bf4-4c87-4b4f-8fea-b47004440f37
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                externalId:
                  type: string
                  description: >-
                    系统生成的唯一标识符，用于追踪交易（包含字母、数字和连字符）。我们建议使用 UUID4 以确保唯一性。**仅
                    Pix（巴西）和现金退款需要此标识符。**
                beneficiary:
                  type: object
                  description: 包含退款受益人详细信息的对象。**仅 Pix（巴西）和现金退款必填。**
                  properties:
                    type:
                      type: string
                      enum:
                        - COMPANY
                        - INDIVIDUAL
                      description: 受益人类型（例如 `INDIVIDUAL`、`COMPANY`）。
                    name:
                      type: string
                      description: >-
                        受益人名称。允许的字符取决于 `type` 字段：对于
                        `individual`，允许字母（包括带重音符号的字符）、空格和点（`.`）；对于
                        `company`，允许相同字符集，另外还允许数字、下划线（`_`）和连字符（`-`）。
                      minLength: 2
                      maxLength: 255
                    lastname:
                      type: string
                      description: >-
                        受益人的姓氏。当 `type` 为 `individual` 时必填，当 `type` 为 `company`
                        时忽略。允许的字符取决于 `type`：对于
                        `individual`，允许字母（包括带重音符号的字符）、空格和点（`.`）；对于
                        `company`，允许相同字符集，另外还允许数字、下划线（`_`）和连字符（`-`）。
                      minLength: 2
                      maxLength: 255
                    document:
                      type: object
                      properties:
                        type:
                          type: string
                          description: >-
                            根据签发国家/地区的不同，[身份证明文件类型](/zh/reference/identity-document-types)可能包括国民身份证号码、社会保障号码或驾驶执照。
                        id:
                          type: string
                          description: 身份证件号码（通常为数字）。该号码必须符合特定证件类型的有效规定。
                    bank:
                      type: object
                      description: 受益人银行账户信息。
                      properties:
                        name:
                          type: string
                          description: 银行名称。
                        code:
                          type: string
                          description: '银行代码。 '
                        account:
                          type: object
                          description: 受益人银行账户详情。
                          properties:
                            type:
                              type: string
                              description: '银行账户类型（例如 `C`、`S`）。 '
                            number:
                              type: string
                              description: 银行账号。
                          required:
                            - type
                            - number
                        branch:
                          type: object
                          description: '**仅限巴西。** '
                          properties:
                            code:
                              type: string
                              description: 分行代码（1 至 5 位数字）。
                            name:
                              type: string
                              description: '分行名称。 '
                      required:
                        - name
                        - code
                        - account
                  required:
                    - type
                    - name
                    - bank
                comment:
                  type: string
                  description: 评论或备注，提供有关退款交易的补充信息。
              required:
                - externalId
                - beneficiary
              x-examples:
                Example 1:
                  comment: Refund API VA
                  beneficiary:
                    type: Type
                    name: Name
                    lastname: LastName
                    document:
                      type: DocumentType
                      id: DocumentId
                    bank:
                      name: BankName
                      code: Code
                      account:
                        type: BankAccountType
                        number: AccountNumber
            examples:
              Pix (Brazil) Refund:
                value:
                  comment: Pix refund
                  beneficiary:
                    type: INDIVIDUAL
                    name: John
                    lastname: Doe
                    document:
                      type: DocumentType
                      id: DocumentId
                    bank:
                      name: BankName
                      code: Code
                      account:
                        type: BankAccountType
                        number: AccountNumber
              902 - The payin was refunded:
                value:
                  externalId: e9407459-1ecc-4e18-800b-4bbae006afe2
                  internalId: 3e90d58c-8d3a-4c75-916e-a6d0add4f3b3
                  status:
                    code: '902'
                    description: REFUNDED
                    detail: The payin was refunded
              Cash refund:
                value:
                  comment: Cash refund
                  beneficiary:
                    type: INDIVIDUAL
                    name: John
                    lastname: Doe
                    document:
                      type: DocumentType
                      id: DocumentId
                    bank:
                      name: BankName
                      code: Code
                      account:
                        type: BankAccountType
                        number: AccountNumber
              Capture refund:
                value:
                  comment: Credit Card refund
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  externalId:
                    type: string
                    description: 系统生成的唯一标识符，用于跟踪交易（包含字母、数字和连字符）。我们建议使用 UUID4 以确保唯一性。
                  internalId:
                    type: string
                    description: Localpayment交易标识符。
                  status:
                    type: object
                    title: 状态
                    description: 操作状态。
                    properties:
                      code:
                        type: string
                        description: '[状态码](/zh/reference/transaction-status-error-codes)。'
                        examples:
                          - '902'
                      description:
                        type: string
                        description: '[状态描述](/zh/reference/transaction-status-error-codes)。'
                        examples:
                          - REFUNDED
                      detail:
                        type: string
                        description: 更多状态信息。
                        examples:
                          - The payin was refunded
                x-examples:
                  Example 1:
                    externalId: '{{ExternalId}}'
                    internalId: '{{InternalId}}'
                    status:
                      code: '902'
                      description: REFUNDED
                      detail: The payin was refunded
              examples:
                902 - The payin was refunded.:
                  value:
                    externalId: e36ef929-c2d4-fcf0-b30c-99dc51798f4b
                    internalId: c09095fb-6a0e-47af-9f43-3d9452b0f290
                    status:
                      code: '902'
                      description: REFUNDED
                      detail: The payin was refunded
        '400':
          description: 错误的请求
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: object
                    description: 操作状态。
                    properties:
                      code:
                        type: string
                        description: '[状态码](/zh/reference/transaction-status-error-codes)。'
                      description:
                        type: string
                        description: 状态描述。
                      detail:
                        type: string
                        description: 更多状态信息。
                x-examples:
                  Example 1:
                    status:
                      code: '400'
                      description: ERROR
                      detail: Invalid operation
              examples:
                400 - Invalid operation:
                  value:
                    status:
                      code: '400'
                      description: ERROR
                      detail: Invalid operation
        '401':
          description: 未经授权。
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: 回复的补充信息。
                  code:
                    type: string
                    description: 状态码。
                  messages:
                    type: array
                    description: 消息列表。
                    items:
                      type: object
                      properties:
                        token_class:
                          type: string
                          description: Token 类。
                        token_type:
                          type: string
                          description: 令牌类型。
                        message:
                          type: string
                          description: 包含补充信息的消息。
                x-examples:
                  Example 1:
                    detail: Given token not valid for any token type
                    code: token_not_valid
                    messages:
                      - token_class: AccessToken
                        token_type: access
                        message: Token is invalid or expired
              examples:
                401 - Token is invalid or expired:
                  value:
                    detail: Given token not valid for any token type
                    code: token_not_valid
                    messages:
                      - token_class: AccessToken
                        token_type: access
                        message: Token is invalid or expired
        '404':
          description: 未找到
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: object
                    title: 状态
                    description: 操作状态。
                    properties:
                      code:
                        type: string
                        description: '[状态码](/zh/reference/transaction-status-error-codes)。'
                      description:
                        type: string
                        description: 状态描述。
                      detail:
                        type: string
                        description: 更多状态信息。
                x-examples:
                  Example 1:
                    status:
                      code: '404'
                      description: ERROR
                      detail: Payin not found
              examples:
                404 - Payin not found.:
                  value:
                    status:
                      code: '404'
                      description: ERROR
                      detail: Payin not found
      security:
        - token: []
      servers:
        - url: https://api.stage.localpayment.com
          description: Stage
components:
  securitySchemes:
    token:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.