### Signature Verification Example

Source: https://docs.maibmerchants.md/checkout/api-reference/callback-notifications

An example demonstrating the structure of a callback message, the secret key, and the expected signature. This is useful for understanding the data format and expected output.

```json
message:
{"checkoutId": "5a4d27a4-79f5-426b-9403-cccdeee81747","terminalId": "T1234567","amount": 1234.56,"currency": "MDL","completedAt": "2024-11-23T19:35:00.6772285+02:00","payerName": "John","payerEmail": "Smith","payerPhone": "37368473653","payerIp": "192.175.12.22","orderId": "ORDER-2025-0001","orderDescription": "Online purchase of electronics","orderDeliveryAmount": 50.00,"orderDeliveryCurrency": "MDL","paymentId": "379b31a3-8283-43d4-8a7b-eef8c0736a32","paymentAmount": 1234.56,"paymentCurrency": "MDL","paymentStatus": "Executed","paymentExecutedAt": "2025-05-05T23:38:07.2760698+03:00","senderIban": "NL43RABO1438227787","senderName": "Steven","senderCardNumber": "444433******1111","retrievalReferenceNumber": "ABC324353245","processingStatus": "OK","processingStatusCode": "00","approvalCode": "123456","threeDsResult": "Y","threeDsReason": null,"paymentMethod": "Card"}.1761032516817
 
key:
67be8e54-ac28-485d-9369-27f6d3c55a27
 
signature
mtFkCMxfwj9t2wvY/7JASHLw+K/du4mY8azf1lV0ttg=
```

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

### Example Request

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

A sample POST request to simulate RTP acceptance.

```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"
}
```

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

### Final API Response Example

Source: https://docs.maibmerchants.md/e-commerce/one-click-payments/execute-one-click-payment

Example of a final transaction response containing status, authentication, and payment details.

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

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

### Example Notification Data

Source: https://docs.maibmerchants.md/e-commerce/notifications-on-callback-url

This is an example of the JSON data structure received on the Callback URL, including the signature for verification.

```json
{
"result": {
"payId": "f16a9006-128a-46bc-8e2a-77a6ee99df75",
"orderId": "123",
"status": "OK",
"statusCode": "000",
"statusMessage": "Approved",
"threeDs": "AUTHENTICATED",
"rrn": "331711380059",
"approval": "327593",
"cardNumber": "510218******1124",
"amount": 10.25,
"currency": "MDL"
},
"signature": "5wHkZvm9lFeXxSeFF0ui2CnAp7pCEFSNmuHYFYJlC0s="
}
```

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

### Intermediate API Response Examples

Source: https://docs.maibmerchants.md/e-commerce/one-click-payments/execute-one-click-payment

Examples of successful and error responses for intermediate transaction requests.

```json
{
"result": {
"payId": "f16a9006-128a-46bc-8e2a-77a6ee99df75",
"orderId": "123",
"payUrl": "https://maib.ecommerce.md/ecomm01/ClientHandler?trans_id=rEsfhyIk8s9ypxkcS9fj/3C8FqA="
},
"ok": true
}
```

```json
{
    "errors": [
        {
            "errorCode": "12001",
            "errorMessage": "Parameter 'amount' is invalid",
            "errorArgs": {
                "parameter": "amount"
            }
        }
    ],
    "ok": false
}
```

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

### Example Error Response

Source: https://docs.maibmerchants.md/checkout/api-reference/errors/api-errors

A concrete example of an error response indicating a missing or expired checkout.

```json
{
  "ok": false,
  "errors": [
    {
      "errorCode": "maib.merchant.payments-43001",
      "errorMessage": "The specified checkout does not exist or has expired."
    }
  ]
}
```

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

### Callback Response Examples

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

JSON response structures for transactions processed with and without an amount parameter.

```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="
}
```

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

### Example Notification Payload

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

A sample notification payload demonstrating the structure with populated values.

```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="
}
```

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

### Cancel RTP Request Example

Source: https://docs.maibmerchants.md/request-to-pay/api-reference/endpoints/cancel-a-pending-payment-request

This example demonstrates how to cancel a pending RTP request. Ensure the RTP is in 'Pending' status before attempting cancellation. The 'reason' parameter is mandatory.

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

{
  "reason": "Customer requested cancellation"
}
```

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

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

### Example of an API error response

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

A concrete example of an error response returned when a Request to Pay is not found or has expired.

```json
[
  {
    "errorCode": "23000",
    "errorMessage": "The specified Request to Pay does not exist or has expired."
  }
]
```

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

### List RTP Requests Example

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

Use this cURL command to list RTP requests. It demonstrates setting pagination, filtering by amount, and sorting.

```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"
```

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

### Example API Response Structure

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

A sample JSON response containing a list of payment objects and the standard root-level fields.

```json
{
    "result": {
        "items": [
            {
                "paymentIntentId": "9783b6f8-1173-440c-b387-8d18938c972a",
                "isRefundable": true,
                "partialRefundAvailable": true,
                "paymentEntryPoint": "Checkout",
                "refundableAmount": 1.00,
                "paymentId": "265b0bb5-d484-40f2-8e84-6cfa88d15e9e",
                "executedAt": "2025-12-01T09:36:59.8654854+00:00",
                "status": "Executed",
                "amount": 1.00,
                "currency": "MDL",
                "type": "MMC",
                "providerType": "MMC",
                "referenceNumber": "533509726066",
                "mcc": "NONE",
                "orderId": "ORD-1764581774756",
                "terminalId": "0149587",
                "refundedAmount": 0.00,
                "requestedRefundAmount": 0.00
            },
            {
                "paymentIntentId": "aa794636-f9dd-4dce-838b-53072b6a939f",
                "isRefundable": true,
                "partialRefundAvailable": true,
                "paymentEntryPoint": "Checkout",
                "refundableAmount": 1.00,
                "paymentId": "0db0f4d7-b23f-40fc-9250-0abacb7bf859",
                "executedAt": "2025-12-01T09:36:01.349707+00:00",
                "status": "Executed",
                "amount": 1.00,
                "currency": "MDL",
                "type": "MIA",
                "providerType": "QR",
                "senderName": "John D.",
                "senderIban": "MD86AG000000022515022502",
                "referenceNumber": "653D3DA8AD17645",
                "mcc": "7399",
                "orderId": "ORD-1764581547938",
                "refundedAmount": 0.00,
                "requestedRefundAmount": 0.00,
                "note": "Test payment"
            }
        ],
        "totalCount": 8
    },
    "ok": true
}
```

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

### Response formats for payment capture

Source: https://docs.maibmerchants.md/e-commerce/two-step-payment/payment-capture

Example responses for successful and failed capture requests.

```json
{
"result": {
"payId": "f16a9006-128a-46bc-8e2a-77a6ee99df75",
"orderId": "123",
"status": "OK",
"statusCode": "000",
"statusMessage": "Approved",
"confirmAmount": 10.25
},
"ok": true
}
```

```json
{
    "errors": [
        {
            "errorCode": "12001",
            "errorMessage": "Parameter 'confirmAmount' is invalid",
            "errorArgs": {
                "parameter": "confirmAmount"
            }
        }
    ],
    "ok": false
}
```

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

### GET /v2/rtp - List all payment requests

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

Retrieves a list of all payment requests.

```APIDOC
## GET /v2/rtp

### Description
Lists all payment requests.

### Method
GET

### Endpoint
/v2/rtp

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter payment requests by status (e.g., "PENDING", "COMPLETED").
- **limit** (integer) - Optional - The maximum number of payment requests to return.
- **offset** (integer) - Optional - The number of payment requests to skip.

### Response
#### Success Response (200)
- **payment_requests** (array) - A list of payment request objects.
  - **id** (string) - The unique identifier of the payment request.
  - **status** (string) - The status of the payment request.
  - **amount** (number) - The amount of the payment request.
  - **currency** (string) - The currency of the payment request.

#### Response Example
{
  "payment_requests": [
    {
      "id": "req_abc123xyz",
      "status": "COMPLETED",
      "amount": 100.50,
      "currency": "USD"
    },
    {
      "id": "req_def456uvw",
      "status": "PENDING",
      "amount": 50.00,
      "currency": "EUR"
    }
  ]
}
```

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

### Successful Payment Response Example

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

Represents a successful API response containing payment intent details and status information.

```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
}
```

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

### Sorted Result Data Example

Source: https://docs.maibmerchants.md/e-commerce/notifications-on-callback-url

This JSON shows the 'result' object's parameters sorted alphabetically by key, as required for signature generation.

```json
"amount" => 10.25,
"approval" => "327593",
"cardNumber" => "510218******1124",
"currency" => "MDL",
"orderId" => "123",
"payId" => "f16a9006-128a-46bc-8e2a-77a6ee99df75",
"rrn" => "331711380059",
"status" => "OK",
"statusCode" => "000",
"statusMessage" => "Approved",
"threeDs" => "AUTHENTICATED"
```

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

### GET /checkouts

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

Retrieves a list of checkout sessions with options for filtering, sorting, and pagination.

```APIDOC
## GET /checkouts

### Description
Retrieves a list of checkout sessions. Supports filtering by status and currency, and allows for sorting and pagination.

### Method
GET

### Endpoint
/checkouts

### Query Parameters
- **status** (string) - Optional - Filters checkouts by their status (e.g., `Completed`).
- **currency** (string) - Optional - Filters checkouts by currency (e.g., `MDL`).
- **count** (integer) - Optional - The number of items to return per page. Defaults to 10.
- **offset** (integer) - Optional - The number of items to skip for pagination. Defaults to 0.
- **sortBy** (string) - Optional - Field to sort results by (e.g., `createdAt`, `amount`).
- **order** (string) - Optional - Sort direction (`asc` or `desc`). Defaults to `desc`.

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

### Response
#### Success Response (200)
- **result** (object) - Operation result container.
  - **result.items** (array<object>) - List of checkout sessions.
  - **result.count** (integer) - Number of items returned.
  - **result.totalCount** (integer) - Total number of items available.
- **ok** (boolean) - Indicates successful request execution.
- **errors** (array) - List of validation or processing errors, if any.

#### Response Example
```json
{
  "result": {
    "items": [
      {
        "id": "chk_123",
        "amount": 1000,
        "currency": "MDL",
        "status": "Completed",
        "createdAt": "2023-10-27T10:00:00Z"
      }
    ],
    "count": 1,
    "totalCount": 5
  },
  "ok": true,
  "errors": []
}
```
```

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

### Card deletion response examples

Source: https://docs.maibmerchants.md/e-commerce/deleting-the-card-from-maib-ecomm

JSON response structures for successful card deletion and error handling scenarios.

```json
{
"result": {
"billerId": "t78i8006-458a-46bc-9e0a-89a6ee11df68",
"status": "OK"
},
"ok": "true"
}
```

```json
{
    "errors": [
        {
            "errorCode": "13003",
            "errorMessage": "Biller ID 'f16a9006-128a-46bc-8e2a-77a6ee99df75' not found",
            "errorArgs": {
                "billerId": "f16a9006-128a-46bc-8e2a-77a6ee99df75"
            }
        }
    ],
    "ok": false
}
```

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

### Direct Payment Request JSON

Source: https://docs.maibmerchants.md/e-commerce/direct-payment

Example JSON body for a POST request to the /v1/pay endpoint.

```json
{
"amount": 10.25,
"currency": "EUR",
"clientIp": "135.250.245.121",
"language": "en",
"description": "Description",
"clientName": "Customer Name",
"email": "customer@gmail.com",
"phone": "069123456",
"orderId": "123",
"delivery": 1.25,
"items": [
{
"id": "10",
"name": "Product 1",
"price": 2.50,
"quantity": 2
},
{
"id": "11",
"name": "Product 2",
"price": 4,
"quantity": 1
}
],
"callbackUrl": "https://example.com/callback",
"okUrl": "https://example.com/ok",
"failUrl": "https://example.com/fail"
}
```

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

### GET /merchant-callback (Browser Redirect)

Source: https://docs.maibmerchants.md/checkout/api-reference/callback-notifications

Endpoint for handling the user redirect after a checkout session completes.

```APIDOC
## GET /merchant-callback

### Description
Redirects the user back to the merchant page after a checkout session completes (success or fail).

### Method
GET

### Parameters
#### Query Parameters
- **checkoutId** (string) - Required - Id of the checkout session
- **checkoutStatus** (string) - Required - Status of checkout - Completed or Failed
- **orderId** (string) - Required - Merchant provider order Id for associated checkout session
```

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

### Base64 Encoded Signature Example

Source: https://docs.maibmerchants.md/e-commerce/notifications-on-callback-url

The final signature is obtained by Base64 encoding the SHA256 hash. This value should match the 'signature' parameter in the notification.

```text
5wHkZvm9lFeXxSeFF0ui2CnAp7pCEFSNmuHYFYJlC0s=
```

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

### Generate Access Token with Project ID and Secret

Source: https://docs.maibmerchants.md/e-commerce/access-token-generation

Use this cURL command to generate an initial access token by providing your Project ID and Project Secret. Ensure the Content-Type is set to application/json.

```bash
curl --location --request POST "https://api.maibmerchants.md/v1/generate-token" \
    --header 'Content-Type: application/json' \
    --data-raw '{
    "projectId": "8508706",
    "projectSecret": "60462913-da44-47fa-8c82-146b676729b9"
    }'
```

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

### Simulate Accept (Sandbox only)

Source: https://docs.maibmerchants.md/request-to-pay/getting-started/endpoints-overview

Simulates the acceptance of an RTP request in the sandbox environment. This triggers a callback and allows developers to test the complete flow without real payments.

```APIDOC
## POST /v2/rtp/{id}/test-accept

### Description
Simulates the acceptance of an RTP request in the sandbox environment. This triggers a callback and allows developers to test the complete flow without real payments.

### Method
POST

### Endpoint
/v2/rtp/{id}/test-accept

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the RTP request to simulate acceptance for.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the RTP request.
- **status** (string) - The updated status of the request, which should be 'Accepted'.

#### Response Example
{
  "id": "rtp_abc123xyz",
  "status": "Accepted"
}
```

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

### Example Request Body for Hosted Checkout Session

Source: https://docs.maibmerchants.md/checkout/api-reference/endpoints/register-a-new-hosted-checkout-session

This JSON object demonstrates a sample request body for creating a hosted checkout session, including amount, currency, order details, payer information, and redirect URLs.

```json
{
  "amount": 50.61,
  "currency": "MDL",
  "orderInfo": {
    "id": "EK123123BV",
    "description": "Order description",
    "date": "2025-11-03T09:28:40.814748+00:00",
    "orderAmount": null,
    "orderCurrency": null,
    "deliveryAmount": null,
    "deliveryCurrency": null,
    "items": [
      {
        "externalId": "243345345",
        "title": "Product1",
        "amount": 50.61,
        "currency": "MDL",
        "quantity": 3,
        "displayOrder": null
      },
      {
        "externalId": "54353453",
        "title": "Product2",
        "amount": 50.61,
        "currency": "MDL",
        "quantity": 2,
        "displayOrder": null
      }
    ]
  },
  "payerInfo": {
    "name": "John D.",
    "email": "test@gmail.com",
    "phone": "+37377382716",
    "ip": "192.168.172.22",
    "userAgent": "Mozilla/5.0"
  },
  "language": "ro",
  "callbackUrl": "https://example.com/path",
  "successUrl": "https://example.com/path",
  "failUrl": "https://example.com/path"
}
```

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

### POST /v2/rtp/{id}/test-accept

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

Simulates the customer accepting an RTP in the sandbox environment to test success flows.

```APIDOC
## POST /v2/rtp/{id}/test-accept

### Description
Simulates the customer accepting an RTP in the sandbox environment. This is used to test success flows end-to-end (including callback delivery) without moving real funds.

### Method
POST

### Endpoint
/v2/rtp/{id}/test-accept

### Parameters
#### Path Parameters
- **rtpId** (string) - Required - RTP unique identifier.

#### Request Body
- **amount** (number) - Required - Payment amount.
- **currency** (string) - Required - Payment currency (MDL).

### Request Example
{
  "amount": 10,
  "currency": "MDL"
}

### Response
#### Success Response (200)
- **result** (object) - Response result object containing rtpId, status, orderId, payId, amount, commission, currency, payerName, payerIban, executedAt, and signature.
- **ok** (boolean) - Request processing status.

#### Response Example
{
  "result": {
    "rtpId": "123e4567-e89b-12d3-a456-426614174000",
    "rtpStatus": "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",
    "signature": "592b6999-fdd0-4fd3-9708-5cb9df590dee"
  },
  "ok": true
}
```

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

### Get Checkout Details Endpoint

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

Use this GET endpoint to retrieve aggregated details for a specific checkout session. Include the checkout session ID in the URL.

```http
GET /v2/checkouts/{id}
```

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

### HTTP GET Request for Payments

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

Use this GET request to retrieve a list of payments. Append your desired query parameters to filter, paginate, and sort the results.

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

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

### POST Payment Request with Access Token

Source: https://docs.maibmerchants.md/e-commerce/access-token-generation

Use this cURL command to initiate a payment. Ensure you replace 'access_token' with your actual token and provide all required fields in the JSON payload.

```bash
curl -X 'POST' \
  'https://api.maibmerchants.md/v1/pay' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer access_token' \
  -H 'Content-Type: application/json' \
  -d '{ \
  "clientIp": "135.250.245.121", \
  "amount": 10.25, \
  "currency": "USD", \
  "description": "Description", \
  "language": "en", \
  "orderId": "123", \
  "clientName": "Client Name", \
  "email": "customer@gmail.com", \
  "phone": "069123456", \
  "delivery": 1.25, \
  "items": [ \
    { \
      "id": "123", \
      "name": "Item", \
      "price": 2.5, \
      "quantity": 2 \
    } \
  ], \
  "callbackUrl": "https://example.com/callback", \
  "okUrl": "https://example.com/ok", \
  "failUrl": "https://example.com/fail" \
}'
```

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

### GET Request to Retrieve Refund Details

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

Use this GET request to retrieve the details of a specific refund using its unique identifier. Include your access token in the Authorization header.

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

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

### GET /v1/pay-info

Source: https://docs.maibmerchants.md/e-commerce/maib-e-commerce-api

Retrieves information about a specific payment.

```APIDOC
## GET /v1/pay-info

### Description
Retrieves status and details for a specific payment.

### Method
GET

### Endpoint
https://api.maibmerchants.md/v1/pay-info
```

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

### GET /v2/checkouts

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

Retrieves a list of all checkout sessions.

```APIDOC
## GET /v2/checkouts

### Description
Retrieve all checkouts.

### Method
GET

### Endpoint
/v2/checkouts
```

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

### GET /v2/payments/refunds/{id}

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

Retrieves details of a specific refund.

```APIDOC
## GET /v2/payments/refunds/{id}

### Description
Retrieve refund details.

### Method
GET

### Endpoint
/v2/payments/refunds/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the refund.
```

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

### GET /v2/payments

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

Retrieves all payments based on provided filters.

```APIDOC
## GET /v2/payments

### Description
Retrieve all payments by filter.

### Method
GET

### Endpoint
/v2/payments
```

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

### POST /checkout

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

Initiates a new checkout session with the specified amount, currency, and callback URLs.

```APIDOC
## POST /checkout

### Description
Initiates a new checkout session for a transaction.

### Method
POST

### Endpoint
/checkout

