Response Format

Tsara business API responses use a predictable JSON envelope so integrations can handle success, validation, and operational failures consistently.

Success response

{
  "success": true,
  "status": "success",
  "status_code": 200,
  "message": "OK",
  "data": {}
}

Error response

{
  "success": false,
  "status": "failed",
  "status_code": 422,
  "message": "Validation failed",
  "errors": {
    "field": ["Field is required."]
  }
}

Envelope fields

Field	Meaning
`success`	Boolean result of the API request
`status`	Top-level request outcome, usually `success` or `failed`
`status_code`	Status code repeated in the JSON body for client compatibility
`message`	Human-readable summary of the result
`data`	Resource, collection, or endpoint-specific result
`errors`	Optional field-level validation messages
`meta`	Optional pagination information for list endpoints

Request success versus transaction success

An HTTP 200 response means the API request was handled successfully. It does not always mean the underlying payment, transfer, payout, refund, or bill is complete.

For asynchronous resources, inspect data.status. Values such as pending, processing, or awaiting_crypto_payment require a later webhook or status check. Treat only the final success status documented for that product as completed.

List and single-resource responses

List endpoints normally return an array in data and pagination details in meta. When a unique identifier such as id, uid, reference, or trx_id is supplied, the same endpoint may return one object in data without pagination.

Integration guidance

use the real HTTP status for transport-level handling
use success and message for the request result
use data.status for the lifecycle of asynchronous resources
do not assume optional fields are always present
preserve identifiers as strings, even when they contain only digits
parse timestamps as server-provided date-time values rather than relying on display formatting

Older Tsara examples may show request_id, nested error objects, or pagination. Those are not the default business API envelope unless a specific endpoint explicitly documents them.