curl "https://sandbox.api.prava.space/v1/sessions/ses_123/payment-result" \
-H "Authorization: Bearer sk_test_..."
import requests
resp = requests.get(
"https://sandbox.api.prava.space/v1/sessions/ses_123/payment-result",
headers={"Authorization": "Bearer sk_test_..."},
)
const resp = await fetch("https://sandbox.api.prava.space/v1/sessions/ses_123/payment-result", {
headers: {
Authorization: "Bearer sk_test_...",
},
});
{
"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": []
}
]
}
]
}
{
"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" }
}
{
"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"
}
}
{
"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."
}
}
{
"error": { "code": "AUTH_1002", "message": "Missing or invalid Authorization header" }
}
{
"error": { "code": "NOT_FOUND", "message": "Session not found" }
}
Server-Side API
Get Payment Result
Retrieve transaction status, card identity, and payment credentials for a session
GET
/
v1
/
sessions
/
{sessionId}
/
payment-result
curl "https://sandbox.api.prava.space/v1/sessions/ses_123/payment-result" \
-H "Authorization: Bearer sk_test_..."
import requests
resp = requests.get(
"https://sandbox.api.prava.space/v1/sessions/ses_123/payment-result",
headers={"Authorization": "Bearer sk_test_..."},
)
const resp = await fetch("https://sandbox.api.prava.space/v1/sessions/ses_123/payment-result", {
headers: {
Authorization: "Bearer sk_test_...",
},
});
{
"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": []
}
]
}
]
}
{
"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" }
}
{
"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"
}
}
{
"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."
}
}
{
"error": { "code": "AUTH_1002", "message": "Missing or invalid Authorization header" }
}
{
"error": { "code": "NOT_FOUND", "message": "Session not found" }
}
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
string
required
The session id from Create Session.
Response
string
string | null
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.object[]
Show transaction properties
Show transaction properties
string
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.string
initiated | awaiting_result | completed | failed.object[]
Omitted from credential-free quote-backed results.
Show line_item properties
Show line_item properties
string
Line-item reference — pass this to Report Status.
string | null
string | null
string
string
pending | credentials_generated | completed | failed.string | null
Virtual card number (network token) your agent uses at checkout. Non-null after credentials are generated.
string | null
Single-use CVV. Non-null after credentials are generated.
string | null
string | null
object
Present only when the transaction failed:
{ code, message }.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.
Show merchant_res properties
Show merchant_res properties
string
pending | quote_ready | prepared | prepare_failed | paid | failed | needs_human | unknown. An effective completed result maps to paid, including successful sandbox simulation.string
Optional merchant order ID, distinct from Prava’s top-level
order_id. Returned only when it meets the bounded identifier format.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.
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.Notes
- For non-quote checkouts,
tokenanddynamic_cvvcontain the virtual card credentials your agent uses at checkout. - Read
transactions[].card_idas 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, andstatus); they never include token, CVV, expiry, or line-item credentials. merchant_rescontains onlystatusand optionalorderId. Read canonical failure details from the top-levelerror. Keep polling while the top-level status ispendingorprocessing.- Sandbox simulation can return effective
completedandmerchant_res.status: "paid"whileobserved_result.statusisfailed. 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-sidesandbox_simulationobject. - 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.
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 |
curl "https://sandbox.api.prava.space/v1/sessions/ses_123/payment-result" \
-H "Authorization: Bearer sk_test_..."
import requests
resp = requests.get(
"https://sandbox.api.prava.space/v1/sessions/ses_123/payment-result",
headers={"Authorization": "Bearer sk_test_..."},
)
const resp = await fetch("https://sandbox.api.prava.space/v1/sessions/ses_123/payment-result", {
headers: {
Authorization: "Bearer sk_test_...",
},
});
{
"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": []
}
]
}
]
}
{
"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" }
}
{
"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"
}
}
{
"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."
}
}
{
"error": { "code": "AUTH_1002", "message": "Missing or invalid Authorization header" }
}
{
"error": { "code": "NOT_FOUND", "message": "Session not found" }
}
Authorizations
Your secret key: sk_test_* (sandbox) or sk_live_* (production).
Path Parameters
The session ID returned from Create Session
Response
Payment result
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.
Available options:
pending, processing, awaiting_result, completed, failed Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
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.
- Option 1
- Option 2
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes