maib Merchants API Documentation

https://docs.maibmerchants.md/
Admin
maib Merchants API Documentation provides comprehensive integration guides and API references for...
Tokens:109,264
Snippets:639
Trust Score:4.8
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Query example for GET /checkouts

Source: https://docs.maibmerchants.md/checkout/api-reference/endpoints/retrieve-all-checkouts

Example query for retrieving completed checkouts in MDL, with pagination and sorting. Shows the query parameters in use.

```http
GET /checkouts?status=Completed&currency=MDL&count=10&offset=0&sortBy=createdAt&order=desc HTTP/1.1
```

--------------------------------

### Query Example for GET /v2/payments

Source: https://docs.maibmerchants.md/checkout/api-reference/endpoints/retrieve-all-payments-by-filter

Example HTTP request showing how to include query parameters for filtering, pagination, and sorting. Replace <your_query_params_here> with the actual query string.

```http
GET /v2/payments?<your_query_params_here> HTTP/1.1
```

--------------------------------

### Example refund request (curl)

Source: https://docs.maibmerchants.md/request-to-pay/api-reference/endpoints/initiate-a-refund-for-a-completed-payment

Example curl command to initiate a refund. The access token is provided as a placeholder.

```bash
curl -X POST "https://api.maibmerchants.md/v2/rtp/123e4567-e89b-12d3-a456-426614174000/refund" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Refund reason"}'
```

--------------------------------

### Payment Simulation Request Example

Source: https://docs.maibmerchants.md/mia-qr-api/en/payment-simulation-sandbox

Example request body for the POST /v2/mia/test-pay endpoint. All fields are required: qrId (string guid), amount (decimal), iban (string up to 100), currency (enum, only MDL), and payerName (string up to 200).

```json
{
  "qrId": "123e4567-e89b-12d3-a456-426614174000",
  "amount": 10,
  "iban": "MD88AG000000011621810140",
  "currency": "MDL",
  "payerName": "John D."
}
```

--------------------------------

### Example Notification

Source: https://docs.maibmerchants.md/request-to-pay/api-reference/callback-notifications

Example callback notification with sample values. Use this to understand the expected format and test your handler.

```json
{
  "result": {
    "rtpId": "123e4567-e89b-12d3-a456-426614174000",
    "rtpStatus": "Accepted",
    "orderId": "123",
    "payId": "c56a4180-65aa-42ec-a945-5fd21dec0538",
    "amount": 100.00,
    "commission": 1.00,
    "currency": "MDL",
    "payerName": "John D.",
    "payerIban": "MD24AG000225100014156789",
    "executedAt": "2029-10-22T10:32:28+03:00"
  },
  "signature": "r4KwwIUXQGHhcEM7C4um8o9rSrGEriTRcYQuBbmjEec="
}
```

--------------------------------

### Example request with curl

Source: https://docs.maibmerchants.md/request-to-pay/api-reference/endpoints/retrieve-the-status-of-a-payment-request

Example curl command to retrieve the status of a payment request. Replace `{{access_token}}` with a valid access token.

```bash
curl -G "https://api.maibmerchants.md/v2/rtp/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {{access_token}}"
```

--------------------------------

### Retrieve Payments with Filters - curl Example

Source: https://docs.maibmerchants.md/mia-qr-api/en/endpoints/information-retrieval-get/retrieve-list-of-payments-with-filtering-options

Example request to retrieve a list of payments with filtering options. Uses the GET /v2/mia/payments endpoint with required count and offset parameters, and optional filters like qrId, sortBy, and order.

```bash
curl -G "https://api.example.com/v2/mia/payments" \
  -H "Authorization: Bearer {{access_token}}" \
  --data-urlencode "count=10" \
  --data-urlencode "offset=0" \
  --data-urlencode "qrId=789e0123-f456-7890-a123-456789012345" \
  --data-urlencode "sortBy=executedAt" \
  --data-urlencode "order=asc"
```

--------------------------------

### Example Request

Source: https://docs.maibmerchants.md/request-to-pay/api-reference/sandbox-simulation-environment/simulate-acceptance-of-a-payment-request

Example request to simulate acceptance of a payment request. The request body includes the amount and currency (MDL).

```http
POST /v2/rtp/123e4567-e89b-12d3-a456-426614174000/test-accept HTTP/1.1
Host: sandbox.maibmerchants.md
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "amount": 10,
  "currency": "MDL"
}
```

--------------------------------

### Example Request Body

Source: https://docs.maibmerchants.md/checkout/api-reference/endpoints/refund-a-payment

Example JSON body for the refund request, including amount and reason.

```json
{
  "amount": 50.61,
  "reason": "Client returned the product"
}
```

--------------------------------

### GET /v2/mia/qr - List QR Codes with Filters

Source: https://docs.maibmerchants.md/mia-qr-api/en/endpoints/information-retrieval-get/display-list-of-qr-codes-with-filtering-options

Example request to retrieve a list of QR codes with filtering, sorting, and pagination. Uses query parameters count, offset, amountFrom, amountTo, sortBy, and order. Requires an access token in the Authorization header.

```bash
curl -G "https://api.example.com/v2/mia/qr" \
  -H "Authorization: Bearer {{access_token}}" \
  --data-urlencode "count=10" \
  --data-urlencode "offset=0" \
  --data-urlencode "amountFrom=10.00" \
  --data-urlencode "amountTo=100.00" \
  --data-urlencode "sortBy=createdAt" \
  --data-urlencode "order=desc"
```

--------------------------------

### Example refund request (HTTP)

Source: https://docs.maibmerchants.md/request-to-pay/api-reference/endpoints/initiate-a-refund-for-a-completed-payment

Example HTTP request to initiate a refund. The request body must include a reason for the refund.

```http
POST /v2/rtp/123e4567-e89b-12d3-a456-426614174000/refund HTTP/1.1
Host: api.maibmerchants.md
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "reason": "Refund reason"
}
```

--------------------------------

### Response Example (JSON)

Source: https://docs.maibmerchants.md/checkout/api-reference/endpoints/retrieve-refund-details

Example JSON response containing the refund details, including the result object, ok flag, and errors field.

```json
{
  "result": {
    "id": "eaed443e-988f-4b59-89da-e76501977fab",
    "paymentId": "ae20c2ae-328b-456d-bed1-52646b5eacab",
    "refundType": "Full",
    "amount": 50.61,
    "currency": "MDL",
    "refundReason": "Refund reason",
    "executedAt": "2024-01-12T00:00:00+03:00",
    "status": "Created"
  },
  "ok": true,
  "errors": null
}
```

--------------------------------

### Example request body for POST /v2/auth/token

Source: https://docs.maibmerchants.md/checkout/api-reference/endpoints/authentication/obtain-authentication-token

Example request body for the POST /v2/auth/token endpoint. Contains the clientId and clientSecret provided by maib.

```json
{
  "clientId": "749c564f-1a65-48e3-a4bf-b7932b6ae3db",
  "clientSecret": "0d922db8-9a2f-4c66-a60d-76a762c9bb04"
}
```

--------------------------------

### Example Successful Response for Get Payment by ID

Source: https://docs.maibmerchants.md/checkout/api-reference/endpoints/get-payment-by-id

Example successful response for the Get payment by id endpoint. Shows the structure of the result object and root-level fields.

```json
{
    "result": {
        "paymentIntentId": "d5c5e7ff-6ecc-4d56-9953-5f14cb0a9181",
        "isRefundable": true,
        "partialRefundAvailable": true,
        "paymentEntryPoint": "Checkout",
        "refundableAmount": 3.00,
        "paymentId": "a975d5c3-9b5c-4497-affa-b615cbbb43f2",
        "executedAt": "2026-02-06T17:32:36.4267896+00:00",
        "status": "Executed",
        "amount": 3.00,
        "currency": "MDL",
        "type": "MMC",
        "providerType": "MMC",
        "referenceNumber": "603717100749",
        "mcc": "NONE",
        "orderId": "some-order-id",
        "terminalId": "0149587",
        "refundedAmount": 0.00,
        "requestedRefundAmount": 0.00
    },
    "ok": true
}
```

