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

# Get Payment Result

> Retrieve transaction status, card identity, and payment credentials for a session

A polling endpoint: after the cardholder completes card entry and passkey approval on Prava's secure surface, poll it to read the outcome and, for non-quote checkouts, the single-use credentials.

`GET /v1/sessions/{sessionId}/payment-result` · Authenticated with your secret key.

## Path parameters

**sessionId** `string` *required*

The session id from [Create Session](https://docs.prava.space/api-reference/create-session.md).

## Response

**session\_id** `string`

**order\_id** `string | null`

**status** `string`

Overall session status: `pending`, `processing`, `awaiting_result`, `completed`, or `failed`. `processing` means authentication or tokenization is in flight, or a quote-backed merchant checkout is not yet terminal.

**transactions** `object[]`

**transaction properties**

**txn\_id** `string`

**card\_id** `string | null`

The card bound to this transaction—the source of truth whether it was preselected or selected or entered on the collection surface. `null` when no card is bound.

**status** `string`

`initiated` | `awaiting_result` | `completed` | `failed`.

**line\_items** `object[]`

Omitted from credential-free quote-backed results.

**line\_item properties**

**txn\_ref\_id** `string`

Line-item reference — pass this to [Report Status](https://docs.prava.space/api-reference/report-status.md).

**merchant\_name** `string | null`

**merchant\_url** `string | null`

**total\_amount** `string`

**status** `string`

`pending` | `credentials_generated` | `completed` | `failed`.

**token** `string | null`

Virtual card number (network token) your agent uses at checkout. Non-null after credentials are generated.

**dynamic\_cvv** `string | null`

Single-use CVV. Non-null after credentials are generated.

**expiry\_month** `string | null`

**expiry\_year** `string | null`

**products** `object[]`

**product properties**

**product\_ref\_id** `string`

**external\_product\_id** `string | null`

**name** `string`

**unit\_price** `string`

**quantity** `number`

**error** `object`

Present only when the transaction failed: `{ code, message }`.

**merchant\_res** `object`

Present for quote-backed sessions when merchant lifecycle data exists. Omitted for non-quote
checkouts and sessions without that data. This projection contains only a normalized status
and an optional merchant order ID.

**merchant\_res properties**

**status** `string`

`pending` | `quote_ready` | `prepared` | `prepare_failed` | `paid` | `failed` | `needs_human` | `unknown`. An effective completed result maps to `paid`, including successful sandbox simulation.

**orderId** `string`

Optional merchant order ID, distinct from Prava's top-level `order_id`. Returned only when it meets the bounded identifier format.

**observed\_result** `object`

Present for an explicitly simulated sandbox session once an eligible terminal payment outcome
is observed. Omitted for ordinary results and outcomes that cannot be simulated.

**observed\_result properties**

**stage** `string`

Always `payment`.

**status** `string`

The actual observed outcome: `completed` or `failed`.

**error** `object`

Present when the observed payment failed: canonical `{ code, message }`.

**error** `object`

Present for a terminal quote-backed failure: `{ code, message }`. Confirmed payment failures use canonical codes such as `CARD_DECLINED`, `INSUFFICIENT_FUNDS`, or the fallback `PAYMENT_FAILED`. See [Errors](https://docs.prava.space/api-reference/errors.md).

## Notes

* For non-quote checkouts, `token` and `dynamic_cvv` contain the virtual card credentials your agent uses at checkout.
* Read `transactions[].card_id` as the source of truth for the card bound to the transaction, whether it was preselected or chosen on the collection surface.
* For quote-backed checkouts, Prava performs the merchant checkout. Results contain credential-free transaction summaries (`txn_id`, `card_id`, and `status`); they never include token, CVV, expiry, or line-item credentials.
* `merchant_res` contains only `status` and optional `orderId`. Read canonical failure details from the top-level `error`. Keep polling while the top-level status is `pending` or `processing`.
* [Sandbox simulation](https://docs.prava.space/api-reference/testing.md#simulate-successful-payment-completion) can return effective `completed` and `merchant_res.status: "paid"` while `observed_result.status` is `failed`. Those effective statuses are returned only after Core's sandbox completion succeeds; they do not establish merchant settlement. The simulation request is supplied at session creation and is not echoed as a response-side `sandbox_simulation` object.
* Responses use `Cache-Control: no-store`.
* Prava performs a lazy mandate expiry check on every request — expired mandates are reflected in the status.
* After using non-quote checkout credentials, report the outcome via [Report Status](https://docs.prava.space/api-reference/report-status.md).

## Error responses

| Status | Code | Cause |
| - | - | - |
| 401 | `AUTH_1001` | Invalid API key |
| 401 | `AUTH_1002` | Missing or invalid Authorization header |
| 404 | `NOT_FOUND` | Session not found or doesn't belong to your merchant account |

```bash cURL theme={null}
curl "https://sandbox.api.prava.space/v1/sessions/ses_123/payment-result" \
  -H "Authorization: Bearer sk_test_..."
```

```python Python theme={null}
import requests

resp = requests.get(
    "https://sandbox.api.prava.space/v1/sessions/ses_123/payment-result",
    headers={"Authorization": "Bearer sk_test_..."},
)
```

```javascript JavaScript theme={null}
const resp = await fetch("https://sandbox.api.prava.space/v1/sessions/ses_123/payment-result", {
  headers: {
    Authorization: "Bearer sk_test_...",
  },
});
```

```json 200 Success theme={null}
{
  "session_id": "ses_123",
  "order_id": "ord_4a1b",
  "status": "awaiting_result",
  "transactions": [
    {
      "txn_id": "txn_1",
      "card_id": "card_42",
      "status": "awaiting_result",
      "line_items": [
        {
          "txn_ref_id": "tli_1",
          "merchant_name": "Acme Store",
          "total_amount": "49.99",
          "status": "credentials_generated",
          "token": "4111111111111111",
          "dynamic_cvv": "123",
          "expiry_month": "12",
          "expiry_year": "2030",
          "products": []
        }
      ]
    }
  ]
}
```

```json 200 Quote-backed theme={null}
{
  "session_id": "ses_123",
  "order_id": "ord_4a1b",
  "status": "processing",
  "transactions": [
    {
      "txn_id": "txn_1",
      "card_id": "card_42",
      "status": "awaiting_result"
    }
  ],
  "merchant_res": { "status": "prepared" }
}
```

```json 200 Quote payment completed theme={null}
{
  "session_id": "ses_123",
  "order_id": "ord_4a1b",
  "status": "completed",
  "transactions": [
    {
      "txn_id": "txn_1",
      "card_id": "card_42",
      "status": "awaiting_result"
    }
  ],
  "merchant_res": {
    "status": "paid",
    "orderId": "merchant_order_123"
  }
}
```

```json 200 Quote payment failed theme={null}
{
  "session_id": "ses_123",
  "order_id": "ord_4a1b",
  "status": "failed",
  "transactions": [
    {
      "txn_id": "txn_1",
      "card_id": "card_42",
      "status": "awaiting_result"
    }
  ],
  "merchant_res": { "status": "failed" },
  "error": {
    "code": "CARD_DECLINED",
    "message": "The payment was declined by the card issuer."
  }
}
```

```json 401 Unauthorized theme={null}
{
  "error": { "code": "AUTH_1002", "message": "Missing or invalid Authorization header" }
}
```

```json 404 Not Found theme={null}
{
  "error": { "code": "NOT_FOUND", "message": "Session not found" }
}
```


## OpenAPI

````yaml api-reference/openapi.json GET /v1/sessions/{sessionId}/payment-result
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}/payment-result:
    get:
      summary: Get Payment Result
      description: >-
        Retrieve transaction status, card identity, and payment credentials for
        a session. Quote-backed results use top-level status and canonical
        errors, include normalized merchant_res when lifecycle data exists, and
        never return credentials. Responses use Cache-Control: no-store.
        Existing recognized transaction error.code values are preserved and
        reused unchanged by the corresponding webhook, including previously
        exposed network-named codes. Renaming requires a versioned API release.
        Messages use safe local copy and unknown codes fall back to
        PAYMENT_FAILED. Shopper and unverified legacy reports cannot attest
        issuer declines. See /webhooks/errors#result-api-compatibility.
      operationId: getPaymentResult
      parameters:
        - name: sessionId
          in: path
          required: true
          description: The session ID returned from Create Session
          schema:
            type: string
      responses:
        '200':
          description: Payment result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResult'
        '401':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
components:
  schemas:
    PaymentResult:
      type: object
      required:
        - session_id
        - order_id
        - status
        - transactions
      properties:
        session_id:
          type: string
        order_id:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - pending
            - processing
            - awaiting_result
            - completed
            - failed
          description: >-
            Overall session status. `processing` means the payment operation is
            still in flight: a non-quote checkout is authenticating or
            tokenizing, or a quote-backed merchant checkout has not reached a
            terminal outcome.
        transactions:
          type: array
          items:
            type: object
            required:
              - txn_id
              - card_id
              - status
            properties:
              txn_id:
                type: string
              card_id:
                type:
                  - string
                  - 'null'
                description: >-
                  The card bound to this transaction and the source of truth
                  whether it was preselected or selected or entered on the
                  collection surface. Null when no card is bound.
              status:
                type: string
                enum:
                  - initiated
                  - awaiting_result
                  - completed
                  - failed
              line_items:
                type: array
                description: >-
                  Credential-bearing line items for non-quote checkouts. Omitted
                  from quote-backed results.
                items:
                  type: object
                  properties:
                    txn_ref_id:
                      type: string
                      description: >-
                        Transaction line item reference ID (used in Report
                        Status)
                    merchant_name:
                      type:
                        - string
                        - 'null'
                    merchant_url:
                      type:
                        - string
                        - 'null'
                    total_amount:
                      type: string
                    status:
                      type: string
                      enum:
                        - pending
                        - credentials_generated
                        - completed
                        - failed
                    token:
                      type:
                        - string
                        - 'null'
                      description: >-
                        Virtual card number (network token). Non-null after
                        credentials are generated.
                    dynamic_cvv:
                      type:
                        - string
                        - 'null'
                      description: >-
                        Single-use CVV. Non-null after credentials are
                        generated.
                    expiry_month:
                      type:
                        - string
                        - 'null'
                    expiry_year:
                      type:
                        - string
                        - 'null'
                    products:
                      type: array
                      items:
                        type: object
                        properties:
                          product_ref_id:
                            type: string
                          external_product_id:
                            type:
                              - string
                              - 'null'
                          name:
                            type: string
                          unit_price:
                            type: string
                          quantity:
                            type: number
              error:
                type: object
                description: Present only when the transaction has failed
                properties:
                  code:
                    type: string
                  message:
                    type: string
        error:
          type: object
          description: >-
            Terminal quote-backed failure: a canonical payment error (including
            the PAYMENT_FAILED fallback), MERCHANT_PREPARE_FAILED, or
            MERCHANT_ACTION_REQUIRED. Read this with the top-level status;
            merchant_res contains only lifecycle status and optional orderId.
          properties:
            code:
              type: string
            message:
              type: string
        observed_result:
          description: >-
            Actual terminal payment outcome for an explicitly simulated sandbox
            session. Omitted for ordinary results and outcomes that cannot be
            simulated. Effective top-level completed can coexist with an
            observed failed payment.
          oneOf:
            - type: object
              required:
                - stage
                - status
              properties:
                stage:
                  type: string
                  const: payment
                status:
                  type: string
                  const: completed
            - type: object
              required:
                - stage
                - status
                - error
              properties:
                stage:
                  type: string
                  const: payment
                status:
                  type: string
                  const: failed
                error:
                  type: object
                  required:
                    - code
                    - message
                  properties:
                    code:
                      type: string
                      enum:
                        - CARD_DECLINED
                        - INSUFFICIENT_FUNDS
                        - INVALID_CARD_NUMBER
                        - INVALID_SECURITY_CODE
                        - INVALID_EXPIRY_DATE
                        - EXPIRED_CARD
                        - BILLING_DETAILS_MISMATCH
                        - CARD_NOT_SUPPORTED
                        - PAYMENT_METHOD_UNAVAILABLE
                        - AUTHENTICATION_FAILED
                        - PAYMENT_FAILED
                    message:
                      type: string
                      description: Canonical safe payment error message.
        merchant_res:
          type: object
          additionalProperties: false
          required:
            - status
          description: >-
            Present for quote-backed sessions when merchant lifecycle data
            exists; omitted for non-quote results and absent lifecycle data.
            Narrow credential-free projection. Effective completed results map
            to paid, including successful sandbox simulation; observed_result
            retains the actual simulated-session outcome.
          properties:
            status:
              type: string
              enum:
                - pending
                - quote_ready
                - prepared
                - prepare_failed
                - paid
                - failed
                - needs_human
                - unknown
            orderId:
              type: string
              minLength: 1
              maxLength: 200
              pattern: ^[A-Za-z0-9._:/-]{1,200}$
              description: >-
                Optional merchant order identifier, distinct from Prava
                order_id. Omitted when missing or outside the bounded identifier
                format.
    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
      headers:
        X-Response-ID:
          $ref: '#/components/headers/XResponseId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  headers:
    XResponseId:
      description: >-
        UUID correlation identifier for this response. Include it when
        contacting Prava support.
      schema:
        type: string
        format: uuid
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your secret key: sk_test_* (sandbox) or sk_live_* (production).'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.