### Request Body
- **amount** (number) - Required - Checkout amount (major units).
- **currency** (string) - Required - ISO 4217 currency code (e.g., MDL).
- **callbackUrl** (string) - Required - Callback url for this checkout
- **successUrl** (string) - Required - Success url for this checkout
- **failUrl** (string) - Required - Fail url for this checkout

### Request Example
{
  "amount": 100.00,
  "currency": "MDL",
  "callbackUrl": "https://example.com/callback",
  "successUrl": "https://example.com/success",
  "failUrl": "https://example.com/fail"
}
```

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

### Simulate Reject (Sandbox only)

Source: https://docs.maibmerchants.md/request-to-pay/getting-started/endpoints-overview

Simulates the rejection of an RTP request in the sandbox environment. Useful for testing error handling and rejection logic on the merchant side.

```APIDOC
## POST /v2/rtp/{id}/test-reject

### Description
Simulates the rejection of an RTP request in the sandbox environment. Useful for testing error handling and rejection logic on the merchant side.

### Method
POST

### Endpoint
/v2/rtp/{id}/test-reject

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the RTP request to simulate rejection for.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the RTP request.
- **status** (string) - The updated status of the request, which should be 'Rejected'.

#### Response Example
{
  "id": "rtp_abc123xyz",
  "status": "Rejected"
}
```

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

### Example Successful Response

Source: https://docs.maibmerchants.md/checkout/api-reference/endpoints/register-a-new-hosted-checkout-session

This JSON object represents a successful API response for creating a checkout session. It includes the unique checkout ID and the URL for redirecting the payer. The checkout is created in 'WaitingForInit' status.

```json
{
  "result": {
    "checkoutId": "f6d0812a-50ee-47ec-bb3f-d3b3a4dda40d",
    "checkoutUrl": "https://example.com/path"
  },
  "ok": true,
  "errors": null
}
```

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

### GET /v2/payments/{id}

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

Retrieves payment details by its unique identifier.

```APIDOC
## GET /v2/payments/{id}

### Description
Get payment by id.

### Method
GET

### Endpoint
/v2/payments/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the payment.
```

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

### GET /v2/checkouts/{id}

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

Retrieves the details of a specific checkout session.

```APIDOC
## GET /v2/checkouts/{id}

### Description
Get checkout details.

### Method
GET

### Endpoint
/v2/checkouts/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the checkout session.
```

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

### Refund Request with Curl

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

This curl command demonstrates how to initiate a refund for an RTP payment. Ensure you replace `{{access_token}}` with your actual token and provide a valid `payId`.

```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"}'
```

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

### POST /v1/pay

Source: https://docs.maibmerchants.md/e-commerce/maib-e-commerce-api

Initiates a direct payment transaction.

```APIDOC
## POST /v1/pay

### Description
Processes a direct payment request. The merchant sends transaction data, and the API returns a payUrl for customer redirection.

### Method
POST

### Endpoint
https://api.maibmerchants.md/v1/pay
```

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

### One-click payment request JSON

Source: https://docs.maibmerchants.md/e-commerce/one-click-payments/execute-one-click-payment

Example payload for the execute-oneclick API endpoint.

```json
{
"billerId": "t78i8006-458a-46bc-9e0a-89a6ee11df68",
"clientIp": "135.250.245.121",
"language": "en",
"amount": 6.25,
"currency": "EUR",
"description": "Description",
"orderId": "123",
"delivery": 1.25,
"items": [
{
"id": "10",
"name": "Product 1",
"price": 2.50,
"quantity": 2
}
],
"callbackUrl": "https://example.com/callback",
"okUrl": "https://example.com/ok",
"failUrl": "https://example.com/fail"
}
```

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

### POST /checkout

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

Initiates a new checkout session with the specified amount, currency, and redirection URLs.

```APIDOC
## POST /checkout

### Description
Initiates a new checkout session.

### Method
POST

### Endpoint
/checkout

### Request Body
- **amount** (number) - Required - Checkout amount (major units).
- **currency** (string) - Required - ISO 4217 currency code (e.g., MDL).
- **callbackUrl** (string) - Required - Callback url for this checkout
- **successUrl** (string) - Required - Success url for this checkout
- **failUrl** (string) - Required - Fail url for this checkout