--------------------------------

### GET /v2/payments/refunds/{id} - Request Example

Source: https://docs.maibmerchants.md/checkout/api-reference/endpoints/retrieve-refund-details

Example HTTP request to retrieve refund details. The Authorization header uses the Bearer token format.

```http
GET /v2/payments/refunds/eaed443e-988f-4b59-89da-e76501977fab
Authorization: Bearer {access_token}
```

--------------------------------

### Example request to list all payment requests

Source: https://docs.maibmerchants.md/request-to-pay/api-reference/endpoints/list-all-payment-requests

Example curl command to list payment requests with query parameters for pagination, filtering, and sorting. Replace {{access_token}} with a valid token.

```bash
curl -G "https://api.maibmerchants.md/v2/rtp" \
  -H "Authorization: Bearer {{access_token}}" \
  --data-urlencode "count=10" \
  --data-urlencode "offset=0" \
  --data-urlencode "amount=10.00" \
  --data-urlencode "sortBy=createdAt" \
  --data-urlencode "order=desc"
```

--------------------------------

### GET /v2/mia/qr/{qrId}

Source: https://docs.maibmerchants.md/mia-qr-api/en/endpoints/information-retrieval-get/retrieve-qr-details-by-id

This code snippet documents the GET /v2/mia/qr/{qrId} endpoint, including its path parameter, request example, and full response schema.

```APIDOC
## GET /v2/mia/qr/{qrId}

### Description
Retrieves details of an existing QR code using its unique identifier `qrId`. The same type of information can also be received automatically through the callback mechanism.

### Method
GET

### Endpoint
`/v2/mia/qr/{qrId}`

### Parameters
#### Path Parameters
- **qrId** (string, guid) - Required - Unique identifier of the QR code.

### Request Example
```
curl -G "https://api.example.com/v2/mia/qr/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer {{access_token}}"
```

### Response
#### Success Response (200)
- **result** (object) - Response object.
- **result.qrId** (string, guid) - Unique QR code identifier.
- **result.extensionId** (string, guid) - QR extension identifier.
- **result.orderId** (string, 100) - Merchant-side order identifier.
- **result.status** (string, enum) - QR status. Possible values: `Active`, `Inactive`, `Expired`, `Paid`, `Cancelled`.
- **result.type** (string, enum) - QR type: `Static`, `Dynamic`, `Hybrid`.
- **result.url** (string, 1000) - QR URL. Format: HTTPS URL.
- **result.amountType** (string, enum) - Amount type: `Fixed`, `Controlled`, `Free`.
- **result.amount** (number, decimal) - Fixed amount (for fixed-type QR).
- **result.amountMin** (number, decimal) - Minimum amount (for controlled-type QR).
- **result.amountMax** (number, decimal) - Maximum amount (for controlled-type QR).
- **result.currency** (string, enum) - Payment currency. Value: `MDL` (ISO 4217).
- **result.description** (string, 500) - Order description.
- **result.callbackUrl** (string, 1000) - Merchant callback URL for payment notification. Format: HTTPS URL.
- **result.createdAt** (string, datetime) - QR code creation timestamp (ISO 8601-1:2019).
- **result.updatedAt** (string, datetime) - Last status update timestamp.
- **result.expiresAt** (string, datetime) - Expiry timestamp for dynamic/hybrid QR.
- **result.terminalId** (string, 100) - Terminal ID provided by the bank.
- **ok** (boolean) - Request processing status. `true` – successful, `false` – error occurred.
- **errors** (array) - Error list (if any).
- **errors.errorCode** (string) - Error code.
- **errors.errorMessage** (string) - Error description.

#### Response Example
```
{
  "result": {
    "qrId": "123e4567-e89b-12d3-a456-426614174000",
    "extensionId": "40e6ba44-7dff-48cc-91ec-386a38318c68",
    "status": "Paid",
    "type": "Dynamic",
    "url": "https://example.com/qr/123e4567-e89b-12d3-a456-426614174000",
    "amountType": "Fixed",
    "amount": 50.00,
    "currency": "MDL",
    "description": "Order description",
    "callbackUrl": "https://example.com/callback",
    "createdAt": "2029-10-22T10:32:28+03:00",
    "updatedAt": "2029-10-22T10:32:58+03:00",
    "expiresAt": "2029-10-22T10:33:28+03:00",
    "terminalId": "P011111"
  },
  "ok": true
}
```
```

