> For the complete documentation index, see [llms.txt](https://docs.maibmerchants.md/checkout/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maibmerchants.md/checkout/getting-started/api-fundamentals.md).

# API Fundamentals

This section describes the core principles that apply when working with the Checkout API. These rules are common for all endpoints and must be respected to ensure a stable and secure integration.

### Request Structure

* All communication with the API is performed over **HTTPS** to guarantee data security and integrity.
* Request and response payloads are exchanged in **JSON** format.
* Each request must include a valid **Authorization header** (see *Authentication* section).
* Request bodies must follow the exact parameter structure defined in the endpoint specifications.
* Responses always follow a consistent format, including a top-level `ok` field and, in case of errors, an `errors` array with detailed codes and messages.

> **Tip:** Always validate both the HTTP status code and the `ok` flag in the JSON response to properly detect failures.

***

### Available Environments

Two environments are available for integration:

| Environment        | Base URL                                                        |
| ------------------ | --------------------------------------------------------------- |
| **Production**     | [`https://api.maibmerchants.md`](https://api.maibmerchants.md/) |
| **Sandbox (Test)** | <https://sandbox.maibmerchants.md>                              |

* Use the **sandbox environment** to perform initial development and functional testing without moving real funds.
* Once the integration is stable and certified, switch to the **production environment**.
* Endpoints and request structures are identical across environments.

***

### Authentication

The API uses **Bearer token authentication**.

1. Obtain an access token in advance (see [*Authentication*](/checkout/api-reference/endpoints/authentication.md) section for details on how to request it).
2. Include the token in the HTTP header of every request:

```http
Authorization: {tokenType} {access_token}
```

* Tokens are environment-specific (sandbox and production use different credentials).
* If the token is missing, expired, or invalid, the API will return `401 Unauthorized`.
* Keep tokens secret and never expose them in client-side code or public repositories.

***

### Data Format

* **Content type:** all requests must specify `Content-Type: application/json`.
* **Datetime fields:** always use the **ISO 8601** format with timezone offset.
  * Example: `2029-10-22T10:32:28+03:00`
* **Currency:** the API uses `MDL` (Moldovan Leu), encoded according to the **ISO 4217** standard.

***

### HTTP Response Codes

The API returns standard HTTP codes to indicate the outcome of each request:

| Code                          | Meaning                          | Notes                                                                                         |
| ----------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------- |
| **200 OK**                    | Valid request, response returned | The `ok` flag in the response body will be `true`.                                            |
| **400 Bad Request**           | Invalid request                  | Caused by missing/invalid parameters or malformed JSON. Check the `errors` array for details. |
| **401 Unauthorized**          | Missing or invalid token         | Ensure the Bearer token is present and not expired.                                           |
| **403 Forbidden**             | Insufficient permissions         | The token is valid but the action is not allowed for this merchant.                           |
| **500 Internal Server Error** | Unexpected server-side error     | Retry later or contact support if persistent.                                                 |

> **Best practice:** Always implement error handling logic based on both the **HTTP status code** and the **error details** in the JSON body.