Docs · API reference

E-comm API

The E-comm API powers websites, hosted checkouts, embed checkout, payment links and third-party plugins on miaPOS. Token authentication, payment creation, status queries, Request-to-Pay push, signed merchant callback, public-key retrieval.

AudienceDeveloper

DifficultyIntermediate

Versionv1

Updated2026-06-25

Interactive reference

Full Redoc spec →

Complete request and response schemas, examples, error catalogues. Rendered from the OpenAPI spec of the E-comm service.

Open reference →

Public integration repo

Protocol overview →

Long-form protocol description in the public integration repository — request/response walk-throughs, JSON examples, plugin patterns. Kept in sync by the backend team.

Open on GitHub →

Overview

The E-comm API is the merchant-facing interface for online payments. A merchant backend authenticates with client credentials, calls POST /ecomm/api/v1/pay with an amount and a callback URL, redirects the buyer to the returned checkout URL, and waits for a signed callback. Status can be polled at any time via GET /ecomm/api/v1/payment/{paymentId}. Refunds and Request-to-Pay are optional secondary flows on top of the same authenticated session.

The same API also powers the plugins (WooCommerce, OpenCart, CS-Cart) and the embed checkout snippet — the embed track adds an Idempotency-Key header on POST /pay plus a public no-JWT GET /checkout/{paymentId} for the browser widget. See Embed checkout guide for that surface.

Base URL & environments

Every partner integration uses its own base URL. Sandbox and production hosts and merchant client credentials are issued per partner during onboarding — request sandbox access from sales. Public documentation intentionally does not list host names or credentials. Once you receive the base URL, you can also try the interactive demo — the demo host is provided together with your sandbox credentials.

Authentication

Get a JWT access token by calling POST /ecomm/api/v1/token with your client credentials. Pass the token as Authorization: Bearer <accessToken> on every business call. Exchange refresh tokens for new access tokens with POST /ecomm/api/v1/token/refresh. The GET /checkout/{paymentId} endpoint is intentionally public (no JWT) so a browser widget can render checkout state without a merchant secret in the browser.

Endpoints

Authentication

2 endpoints

Issue and refresh JWT access tokens for merchant backend calls.

POST/ecomm/api/v1/tokenclient credentials → access + refresh

POST/ecomm/api/v1/token/refreshrefresh token → new pair

Payment

4 endpoints

Create a payment, read its state, render checkout for the browser widget, refund a completed payment.

POST/ecomm/api/v1/paycreate payment · Idempotency-Key for embed

GET/ecomm/api/v1/payment/{paymentId}read payment state

GET/ecomm/api/v1/checkout/{paymentId}public, no JWT — embed widget

POST/ecomm/api/v1/payment/{paymentId}/refundrefund a completed payment

Request-to-Pay

1 endpoint

Push a payment request directly to the buyer's banking app (rail-dependent — availability differs per market).

POST/ecomm/api/v1/request-to-pay/directRTP push

Public key

1 endpoint

Fetch the RSA public key used to verify callback signatures. Rotate on your side by re-fetching after signature verification errors — the key can change without notice.

GET/api/v1/public-keyRSA public key (Base64)

Callback protocol

When a payment reaches a terminal state (SUCCESS, FAILED, refunded), the E-comm service POSTs a JSON body to the callbackUrl the merchant supplied on POST /pay. The payload has two top-level fields — result and signature. The signature is an RSA-SHA256 signature over the result object, produced by miaPOS with its private key and verifiable with the public key from GET /api/v1/public-key. Full algorithm and language examples: Signature verification.

POST https://your-shop.example/miapos/callback
Content-Type: application/json

{
  "result": {
    "terminalId": "123456",
    "orderId": "order123",
    "paymentId": "bc340d13-7411-4785-a083-b594b1384eb5",
    "status": "SUCCESS",
    "amount": 145.25,
    "currency": "MDL",
    "paymentDate": "2024-05-20T16:32:28+03:00",
    "swiftMessageId": "swift123",
    "swiftPayerBank": "SomeBank"
  },
  "signature": "base64_encoded_signature"
}

Verify every callback before you fulfil the order. Anyone can POST to your callbackUrl. The signature field is what proves the payload came from miaPOS. Do not rely on IP allow-listing; do rely on RSA verification.

Schemas

Full request and response schemas — including enum values and per-field descriptions — are published in the interactive Redoc reference. Long-form protocol description with request/response walk-throughs and plugin patterns is in the public integration repo on GitHub.

Errors

All endpoints return errors in the standard envelope. See Errors for the full catalogue and the mapping from HTTP status to internal error code.