Responses

The response envelope, pagination, HTTP status codes, and the error format used across the API.

Every endpoint in the external API follows the same conventions for shaping responses, paging lists, and reporting errors. Read this once and it applies everywhere.

Success envelope

A single resource is wrapped in a data object:

{
  "data": {
    "id": "5a6b7c8d-9e0f-1a2b-3c4d-5e6f7a8b9c0d",
    "title": "Order #10428",
    "status": "active"
  }
}

Some action endpoints instead return a short message:

{ "message": "Payment link archived." }

Pagination

List endpoints return a data array plus links and meta. Control paging with the per_page query parameter (default 15) and the page parameter.

{
  "data": [
    { "id": "5a6b...", "title": "Order #10428" },
    { "id": "6b7c...", "title": "Order #10429" }
  ],
  "links": {
    "first": "https://api.mytpe.appp/api/ext/links?page=1",
    "last": "https://api.mytpe.appp/api/ext/links?page=4",
    "prev": null,
    "next": "https://api.mytpe.appp/api/ext/links?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "to": 15,
    "per_page": 15,
    "last_page": 4,
    "total": 58
  }
}

Most list endpoints also accept search, sort_by, and sort_dir (asc / desc). The allowed sort_by values are listed on each resource page.

Data types

Type	Representation
Identifiers	UUID strings, e.g. `"5a6b7c8d-9e0f-1a2b-3c4d-5e6f7a8b9c0d"`.
Money	Decimal strings, e.g. `"4500.00"`. Currency is a 3‑letter code (`DZD`).
Timestamps	ISO 8601 UTC, e.g. `"2026-06-09T12:34:56.000000Z"`.
Enums	Lowercase snake_case strings — see Statuses & enums.
Booleans	`true` / `false`.

HTTP status codes

Code	Meaning
`200 OK`	Request succeeded.
`201 Created`	Resource created.
`204 No Content`	Succeeded with no body (e.g. webhook delete).
`401 Unauthorized`	Missing or invalid API credentials.
`403 Forbidden`	Authenticated, but not allowed to perform this action.
`404 Not Found`	Resource does not exist or is not yours.
`422 Unprocessable Entity`	Validation failed.
`500 Internal Server Error`	Unexpected server error.
`503 Service Unavailable`	A dependency (e.g. statistics, gateway) is temporarily down.

Errors

All non‑validation errors share one shape — a machine‑readable error code and a human‑readable message:

404 Not Found

{
  "error": "NOT_FOUND",
  "message": "Resource not found."
}

Common error codes:

HTTP	`error` code
`401`	`UNAUTHORIZED`
`403`	`FORBIDDEN`
`404`	`NOT_FOUND` (or resource‑specific, e.g. `IDENTIFICATION_NOT_FOUND`)
`422`	`BUSINESS_ERROR` (for business‑rule violations)
`503`	`SERVICE_UNAVAILABLE`

Validation errors

Validation failures return 422 with Laravel's errors map, where each key is a field and the value is an array of messages:

422 Unprocessable Entity

{
  "message": "The given data was invalid.",
  "errors": {
    "amount": ["The amount field is required when amount mode is fixed."],
    "payment_instance_id": ["The selected payment instance id is invalid."]
  }
}

Always branch on the HTTP status first, then read error (or errors) for specifics.