--------------------------------

### Retrieve Payments Response - JSON Example

Source: https://docs.maibmerchants.md/mia-qr-api/en/endpoints/information-retrieval-get/retrieve-list-of-payments-with-filtering-options

Example response from the GET /v2/mia/payments endpoint. Shows the structure with result.totalCount, result.items array, and ok flag. Includes payment details such as payId, amount, commission, status, and timestamps.

```json
{
  "result": {
    "totalCount": 42,
    "items": [
      {
        "payId": "123e4567-e89b-12d3-a456-426614174000",
        "referenceId": "QR000123456789",
        "qrId": "789e0123-f456-7890-a123-456789012345",
        "extensionId": "40e6ba44-7dff-48cc-91ec-386a38318c68",
        "amount": 50.00,
        "commission": 0.50,
        "currency": "MDL",
        "description": "Payment for order #123",
        "payerName": "John D.",
        "payerIban": "MD24AG00225100013104168",
        "status": "Executed",
        "executedAt": "2024-08-05T10:32:28+03:00",
        "terminalId": "P011111"
      },
      {
        "payId": "456e7890-a12b-34cd-5678-9e01f23g4567",
        "referenceId": "QR000123456780",
        "qrId": "789e0123-f456-7890-a123-456789012345",
        "extensionId": "37efb479-c41b-4a39-bd27-ea1aef05134f",
        "amount": 100.00,
        "commission": 1.00,
        "currency": "MDL",
        "description": "Payment for order #1234",
        "payerName": "Jane S.",
        "payerIban": "MD24AG000225100014156789",
        "status": "Refunded",
        "executedAt": "2024-08-04T09:15:00+03:00",
        "refundedAt": "2024-08-05T09:17:05+03:00",
        "terminalId": "P011111"
      }
    ]
  },
  "ok": true
}
```

--------------------------------

### Response Example - List QR Codes

Source: https://docs.maibmerchants.md/mia-qr-api/en/endpoints/information-retrieval-get/display-list-of-qr-codes-with-filtering-options

Example response for the list QR codes endpoint. Shows the structure with result.totalCount, items array, and ok flag. Includes fields like qrId, type, amount, currency, status, and timestamps.

```json
{
  "result": {
    "totalCount": 42,
    "items": [
      {
        "qrId": "123e4567-e89b-12d3-a456-426614174000",
        "extensionId": "40e6ba44-7dff-48cc-91ec-386a38318c68",
        "type": "Dynamic",
        "url": "https://example.com/qr/123e4567-e89b-12d3-a456-426614174000",
        "amountType": "Fixed",
        "amount": 50.00,
        "currency": "MDL",
        "description": "Description",
        "status": "Paid",
        "createdAt": "2024-08-05T10:32:28+03:00",
        "updatedAt": "2024-08-05T10:33:50+03:00",
        "expiresAt": "2024-08-05T10:34:28+03:00",
        "terminalId": "P011111"
      }
    ]
  },
  "ok": true
}
```

--------------------------------

### Example request to create a new RTP

Source: https://docs.maibmerchants.md/request-to-pay/api-reference/endpoints/create-a-new-payment-request-rtp

Complete example request to create a new RTP. The body includes all required fields: alias, amount, expiresAt, currency, and description. Optional fields like orderId, terminalId, callbackUrl, and redirectUrl are also shown.

```http
POST /v2/rtp HTTP/1.1
Host: api.maibmerchants.md
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "alias": "37369112221",
  "amount": 150.00,
  "expiresAt": "2029-10-22T10:32:28+03:00",
  "currency": "MDL",
  "description": "Invoice #123",
  "orderId": "INV123",
  "terminalId": "P011111",
  "callbackUrl": "https://merchant.example.com/callback",
  "redirectUrl": "https://merchant.example.com/success"
}
```