### Request Example
{
  "amount": 100.00,
  "currency": "MDL",
  "callbackUrl": "https://example.com/callback",
  "successUrl": "https://example.com/success",
  "failUrl": "https://example.com/fail"
}
```

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

### GET /merchants/records

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

Retrieve merchant records filtered by various timestamp criteria.

```APIDOC
## GET /merchants/records

### Description
Retrieve a list of merchant records filtered by expiration, cancellation, or failure timestamps.

### Method
GET

### Endpoint
/merchants/records

### Parameters
#### Query Parameters
- **expiresAtFrom** (string, date-time) - Optional - Return records expiring after this timestamp.
- **expiresAtTo** (string, date-time) - Optional - Return records expiring before this timestamp.
- **cancelledAtFrom** (string, date-time) - Optional - Return records cancelled after this timestamp.
- **cancelledAtTo** (string, date-time) - Optional - Return records cancelled before this timestamp.
- **failedAtFrom** (string, date-time) - Optional - Return records failed after this timestamp.
```

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

### GET /websites/maibmerchants_md

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

Retrieves a list of merchant records based on specified criteria.

```APIDOC
## GET /websites/maibmerchants_md

### Description
Retrieves a list of merchant records. You can filter the results by payer email, payer phone, payer IP, and creation date range.

### Method
GET

### Endpoint
/websites/maibmerchants_md

### Query Parameters
- **payerEmail** (string) - Optional - Payer email.
- **payerPhone** (string) - Optional - Payer phone.
- **payerIp** (string) - Optional - Payer IP.
- **createdAtFrom** (string (date-time)) - Optional - Return records created after this timestamp.
- **createdAtTo** (string (date-time)) - Optional - Return records created before this timestamp.

### Response
#### Success Response (200)
- **payerEmail** (string) - Payer email.
- **payerPhone** (string) - Payer phone.
- **payerIp** (string) - Payer IP.
- **createdAt** (string (date-time)) - Timestamp of record creation.

#### Response Example
{
  "example": "[\n  {\n    \"payerEmail\": \"john.doe@example.com\",\n    \"payerPhone\": \"123-456-7890\",\n    \"payerIp\": \"192.168.1.1\",\n    \"createdAt\": \"2023-10-27T10:00:00Z\"\n  }\n]"
}
```

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

### Simulate RTP Rejection Endpoint

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

Use this POST endpoint in the sandbox environment to simulate a customer rejecting an RTP payment. This helps test your application's reaction to declines.

```http
POST /v2/rtp/{id}/test-reject
```

```http
Authorization: Bearer {access_token}
Content-Type: application/json
```

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

### POST /v1/pay

Source: https://docs.maibmerchants.md/e-commerce/access-token-generation

Initiates a new payment transaction by sending order details, customer information, and callback URLs.

```APIDOC
## POST /v1/pay

### Description
Initiates a payment transaction for a specific order.

### Method
POST

### Endpoint
https://api.maibmerchants.md/v1/pay

### Request Body
- **clientIp** (string) - Required - The IP address of the client.
- **amount** (number) - Required - The total amount of the transaction.
- **currency** (string) - Required - The currency code (e.g., USD).
- **description** (string) - Optional - Description of the payment.
- **language** (string) - Optional - Language code for the payment interface.
- **orderId** (string) - Required - Unique identifier for the order.
- **clientName** (string) - Optional - Name of the customer.
- **email** (string) - Optional - Customer email address.
- **phone** (string) - Optional - Customer phone number.
- **delivery** (number) - Optional - Delivery cost.
- **items** (array) - Optional - List of items purchased.
- **callbackUrl** (string) - Optional - URL for server-to-server notifications.
- **okUrl** (string) - Optional - URL to redirect on success.
- **failUrl** (string) - Optional - URL to redirect on failure.

