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

The RTP API uses Bearer token authentication.

1. Obtain an access token in advance (see Authentication section for details on how to request it).

2. Include the token in the HTTP header of every request:

Authorization: Bearer {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.

• 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.