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

# Recupera el estado de un pago

> Recupera el estado actual y los detalles completos de cualquier pago usando su paymentCode o su UUID de pago interno.

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 `GET /payment/inquiry/{id}` para recuperar el estado actual y los detalles de cualquier pago. Pasa el `paymentCode` que Therius devolvió cuando se creó el pago (p. ej. `PC-1234567890`) o el UUID de pago interno. Este endpoint es útil para sondear pagos pendientes, conciliación y depuración.

<SchemaLangNote lang="es" />

<Note>
  A diferencia de las respuestas de pago/suscripción del resto de esta API, `amount` aquí es un entero plano en las unidades menores de la moneda, con un campo `currency` separado en el nivel superior — no un objeto `{ currency, value, exponent }`.
</Note>

### Buscar un pago rechazado

```bash theme={"dark"}
curl https://api.therius.io/v1/payment/inquiry/PC-9876543210 \
  -H "Authorization: Bearer prv_production_your_key_here"
```

```json theme={"dark"}
{
  "id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "status": "declined",
  "paymentCode": "PC-9876543210",
  "orderCode": "ORDER-20240101-003",
  "amount": { "currency": "USD", "value": 2500, "exponent": 2 },
  "currency": "USD",
  "merchantId": "MERCHANT_001",
  "refusalCode": {
    "reason": "Do not honor",
    "reasonCode": "DO_NOT_HONOR",
    "recoveryAction": "switch_method"
  }
}
```

### Consultar el sandbox sin una clave de API

```bash theme={"dark"}
curl https://api-sandbox.therius.io/v1/payment/inquiry/PC-1234567890 \
  -H "X-Environment: sandbox"
```

<Note>
  Si no existe ningún pago para el `id` proporcionado, la API devuelve `404 Not Found`. Verifica el `paymentCode` o el UUID y asegúrate de estar consultando el entorno correcto (producción vs. sandbox).
</Note>

<Tip>
  Puedes usar este endpoint para sondear el estado final de pagos `pending_3ds` o `pending_action` si prefieres no usar webhooks. Sin embargo, los webhooks se recomiendan para producción — empujan el estado final a tu servidor tan pronto como está disponible, sin requerir sondeo.
</Tip>

<RequestExample>
  ```bash cURL theme={"dark"}
  curl https://api.therius.io/v1/payment/inquiry/PC-1234567890 \
    -H "Authorization: Bearer prv_production_your_key_here"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={"dark"}
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "captured",
    "paymentCode": "PC-1234567890",
    "orderCode": "ORDER-20240101-001",
    "amount": { "currency": "USD", "value": 4999, "exponent": 2 },
    "currency": "USD",
    "merchantId": "MERCHANT_001",
    "authorizationCode": "AUTH-789"
  }
  ```
</ResponseExample>


## OpenAPI

````yaml GET /payment/inquiry/{id}
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/inquiry/{id}:
    get:
      tags:
        - Payments
      summary: Retrieve payment status
      operationId: inquiryPayment
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: >-
            The `paymentCode` (e.g. `PC-1234567890`) or the internal payment
            UUID.
        - name: X-Environment
          in: header
          description: >-
            Set to `sandbox` to look up a sandbox payment without an API key
            (e.g. client-side status polling). Defaults to `production`.
          schema:
            type: string
            enum:
              - sandbox
              - production
      responses:
        '200':
          description: Payment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InquiryResponse'
components:
  schemas:
    InquiryResponse:
      type: object
      description: >-
        Current state of a payment. Note `amount` here is a flat integer in
        minor units with a separate `currency`, unlike the Amount object used
        elsewhere.
      properties:
        id:
          type: string
          description: Internal Therius payment UUID.
        merchantId:
          type: integer
          description: Your merchant account ID.
        orderCode:
          type: string
          description: Your original order reference.
        paymentCode:
          type: string
          description: Therius receipt ID.
        status:
          $ref: '#/components/schemas/PaymentStatus'
        amount:
          type: integer
          description: Payment amount in the currency minor units.
        currency:
          type: string
          description: ISO 4217 currency code.
        authorizationCode:
          type: string
          description: >-
            Issuer authorization code. Present on `authorized` and `captured`
            payments.
        refusalCode:
          $ref: '#/components/schemas/RefusalCode'
    PaymentStatus:
      type: string
      enum:
        - captured
        - authorized
        - declined
        - pending_3ds
        - pending_action
        - failed
        - cancelled
        - refunded
      description: >-
        `captured` - funds settled; `authorized` - funds reserved, call capture
        to settle; `declined` - issuer declined, see `refusalCode`;
        `pending_3ds` - a 3DS challenge is required, see `actionRequired`;
        `pending_action` - an external action (redirect, voucher) is required,
        see `actionRequired`; `failed` - processing error unrelated to the
        issuer; `cancelled` - authorization voided; `refunded` - captured funds
        returned.
    RefusalCode:
      type: object
      description: >-
        Present when `status` is `declined`. See the Declined Payments concept
        page for the full code table and how to react to each `recoveryAction`.
      properties:
        reason:
          type: string
          description: Human-readable meaning of `reasonCode`.
          example: Insufficient funds
        reasonCode:
          type: string
          description: >-
            Normalized ISO 8583 decline code. Every provider decline is mapped
            to this set, so handling logic is provider-independent. Full table
            with meanings on the Declined Payments concept page.
          example: '51'
          enum:
            - '1'
            - '2'
            - '3'
            - '4'
            - '5'
            - '6'
            - '7'
            - '8'
            - '9'
            - '11'
            - '12'
            - '13'
            - '14'
            - '15'
            - '16'
            - '17'
            - '19'
            - '20'
            - '21'
            - '22'
            - '25'
            - '28'
            - '30'
            - '41'
            - '43'
            - '46'
            - '51'
            - '52'
            - '53'
            - '54'
            - '55'
            - '57'
            - '58'
            - '59'
            - '61'
            - '62'
            - '63'
            - '65'
            - '68'
            - '75'
            - '76'
            - '77'
            - '78'
            - '80'
            - '81'
            - '82'
            - '83'
            - '85'
            - '91'
            - '92'
            - '93'
            - '94'
            - '95'
            - '96'
            - B1
            - N0
            - N3
            - N4
            - N7
            - P2
            - P5
            - P6
            - Q1
            - R0
            - R1
            - R3
            - XA
            - XD
            - Z3
        originalReason:
          type: string
          description: >-
            Raw message the underlying provider returned, before normalization.
            Diagnostic only — format is not stable across providers.
        originalReasonCode:
          type: string
          description: >-
            Raw code the underlying provider returned, before normalization.
            Diagnostic only — format varies by provider.
        recoveryAction:
          type: string
          description: >-
            What the checkout should do next: `retry` (transient/technical —
            same card may be retried once), `switch_method` (this card will not
            work — prompt for another method), `terminal` (hard block — do not
            retry or offer an alternative).
          enum:
            - retry
            - switch_method
            - terminal
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your secret API key: `Bearer prv_production_xxx` (production) or `Bearer
        prv_sandbox_xxx` (sandbox).

````