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 responses are JSON. 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 complete payment is three API calls and one non-API step. Nothing else is required:
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

Once the cardholder finishes, this returns the one-time credentials: token (virtual card number) and dynamic_cvv. Use them at the merchant checkout like a normal card. → Get Payment Result
4

Report the outcome — POST /v1/sessions/{sessionId}/report-status

Tell Prava whether the checkout succeeded (APPROVED) or failed (DECLINED) so transaction records and the card network stay in sync. → Report Status

​
Supporting endpoints

Revoke Session

Cancel a session before it’s used

List Cards

Retrieve a customer’s enrolled cards