### Request Example
{
  "clientIp": "135.250.245.121",
  "amount": 10.25,
  "currency": "USD",
  "description": "Description",
  "language": "en",
  "orderId": "123",
  "clientName": "Client Name",
  "email": "customer@gmail.com",
  "phone": "069123456",
  "delivery": 1.25,
  "items": [
    {
      "id": "123",
      "name": "Item",
      "price": 2.5,
      "quantity": 2
    }
  ],
  "callbackUrl": "https://example.com/callback",
  "okUrl": "https://example.com/ok",
  "failUrl": "https://example.com/fail"
}
```

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

### GET /v2/checkouts

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

Retrieves a list of checkout sessions based on provided query parameters.

```APIDOC
## GET /v2/checkouts

### Description
Retrieves checkout sessions. You can filter the results by checkout ID, merchant order ID, or current checkout status.

### Method
GET

### Endpoint
/v2/checkouts

### Parameters
#### Query Parameters
- **id** (string/UUID) - Optional - Filter by checkout ID.
- **orderId** (string) - Optional - Filter by merchant order ID.
- **status** (string) - Optional - Checkout status. Possible values: WaitingForInit, Initialized, PaymentMethodSelected, Completed, Expired, Abandoned, Cancelled, Failed.
```

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

### Response for Authentication Token

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

This is an example of a successful response containing the access token, its expiration time, and type. The accessToken should be used in the Authorization header for subsequent requests.

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

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

### GET /payments

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

Retrieves a list of payments with their associated refund capabilities and status details.

```APIDOC
## GET /payments

### Description
Retrieves a list of payment transactions including details on refundability and payment entry points.

### Method
GET

### Endpoint
/payments

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates whether the request was processed successfully.
- **errors** (array | null) - List of errors, if the request failed.
- **result** (object) - Contains the list of payment items and total count.

#### Response Example
{
    "result": {
        "items": [
            {
                "paymentIntentId": "9783b6f8-1173-440c-b387-8d18938c972a",
                "isRefundable": true,
                "partialRefundAvailable": true,
                "paymentEntryPoint": "Checkout",
                "refundableAmount": 1.00,
                "paymentId": "265b0bb5-d484-40f2-8e84-6cfa88d15e9e",
                "executedAt": "2025-12-01T09:36:59.8654854+00:00",
                "status": "Executed",
                "amount": 1.00,
                "currency": "MDL",
                "type": "MMC",
                "providerType": "MMC",
                "referenceNumber": "533509726066",
                "mcc": "NONE",
                "orderId": "ORD-1764581774756",
                "terminalId": "0149587",
                "refundedAmount": 0.00,
                "requestedRefundAmount": 0.00
            }
        ],
        "totalCount": 8
    },
    "ok": true
}
```

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

### Register card with amount parameter

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

JSON request body for registering a card while simultaneously debiting a specified amount from the customer's account.

```json
{
"billerExpiry": "1225",
"amount": 6.25,
"currency": "EUR",
"clientIp": "135.250.245.121",
"language": "en",
"description": "Description",
"email": "customer@gmail.com",
"phone": "069123456",
"orderId": "123",
"delivery": 1.25,
"items": [
{
"id": "10",
"name": "Product 1",
"price": 2.50,
"quantity": 2
}
],
"callbackUrl": "https://example.com/callback",
"okUrl": "https://example.com/ok",
"failUrl": "https://example.com/fail"
}
```

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

### Refund Response Payloads

Source: https://docs.maibmerchants.md/e-commerce/payment-refund

Example responses for successful refund processing and error handling scenarios.

```json
{
"result": {
"payId": "f16a9006-128a-46bc-8e2a-77a6ee99df75",
"orderId": "123",
"status": "OK",
"statusCode": "400",
"statusMessage": "Accepted",
"refundAmount": 10.25
},
"ok": true
}
```

```json
{
    "errors": [
        {
            "errorCode": "12001",
            "errorMessage": "Parameter 'refundAmount' is invalid",
            "errorArgs": {
                "parameter": "refundAmount"
            }
        }
    ],
    "ok": false
}
```