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

# Predict Transaction Risk

> Predicts the risk score for a transaction before executing it. Use this to pre-screen payments and decide whether to proceed, delay, or block.

### Recommendation Values

| Value | Meaning |
|-------|---------|
| `proceed` | Low risk, charge normally |
| `proceed_with_caution` | Moderate risk, monitor closely |
| `delay` | High risk, consider delaying the charge |
| `block` | Very high risk, do not charge |




## OpenAPI

````yaml /api-reference/openapi.yaml post /api/predict/risk
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/predict/risk:
    post:
      tags:
        - Predictive Risk Engine
      summary: Predict Transaction Risk
      description: >
        Predicts the risk score for a transaction before executing it. Use this
        to pre-screen payments and decide whether to proceed, delay, or block.


        ### Recommendation Values


        | Value | Meaning |

        |-------|---------|

        | `proceed` | Low risk, charge normally |

        | `proceed_with_caution` | Moderate risk, monitor closely |

        | `delay` | High risk, consider delaying the charge |

        | `block` | Very high risk, do not charge |
      operationId: predictRisk
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PredictRiskRequest'
            example:
              paymentMethodToken: pm_1234567890
              amount: 5000
              currency: USD
      responses:
        '200':
          description: Risk prediction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PredictRiskResponse'
              example:
                success: true
                prediction:
                  riskScore: 72.5
                  confidence: 68
                  reasoning: >-
                    Card has 3 prior declines in last 30 days. Amount matches a
                    historically recoverable pattern.
                  factors:
                    - prior_decline_history
                    - amount_pattern_match
                    - time_of_day_risk
                  recommendation: proceed_with_caution
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
components:
  schemas:
    PredictRiskRequest:
      type: object
      required:
        - paymentMethodToken
        - amount
      properties:
        paymentMethodToken:
          type: string
          description: >-
            Your gateway's payment token. Format varies per gateway — see
            [Supported Gateways](/concepts/supported-gateways) for the
            per-gateway format table covering all 13 supported processors.
          example: pm_1234567890
        amount:
          type: integer
          description: Amount in cents.
          example: 5000
        currency:
          type: string
          default: USD
          example: USD
        scheduledDate:
          type: string
          format: date-time
          description: >-
            ISO 8601 date for scheduled transactions. Improves prediction
            accuracy.
          example: '2026-04-15T10:00:00.000Z'
    PredictRiskResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        prediction:
          type: object
          properties:
            riskScore:
              type: number
              example: 72.5
            confidence:
              type: integer
              example: 68
            reasoning:
              type: string
              example: >-
                Card has 3 prior declines in last 30 days. Amount matches a
                historically recoverable pattern.
            factors:
              type: array
              items:
                type: string
              example:
                - prior_decline_history
                - amount_pattern_match
                - time_of_day_risk
            recommendation:
              type: string
              enum:
                - proceed
                - proceed_with_caution
                - delay
                - block
              example: proceed_with_caution
    ValidationError:
      type: object
      properties:
        error:
          type: string
          example: Validation failed.
        details:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          example:
            paymentMethodToken:
              - Payment method token is required
            amount:
              - Amount must be a positive number
    UnauthorizedError:
      type: object
      properties:
        error:
          type: string
          example: Unauthorized. Missing or invalid API key.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: 'Your Revtain API key (format: `rev_xxx`). Provided during onboarding.'

````