Errors

All errors share one envelope:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  }
}

details is optional; it’s included for validation errors to specify which fields failed. Every response also carries an X-Response-ID header; include it when contacting support@prava.space.

Authentication & validation

These can occur on any endpoint:

Status	Code	Cause	Recovery
401	`AUTH_1001`	Invalid or missing API key	Use `Authorization: Bearer sk_…` with a valid secret key for the right environment
401	`AUTH_1002`	Missing or invalid Authorization header	Include the header exactly as `Bearer sk_…`
401	`AUTH_1003`	Session has expired	Create a new session
401	`AUTH_1004`	Session has been revoked	Create a new session
400	`VAL_2001`	Request failed schema validation	Check `details` for the failing fields
400	`INVALID_REQUEST`	A required field is missing (e.g. `customer_id`, `card_id`)	Include the named field

Create Session — `POST /v1/sessions`

Status	Code	Cause	Recovery
429	`TRIES_EXHAUSTED`	Your account’s session allowance is depleted	Contact support@prava.space
500	`MERCHANT_LOOKUP_ERROR`	Your merchant account couldn’t be resolved	Retry; if persistent, contact support with the `X-Response-ID`
500	`CONFIG_ERROR`	Merchant account is missing payment configuration	Contact support; this is an account-setup issue, not a request problem
400	`CARD_NOT_FOUND`	A pre-selected card doesn’t exist	Verify via List Cards
400	`CARD_INACTIVE`	A pre-selected card is not active	Choose an active card
500	`SESSION_CREATE_ERROR`	Internal failure creating the session	Retry; then support

Payment Result — `GET /v1/sessions/{sessionId}/payment-result`

Status	Code	Cause	Recovery
404	`NOT_FOUND`	Session not found, or it belongs to another merchant	Verify the session ID and which key created it

Report Status — `POST /v1/sessions/{sessionId}/report-status`

Status	Code	Cause	Recovery
404	`NOT_FOUND`	Session / order / transaction reference not found	Verify the session ID and `txn_ref_id`
400	`INVALID_STATE`	No transaction awaiting a result	It may already be reported, or the cardholder hasn’t finished
400	`MANDATE_EXPIRED`	The mandate has expired	Create a new session
400	`PRODUCT_NOT_FOUND`	Product not found by the given ID	Verify `product_id` / `product_ref_id`
502	`VISA_CONFIRMATION_FAILED`	Card-network confirmation failed	Retry; then support
500	`REPORT_STATUS_ERROR`	Internal error	Contact support with the `X-Response-ID`

Cards — `GET /v1/listCards` · `POST /v1/deleteCard`

Status	Code	Cause	Recovery
404	`CUSTOMER_NOT_FOUND`	No customer for the given identifier	Verify `customer_id` (the `user_id` you used at session creation)
404	`NOT_FOUND`	Card not found (delete)	Verify `card_id` via List Cards
502	`NETWORK_DELETE_FAILED`	Card-network deletion failed (delete)	Retry

Revoke Session — `POST /v1/sessions/{id}/revoke`

Status	Code	Cause	Recovery
404	`NOT_FOUND`	Session not found	Verify the session ID
400	`INVALID_STATE`	Session not in a revocable state	It may already be completed or expired

The SDK has its own client-side error codes (SDK_ALREADY_ACTIVE, INVALID_CONFIG, IFRAME_LOAD_ERROR, SDK_INIT_ERROR); see Collect Card Details. CLI errors are mapped on the Prava Pay troubleshooting page.

Server-Side API

Reference

Authentication & validation

Create Session — `POST /v1/sessions`

Payment Result — `GET /v1/sessions/{sessionId}/payment-result`

Report Status — `POST /v1/sessions/{sessionId}/report-status`

Cards — `GET /v1/listCards` · `POST /v1/deleteCard`

Revoke Session — `POST /v1/sessions/{id}/revoke`

​Authentication & validation

​Create Session — POST /v1/sessions

​Payment Result — GET /v1/sessions/{sessionId}/payment-result

​Report Status — POST /v1/sessions/{sessionId}/report-status

​Cards — GET /v1/listCards · POST /v1/deleteCard

​Revoke Session — POST /v1/sessions/{id}/revoke

Authentication & validation

Create Session — `POST /v1/sessions`

Payment Result — `GET /v1/sessions/{sessionId}/payment-result`

Report Status — `POST /v1/sessions/{sessionId}/report-status`

Cards — `GET /v1/listCards` · `POST /v1/deleteCard`

Revoke Session — `POST /v1/sessions/{id}/revoke`