> ## 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.
# Revierte un pago
> Cancela automáticamente si el pago está autorizado, o reembolsa si ya está capturado. Sin necesidad de rastrear el estado del pago.
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 {text};
};
Si no quieres rastrear en tu propio sistema si un pago está en el estado `authorized` o `captured`, `POST /payment/{id}/cancel_or_refund` lo maneja por ti. Therius verifica el estado actual del pago y automáticamente cancela la autorización (si no está capturada) o emite un reembolso total (si ya está capturada). Esto es especialmente útil en flujos de reversión de pedidos donde el estado del pago puede variar según el momento — por ejemplo, un cliente que cancela un pedido mientras el cumplimiento está en curso.
## 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`.
Este endpoint siempre revierte el pago **completo** — anula toda la retención de autorización, o reembolsa todo el monto capturado. Para emitir un reembolso *parcial* en un pago capturado, llama a [Refund](/api-reference/refund) con un `amount` en su lugar.
## Ejemplo
### Revertir un pago sin conocer su estado
```bash cURL theme={"dark"}
curl -X POST https://api.therius.io/v1/payment/9f8b2c1e-4d5a-6b7c-8d9e-0f1a2b3c4d5e/cancel_or_refund \
-H "Authorization: Bearer prv_production_your_key_here" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"merchantCode": "MERCHANT_001"
}'
```
```json 200 OK theme={"dark"}
{
"id": "9f8b2c1e-4d5a-6b7c-8d9e-0f1a2b3c4d5e",
"status": "cancelled",
"paymentCode": "PC-1234567890",
"orderCode": "ORDER-20240101-002",
"merchantCode": "MERCHANT_001",
"amount": { "currency": "USD", "value": 9900, "exponent": 2 }
}
```
**Respuesta cuando el pago estaba capturado (ruta de reembolso) — `200 OK`**
```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": 4999, "exponent": 2 }
}
```
Este endpoint es ideal para flujos de reversión de pedidos disparados por tu UI de cancelación de cara al cliente, donde la misma ruta de código maneja tanto los estados previos a la captura como los posteriores. Usa el `status` en la respuesta para determinar qué acción se tomó y actualiza tus registros internos en consecuencia.
## OpenAPI
````yaml POST /payment/{id}/cancel_or_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}/cancel_or_refund:
post:
tags:
- Payments
summary: Reverse a payment
operationId: cancelOrRefundPayment
parameters:
- $ref: '#/components/parameters/PaymentId'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- merchantCode
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.
reference:
type: string
description: Optional internal reference for this operation.
responses:
'200':
description: Reverse 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:
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.
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
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Your secret API key: `Bearer prv_production_xxx` (production) or `Bearer
prv_sandbox_xxx` (sandbox).
````