# API Fundamentals

This section describes the core principles that apply when working with the Request to Pay (RTP) 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 RTP 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`     |
| **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

To securely access and use the API, each request must be authorized. Authentication is done via a standard OAuth 2.0 Client Credentials Flow, using the Client ID and Client Secret provided by maib.

**Main steps of authentication:**

**Obtaining the access token (Access Token):**\
The client application sends a POST request to the `/v2/auth/token` endpoint, providing the clientId and clientSecret.

**Receiving the token:**\
If the credentials are correct, the response will contain:

* `accessToken`: a JWT (JSON Web Token) required for authorizing subsequent requests.
* `expiresIn`: token lifetime in seconds (e.g., 300 seconds = 5 minutes).
* `tokenType`: usually `Bearer`.

**Using the token in requests:**\
For every call to other API endpoints, the token must be included in the HTTP Authorization header in the format:

```http
Authorization: Bearer {access_token}
```

**Token renewal:**\
After the accessToken expires, the client must repeat step 1 to obtain a new token.

***

### 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.
* **Identifiers:** RTP IDs (`rtpId`) and Payment IDs (`payId`) are UUID/GUID strings.

***

### HTTP Response Codes

The RTP 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.

###


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.maibmerchants.md/request-to-pay/getting-started/api-fundamentals.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.