Skip to main content
Not sure this is the right path? See Choosing Your Integration.

​
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.
Never expose your secret key in client-side code, version control, or logs. Use it only in server-to-server requests.

​
Base URLs

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.
These are the only API hosts. dashboard.prava.space (developer console) and 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:

​
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:
Include this ID when contacting support to help trace issues.

​
Error Response Format

All errors follow a consistent structure:
The details field is optional and included for validation errors to specify which fields failed.

​
Common Error Codes

The full catalog (every code, per endpoint, with recovery steps) is on the Errors 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
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 (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
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

​
Supporting endpoints

Enroll Card

Provision a card only, or create an interactive card-and-passkey enrollment session

Card Enrollment Status

Poll an interactive card-enrollment session without exposing payment credentials

Revoke Session

Cancel a session before it’s used

List Cards

Retrieve a customer’s enrolled cards