--------------------------------

### Example Successful Response

Source: https://docs.maibmerchants.md/checkout/api-reference/endpoints/refund-a-payment

Example JSON response for a successful refund, containing refundId and status.

```json
{
  "result": {
    "refundId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "Created"
  },
  "ok": true
}
```

--------------------------------

### Payment Simulation Response Example

Source: https://docs.maibmerchants.md/mia-qr-api/en/payment-simulation-sandbox

Example response from the payment simulation endpoint. The result object contains payment details including qrStatus (possible values: Active, Inactive, Expired, Paid, Cancelled), orderId, payId, amount, commission, currency, payerName, payerIban, executedAt, and signatureKey. The ok field indicates success (true) or failure (false).

```json
{
  "result": {
    "qrId": "123e4567-e89b-12d3-a456-426614174000",
    "qrStatus": "Active",
    "orderId": "123",
    "payId": "6d24e4a5-c6bf-4d3e-bf7a-8d2123faf4e9",
    "amount": 10,
    "commission": 2.50,
    "currency": "MDL",
    "payerName": "John D.",
    "payerIban": "MD88AG000000011621810140",
    "executedAt": "2024-11-29T10:56:52.1380956+00:00",
    "signatureKey": "592b6999-fdd0-4fd3-9708-5cb9df590dee"
  },
  "ok": true
}
```

--------------------------------

### Endpoint: GET /v2/payments

Source: https://docs.maibmerchants.md/checkout/api-reference/endpoints/retrieve-all-payments-by-filter

The endpoint path for retrieving all payments by filter. Use with the GET HTTP method.

```http
/v2/payments
```

--------------------------------

### Example response from POST /v2/auth/token

Source: https://docs.maibmerchants.md/checkout/api-reference/endpoints/authentication/obtain-authentication-token

Example response from the POST /v2/auth/token endpoint. Contains the access token, its expiration time in seconds, token type, and a success flag.

```json
{
  "result": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 300,
    "tokenType": "Bearer"
  },
  "ok": true
}
```

--------------------------------

### GET /v2/checkouts endpoint

Source: https://docs.maibmerchants.md/checkout/api-reference/endpoints/retrieve-all-checkouts

The endpoint path for retrieving all checkouts. Use with the GET method and the required Authorization header.

```http
/v2/checkouts
```

--------------------------------

### Callback response examples for card registration (with and without amount)

Source: https://docs.maibmerchants.md/e-commerce/one-click-payments/register-card-in-the-maib-ecomm-system

Two example callback responses from the maib ecomm system after card registration. The first includes the amount parameter and returns status OK with statusCode 000 and statusMessage Approved; the second omits the amount parameter and returns status PENDING. Both include the billerId and billerExpiry needed for subsequent execute-recurring payments.

```json
{
"result": {
"payId": "f16a9006-128a-46bc-8e2a-77a6ee99df75",
"billerId": "t78i8006-458a-46bc-9e0a-89a6ee11df68",
"billerExpiry": "1225",
"orderId": "123",
"status": "OK",
"statusCode": "000",
"statusMessage": "Approved",
"threeDs": "AUTHENTICATED",
"rrn": "331711380059",
"approval": "327593",
"cardNumber": "510218******1124",
"amount": 6.25,
"currency": "EUR"
},
"signature": "r4KwwIUXQGHhcEM7C4um8o9rSrGEriTRcYQuBbmjEec="
}
```

```json
{
"result": {
"payId": "f16a9006-128a-46bc-8e2a-77a6ee99df75",
"billerId": "t78i8006-458a-46bc-9e0a-89a6ee11df68",
"billerExpiry": "1225",
"status": "PENDING",
"threeDs": "AUTHENTICATED",
"cardNumber": "510218******1124",
"amount": 0,
"currency": "EUR"
},
"signature": "r4KwwIUXQGHhcEM7C4um8o9rSrGEriTRcYQuBbmjEec="
}
```
Tokens:
Raw