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

# API Reference

> Server-side REST API for Prava Payments

*Not sure this is the right path? See [Choosing Your Integration](https://docs.prava.space/choosing-your-integration.md).*

## Overview

The Prava REST API is used for server-side operations: creating sessions, managing cards, retrieving payment results, and reporting status. All server-side requests are authenticated using your **secret key**.

> [!WARNING]
>
> Never expose your secret key in client-side code, version control, or logs. Use it only in server-to-server requests.

## Base URLs

| Environment | Base URL | Key Prefix |
| - | - | - |
| **Sandbox** | `https://sandbox.api.prava.space` | `sk_test_*` |
| **Production** | `https://api.prava.space` | `sk_live_*` |

> [!TIP]
>
> Use the **sandbox** URL with your `sk_test_*` key during development. Switch to the **production** URL with `sk_live_*` when you're ready to go live.

> [!NOTE]
>
> These are the only **API** hosts. [dashboard.prava.space](https://dashboard.prava.space) (developer
> console) and [pay.prava.space](https://pay.prava.space) (agent-owner wallet) are web UIs; never send
> API requests to them.

## Authentication

All API requests require a Bearer token using your secret key:

```bash theme={null}
Authorization: Bearer sk_test_xxx
```

## Response Format

All requests and responses are JSON. Monetary amounts are always decimal strings (e.g. `"49.99"`), never numbers. Every response includes an `X-Response-ID` header for debugging:

```
X-Response-ID: 8b74ce32-4682-4b17-b51f-d57808f99061
```

Include this ID when contacting support to help trace issues.

## Error Response Format

All errors follow a consistent structure:

```json theme={null}
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  }
}
```

The `details` field is optional and included for validation errors to specify which fields failed.

### Common Error Codes

| Status | Code | Description |
| - | - | - |
| 401 | `AUTH_1001` | Invalid API key |
| 400 | `VAL_2001` | Validation error (check `details` for specifics) |
| 404 | `NOT_FOUND` | Requested resource not found |
| 400 | `INVALID_STATE` | Operation not allowed in current state |

The full catalog (every code, per endpoint, with recovery steps) is on the
[Errors](https://docs.prava.space/api-reference/errors.md) page.

## The payment journey

A non-quote payment is **three API calls and one non-API step**. Quote-backed checkouts use the same
session and polling endpoints, but Prava completes the merchant checkout for you:

**1. Create a session — POST /v1/sessions**

Your backend pins the order: customer, merchant, amount, line items. Returns `session_token` and
`iframe_url`. → [Create Session](https://docs.prava.space/api-reference/create-session.md)

**2. The cardholder enters their card (no API call)**

This step happens on Prava's secure surface, not through the API: redirect the cardholder to the
`iframe_url` (**hosted**) or mount it in your page with
[`collectPAN`](https://docs.prava.space/sdk/cards/collect-pan) (**embedded**). Card entry and passkey approval (a biometric
confirmation on the cardholder's device) happen here. Prava handles authentication, mandate
registration (the spending permission recorded with the card network), and tokenization (swapping
the card number for a secure stand-in) for you.

**3. Poll the result — GET /v1/sessions/\{sessionId}/payment-result**

For a non-quote checkout, this returns one-time `token` and `dynamic_cvv` credentials. For a
quote-backed checkout, it returns a credential-free transaction summary with the card actually
used and the normalized outcome in the top-level `status` and `error`. When merchant lifecycle
data exists, `merchant_res` also provides its normalized status and optional merchant order ID.
→ [Get Payment Result](https://docs.prava.space/api-reference/get-payment-result.md)

**4. Report the outcome — POST /v1/sessions/\{sessionId}/report-status**

For non-quote checkouts, tell Prava whether checkout succeeded (`APPROVED`) or failed (`DECLINED`)
so transaction records and the card network stay in sync. Quote callers do not call this public
endpoint; poll their normalized payment result instead. → [Report Status](https://docs.prava.space/api-reference/report-status.md)

### Supporting endpoints

> [card] [Enroll Card](https://docs.prava.space/api-reference/enroll-card.md)
>
> Provision a card only, or create an interactive card-and-passkey enrollment session

> [card] [Card Enrollment Status](https://docs.prava.space/api-reference/get-card-enrollment-status.md)
>
> Poll an interactive card-enrollment session without exposing payment credentials

> [card] [Revoke Session](https://docs.prava.space/api-reference/revoke-session.md)
>
> Cancel a session before it's used

> [card] [List Cards](https://docs.prava.space/api-reference/list-cards.md)
>
> Retrieve a customer's enrolled cards

> [card] [Delete Card](https://docs.prava.space/api-reference/delete-card.md)
>
> Delete a customer's card and retire its network token

> [card] [Set Default Card](https://docs.prava.space/api-reference/set-default-card.md)
>
> Choose which saved card is preselected at checkout


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