Skip to main content

​
Endpoint

POST /v1/sessions/:sessionId/report-status
EnvironmentFull URL
Sandboxhttps://sandbox.api.prava.space/v1/sessions/:sessionId/report-status
Productionhttps://api.prava.space/v1/sessions/:sessionId/report-status

​
Authentication

Bearer token using your secret key: 
Authorization: Bearer sk_test_xxx

​
Path Parameters

​
sessionId
string
required
The session ID returned from Create Session

​
Request Body

​
txn_ref_id
string
required
The transaction line item reference ID (from Get Payment Result)
​
txn_status
string
required
The payment outcome: APPROVED or DECLINED
​
txn_type
string
Transaction type. Defaults to PURCHASE.
​
authorization_code
string
Authorization code from the merchant’s payment processor (max 128 characters)
​
response_code
string
Processor response code, e.g., "00" for approved (max 2 characters)
​
amount_paid
string
Override the total amount paid (if different from the original amount)
​
product_statuses
array
Optional per-product status overrides

​
Response

​
status
string
Always "confirmed"
​
txn_ref_id
string
The transaction line item reference ID
​
txn_status
string
The reported status: APPROVED or DECLINED
​
visa_confirmation
string
Card network confirmation result: SUCCESS or FAILURE

​
Example

Swap the host for production: use https://api.prava.space instead of https://sandbox.api.prava.space.
curl -X POST https://sandbox.api.prava.space/v1/sessions/ses_a1b2c3d4/report-status \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "txn_ref_id": "tli_abc123",
    "txn_status": "APPROVED",
    "authorization_code": "AUTH123",
    "response_code": "00"
  }'

curl -X POST https://api.prava.space/v1/sessions/ses_a1b2c3d4/report-status \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "txn_ref_id": "tli_abc123",
    "txn_status": "APPROVED",
    "authorization_code": "AUTH123",
    "response_code": "00"
  }'

const BASE_URL = 'https://sandbox.api.prava.space'; // or https://api.prava.space

const result = await fetch(
  `${BASE_URL}/v1/sessions/ses_a1b2c3d4/report-status`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${SECRET_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      txn_ref_id: 'tli_abc123',
      txn_status: 'APPROVED',
      authorization_code: 'AUTH123',
      response_code: '00',
    }),
  }
).then(res => res.json());

​
Response

{
  "status": "confirmed",
  "txn_ref_id": "tli_abc123",
  "txn_status": "APPROVED",
  "visa_confirmation": "SUCCESS"
}

​
Reporting a Failed Payment

curl -X POST https://sandbox.api.prava.space/v1/sessions/ses_a1b2c3d4/report-status \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "txn_ref_id": "tli_abc123",
    "txn_status": "DECLINED",
    "response_code": "51"
  }'

​
Reporting with Per-Product Statuses

curl -X POST https://sandbox.api.prava.space/v1/sessions/ses_a1b2c3d4/report-status \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "txn_ref_id": "tli_abc123",
    "txn_status": "APPROVED",
    "authorization_code": "AUTH123",
    "product_statuses": [
      {
        "product_ref_id": "prd_def456",
        "status": "COMPLETED",
        "amount_paid": "49.99"
      }
    ]
  }'

​
Error Responses

StatusCodeCauseResolution
401AUTH_1001Invalid API keyCheck your secret key
401AUTH_1002Missing or invalid Authorization headerInclude Authorization: Bearer sk_xxx
404NOT_FOUNDSession not foundVerify the session ID
404NOT_FOUNDNo order found for this sessionEnsure the session has a completed order
404NOT_FOUNDTransaction reference not foundVerify the txn_ref_id
400INVALID_STATENo transaction awaiting payment resultThe transaction may have already been reported or is not yet ready
400MANDATE_EXPIREDMandate has expiredThe mandate expired before status was reported — register a new intent
400INVALID_STATETransaction has no mandateThe transaction is missing mandate data
400PRODUCT_NOT_FOUNDProduct not found by the given IDVerify product_id or product_ref_id
502VISA_CONFIRMATION_FAILEDCard network confirmation failedRetry or contact support
500REPORT_STATUS_ERRORInternal errorContact support with the X-Response-ID header

​
Error Response Format

{
  "error": {
    "code": "INVALID_STATE",
    "message": "No transaction awaiting payment result found for this session"
  }
}

​
Notes

  • Always report status after checkout execution — this updates transaction records and relays the outcome to the card network.
  • For one-time mandates, an APPROVED status automatically consumes the mandate (it cannot be used again).
  • For recurring mandates, an APPROVED status keeps the mandate active for future invocations.
  • If a payment token was used but checkout failed, reporting DECLINED ensures the mandate invocation is logged correctly.
  • The product_statuses field is optional and informational — the overall mandate status follows txn_status.