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

# Get Recovery Status by Transaction ID

> Poll the current status of a recovery attempt by its transaction ID.

The `transactionId` is the value returned from `/api/recovery/execute`.

The response includes the number of gateway attempts, the last decline code seen, and — when the recovery did not succeed — a recommended next action.

To look a recovery up by the `idempotencyKey` you supplied instead, use `GET /api/recovery/status?idempotencyKey=...`.

> Clients can only query their own transactions.




## OpenAPI

````yaml /api-reference/openapi.yaml get /api/recovery/status/{transactionId}
openapi: 3.0.3
info:
  title: Revtain API
  description: >
    Recover failed payments. No checkout changes. Works with your existing
    payment stack.


    ## Choose Your Path


    **Using Chargebee, Recurly, Stripe Billing, Braintree, Zuora, or Shopify
    (ReCharge)?**

    Use a Connector — paste one webhook URL, no code, 5 minutes.


    **Custom billing system or want full API control?**

    Use the Recovery Engine directly. The quickstart gets you to a working
    recovery call in 60 seconds.


    ## Authentication


    Pass your API key via the `X-API-KEY` header on all requests:


    ```

    X-API-KEY: rev_dTviCg52T8gLPCjrrW4KA0NKf_f5pQgk

    ```


    Keep this secret. Your API key can trigger charges. Never expose it in
    client-side code, public repos, or logs.


    ## Base URL


    ```

    https://api.revtain.com

    ```


    Same URL for testing and production. Test mode is controlled by your gateway
    type — onboard with a test gateway (e.g., Stripe `sk_test_...`) for sandbox,
    live key for production.
  version: 1.0.0
  contact:
    email: support@revtain.com
servers:
  - url: https://api.revtain.com
    description: Production & Sandbox (test mode controlled by gateway key)
security:
  - ApiKeyAuth: []
tags:
  - name: Recovery Engine
    description: Trigger and track payment recovery attempts
  - name: Predictive Risk Engine
    description: Pre-screen payments before they fail
  - name: Retention
    description: Hosted cancel flow to reduce voluntary churn
  - name: Health
    description: Service health check
paths:
  /api/recovery/status/{transactionId}:
    get:
      tags:
        - Recovery Engine
      summary: Get Recovery Status by Transaction ID
      description: >
        Poll the current status of a recovery attempt by its transaction ID.


        The `transactionId` is the value returned from `/api/recovery/execute`.


        The response includes the number of gateway attempts, the last decline
        code seen, and — when the recovery did not succeed — a recommended next
        action.


        To look a recovery up by the `idempotencyKey` you supplied instead, use
        `GET /api/recovery/status?idempotencyKey=...`.


        > Clients can only query their own transactions.
      operationId: getRecoveryStatus
      parameters:
        - name: transactionId
          in: path
          required: true
          description: The transaction ID returned from `/api/recovery/execute`.
          schema:
            type: string
          example: 01KKZ14FEZK152ZBXEM2XK1B0C
      responses:
        '200':
          description: Recovery status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecoveryStatusResponse'
              example:
                transactionId: 01KKZ14FEZK152ZBXEM2XK1B0C
                status: succeeded
                recovered: true
                amount: 5000
                currency: USD
                recoveredAt: '2026-03-17T23:15:21.000Z'
                strategyUsed: primary
                attemptCount: 1
                lastDeclineCode: do_not_honor
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Transaction not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
components:
  schemas:
    RecoveryStatusResponse:
      type: object
      properties:
        transactionId:
          type: string
          example: 01KKZ14FEZK152ZBXEM2XK1B0C
        status:
          type: string
          enum:
            - succeeded
            - failed
            - blocked
            - unknown
          example: succeeded
        recovered:
          type: boolean
          example: true
        amount:
          type: integer
          example: 5000
        currency:
          type: string
          example: USD
        recoveredAt:
          type: string
          format: date-time
          nullable: true
          example: '2026-03-17T23:15:21.000Z'
        strategyUsed:
          type: string
          example: primary
        attemptCount:
          type: integer
          description: Number of gateway attempts made during the cascade.
          example: 2
        lastDeclineCode:
          type: string
          nullable: true
          description: The most recent decline code seen for this recovery.
          example: do_not_honor
        recommendedAction:
          type: string
          enum:
            - request_card_update
            - retry_later
            - manual_review
            - monitor
          description: What to do next. Present only when the recovery did not succeed.
          example: retry_later
        recommendedActionReason:
          type: string
          description: >-
            Human-readable explanation of the recommended action. Present only
            when the recovery did not succeed.
          example: >-
            The issuer returned a soft decline. A later retry, or a card update,
            may succeed.
    UnauthorizedError:
      type: object
      properties:
        error:
          type: string
          example: Unauthorized. Missing or invalid API key.
    NotFoundError:
      type: object
      properties:
        error:
          type: string
          example: Transaction not found.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: 'Your Revtain API key (format: `rev_xxx`). Provided during onboarding.'

````