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

# Report Status

> Report payment execution outcome back to Prava

<Note>
  **Always report status** after checkout execution: this updates transaction records and relays the
  outcome to the card network. Report `DECLINED` if a payment token was used but checkout failed.
</Note>

## Notes

* A mandate is the spending permission created when the cardholder approved the payment. Mandates are
  currently **one-time**: an `APPROVED` status automatically consumes the mandate (it can't be reused).
  Recurring mandate frequencies are planned; once available, `APPROVED` will keep a recurring mandate
  active for future invocations.
* `product_statuses` is optional and informational; the overall mandate status follows `txn_status`.

## Error responses

| Status | Code                       | Cause                                             | Resolution                                      |
| ------ | -------------------------- | ------------------------------------------------- | ----------------------------------------------- |
| 401    | `AUTH_1001`                | Invalid API key                                   | Check your secret key                           |
| 401    | `AUTH_1002`                | Missing or invalid Authorization header           | Include `Authorization: Bearer sk_xxx`          |
| 404    | `NOT_FOUND`                | Session / order / transaction reference not found | Verify the session ID and `txn_ref_id`          |
| 400    | `INVALID_STATE`            | No transaction awaiting payment result            | May already be reported, or not yet ready       |
| 400    | `MANDATE_EXPIRED`          | Mandate has expired                               | Register a new intent                           |
| 400    | `PRODUCT_NOT_FOUND`        | Product not found by the given ID                 | Verify `product_id` or `product_ref_id`         |
| 502    | `VISA_CONFIRMATION_FAILED` | Card network confirmation failed                  | Retry or contact support                        |
| 500    | `REPORT_STATUS_ERROR`      | Internal error                                    | Contact support with the `X-Response-ID` header |


## OpenAPI

````yaml api-reference/openapi.json POST /v1/sessions/{sessionId}/report-status
openapi: 3.1.0
info:
  title: Prava Payments API
  description: >-
    Server-side REST API for Prava Payments. All requests are authenticated with
    your secret key (sk_test_* in sandbox, sk_live_* in production).
  version: 1.0.0
servers:
  - url: https://sandbox.api.prava.space
    description: Sandbox
  - url: https://api.prava.space
    description: Production
security:
  - bearerAuth: []
paths:
  /v1/sessions/{sessionId}/report-status:
    post:
      summary: Report Status
      description: >-
        Report payment execution outcome back to Prava. Always report status
        after checkout execution.
      operationId: reportStatus
      parameters:
        - name: sessionId
          in: path
          required: true
          description: The session ID returned from Create Session
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportStatusRequest'
      responses:
        '200':
          description: Status confirmed
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Always "confirmed"
                  txn_ref_id:
                    type: string
                  txn_status:
                    type: string
                    enum:
                      - APPROVED
                      - DECLINED
                  visa_confirmation:
                    type: string
                    enum:
                      - SUCCESS
                      - FAILURE
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
        '502':
          $ref: '#/components/responses/Error'
components:
  schemas:
    ReportStatusRequest:
      type: object
      required:
        - txn_ref_id
        - txn_status
      properties:
        txn_ref_id:
          type: string
          description: The transaction line item reference ID (from Get Payment Result)
        txn_status:
          type: string
          enum:
            - APPROVED
            - DECLINED
          description: The payment outcome
        txn_type:
          type: string
          default: PURCHASE
          description: Transaction type
        authorization_code:
          type: string
          maxLength: 128
          description: Authorization code from the merchant's payment processor
        response_code:
          type: string
          maxLength: 2
          description: Processor response code, e.g. "00" for approved
        amount_paid:
          type: string
          description: Override the total amount paid, if different from the original
        product_statuses:
          type: array
          description: Optional per-product status overrides
          items:
            type: object
            required:
              - status
            properties:
              product_id:
                type: string
                maxLength: 50
                description: >-
                  Your external product ID. Either product_id or product_ref_id
                  must be provided.
              product_ref_id:
                type: string
                maxLength: 50
                description: >-
                  Prava's internal product reference ID. Either product_id or
                  product_ref_id must be provided.
              status:
                type: string
                enum:
                  - COMPLETED
                  - FAILED
                  - CANCELED
                  - INPROGRESS
                  - PENDING
                  - ONHOLD
                description: Product-level status
              amount_paid:
                type: string
                description: Amount paid for this specific product
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code (e.g. VAL_2001, AUTH_1001)
            message:
              type: string
              description: Human-readable error message
            details:
              type: object
              description: >-
                Optional — included for validation errors to specify which
                fields failed
  responses:
    Error:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your secret key: sk_test_* (sandbox) or sk_live_* (production).'

````