> ## 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.

# Emite un reembolso total o parcial

> Reembolsa un pago capturado en su totalidad o parcialmente. Se permiten varios reembolsos parciales hasta el monto 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>;
};

Usa `POST /payment/{id}/refund` para devolver fondos a un titular de tarjeta después de que un pago ha sido capturado y liquidado. Puedes emitir un solo reembolso total o varios reembolsos parciales — siempre que el monto acumulado reembolsado no exceda el total capturado originalmente. Los reembolsos suelen aparecer en el estado de cuenta del titular de la tarjeta dentro de 5–10 días hábiles, según su banco.

<SchemaLangNote lang="es" />

## Identificar el pago

`{id}` es el `id` de pago de Therius devuelto por `POST /payment/authorization` y `POST /payment/purchase`. `orderCode` y `paymentCode` son tus propios campos de referencia y **no** se aceptan aquí. Un `id` desconocido o no propio devuelve `404`.

## Ejemplos

### 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 solo parte de un pedido — por ejemplo, un solo artículo devuelto de una compra de varios artículos:

```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>
  No puedes reembolsar un pago que está en el estado `authorized` (aún no capturado). Para liberar una autorización que no se ha capturado, usa [Cancel](/api-reference/cancel) en su lugar. Intentar reembolsar un pago no capturado devuelve un error.
</Warning>

<Note>
  Se permiten varios reembolsos parciales. Puedes llamar a este endpoint varias veces contra el mismo `id` de pago, siempre que el monto acumulado de reembolso no exceda el monto capturado original. Cada llamada debe usar un `Idempotency-Key` distinto.
</Note>

<Tip>
  Si no estás seguro de si un pago está en el estado `authorized` o `captured`, usa [Cancel or Refund](/api-reference/cancel-or-refund) en su lugar — detecta el estado automáticamente y toma la acción apropiada.
</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).

````