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

# Emita um reembolso total ou parcial

> Reembolse um pagamento capturado total ou parcialmente. Vários reembolsos parciais são permitidos até o valor total capturado.

export const SchemaLangNote = ({lang}) => {
  const text = ({
    es: "Los nombres de campos y el esquema de solicitud/respuesta que se muestran a continuación están en inglés — se generan a partir de la especificación OpenAPI. El texto explicativo de esta página está traducido.",
    pt: "Os nomes dos campos e o esquema de requisição/resposta exibidos abaixo estão em inglês — são gerados a partir da especificação OpenAPI. O texto explicativo desta página está traduzido."
  })[lang] || "Field names and the request/response schema shown below are in English — they are generated from the OpenAPI specification.";
  return <Note>{text}</Note>;
};

Use `POST /payment/{id}/refund` para devolver fundos a um titular de cartão depois que um pagamento foi capturado e liquidado. Você pode emitir um único reembolso total ou vários reembolsos parciais — desde que o valor cumulativo reembolsado não exceda o total capturado originalmente. Os reembolsos costumam aparecer no extrato do titular do cartão dentro de 5–10 dias úteis, conforme o banco dele.

<SchemaLangNote lang="pt" />

## Identificar o pagamento

`{id}` é o `id` de pagamento do Therius devolvido por `POST /payment/authorization` e `POST /payment/purchase`. `orderCode` e `paymentCode` são os seus próprios campos de referência e **não** são aceitos aqui. Um `id` desconhecido ou não pertencente devolve `404`.

## Exemplos

### Reembolso total

<RequestExample>
  ```bash cURL theme={"dark"}
  curl -X POST https://api.therius.io/v1/payment/9f8b2c1e-4d5a-6b7c-8d9e-0f1a2b3c4d5e/refund \
    -H "Authorization: Bearer prv_production_your_key_here" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{
      "merchantCode": "MERCHANT_001",
      "amount": { "currency": "USD", "value": 4999, "exponent": 2 }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={"dark"}
  {
    "id": "9f8b2c1e-4d5a-6b7c-8d9e-0f1a2b3c4d5e",
    "status": "refunded",
    "paymentCode": "PC-1234567890",
    "orderCode": "ORDER-20240101-001",
    "merchantCode": "MERCHANT_001",
    "amount": { "currency": "USD", "value": 4999, "exponent": 2 }
  }
  ```
</ResponseExample>

### Reembolso parcial

Reembolsar apenas parte de um pedido — por exemplo, um único item devolvido de uma compra com vários itens:

```bash theme={"dark"}
curl -X POST https://api.therius.io/v1/payment/9f8b2c1e-4d5a-6b7c-8d9e-0f1a2b3c4d5e/refund \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "reference": "RETURN-98765",
    "amount": { "currency": "USD", "value": 1999, "exponent": 2 }
  }'
```

```json theme={"dark"}
{
  "id": "9f8b2c1e-4d5a-6b7c-8d9e-0f1a2b3c4d5e",
  "status": "refunded",
  "paymentCode": "PC-1234567890",
  "orderCode": "ORDER-20240101-001",
  "merchantCode": "MERCHANT_001",
  "amount": { "currency": "USD", "value": 1999, "exponent": 2 }
}
```

<Warning>
  Você não pode reembolsar um pagamento que está no estado `authorized` (ainda não capturado). Para liberar uma autorização que não foi capturada, use [Cancel](/api-reference/cancel) em vez disso. Tentar reembolsar um pagamento não capturado devolve um erro.
</Warning>

<Note>
  Vários reembolsos parciais são permitidos. Você pode chamar este endpoint várias vezes contra o mesmo `id` de pagamento, desde que o valor cumulativo de reembolso não exceda o valor capturado original. Cada chamada deve usar um `Idempotency-Key` distinto.
</Note>

<Tip>
  Se você não tem certeza se um pagamento está no estado `authorized` ou `captured`, use [Cancel or Refund](/api-reference/cancel-or-refund) em vez disso — ele detecta o estado automaticamente e toma a ação apropriada.
</Tip>


## OpenAPI

````yaml POST /payment/{id}/refund
openapi: 3.1.0
info:
  title: Therius API
  description: REST API for payments, subscriptions, and billing plans.
  version: 1.0.0
servers:
  - url: https://api.therius.io/v1
    description: Production
  - url: https://api-sandbox.therius.io/v1
    description: Sandbox
security:
  - bearerAuth: []
paths:
  /payment/{id}/refund:
    post:
      tags:
        - Payments
      summary: Issue a full or partial refund
      operationId: refundPayment
      parameters:
        - $ref: '#/components/parameters/PaymentId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - merchantCode
                - amount
              properties:
                merchantCode:
                  type: string
                  description: >-
                    Your merchant account identifier. Validated against the
                    Bearer key's merchant; required if the key maps to more than
                    one merchant account.
                amount:
                  $ref: '#/components/schemas/Amount'
                reference:
                  type: string
                  description: Optional internal reference for this refund operation.
      responses:
        '200':
          description: Refund result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModificationResponse'
components:
  parameters:
    PaymentId:
      name: id
      in: path
      required: true
      description: >-
        The Therius payment `id` returned by `POST /payment/authorization` or
        `POST /payment/purchase`.
      schema:
        type: string
        format: uuid
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      description: >-
        A UUID you generate per operation. Required in production. Retrying with
        the same key returns the original response.
      schema:
        type: string
        format: uuid
  schemas:
    Amount:
      type: object
      required:
        - currency
        - value
        - exponent
      properties:
        currency:
          type: string
          description: >-
            ISO 4217 currency code. On capture, refund and cancel it must match
            the currency of the original payment.
          example: USD
        value:
          type: integer
          description: >-
            Amount in minor units (cents, pence, etc.). `4999` = $49.99 for USD
            (exponent 2); `5000` = ¥5000 for JPY (exponent 0). On capture it
            must not exceed the authorized value; on refund the cumulative total
            across refunds must not exceed the captured amount.
          example: 4999
        exponent:
          type: integer
          description: >-
            Number of decimal places for the currency — `2` for USD/EUR, `0` for
            JPY. Determines where the decimal point sits in `value`.
          example: 2
    ModificationResponse:
      type: object
      description: Result of a capture, refund, cancel or cancel_or_refund.
      properties:
        id:
          type: string
          description: The Therius payment `id`.
        merchantCode:
          type: string
        orderCode:
          type: string
        paymentCode:
          type: string
          description: Therius receipt ID.
        amount:
          $ref: '#/components/schemas/Amount'
        status:
          type: string
          enum:
            - captured
            - refunded
            - cancelled
            - failed
          description: Outcome of the operation.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your secret API key: `Bearer prv_production_xxx` (production) or `Bearer
        prv_sandbox_xxx` (sandbox).

````